THEMIS analysis tools

Coordinate transforms

The THEMIS mission defines coordinate systems related to the spacecraft spin axes (one spinning with the spacecraft, the other referenced to the sun direction). The two ARTEMIS probes (aka THEMIS-B and THEMIS-C) are in lunar orbits, so so a few selenocentric coordinate transforms are required.

DSL (Despun Solar L-(angular momentum) vector)
SSL (Spinning Solar L-(angular momentum) vector)
SSE (Selenocentric Solar Ecliptic)
SEL (Selenographic)

The GSE system serves as a bridge between the THEMIS-specific and selenocentric coordinates, and the set of coordinate systems supported by pyspedas.cotrans().

Each of these transforms requires support data to be loaded from various THEMIS datasets.

Transformations

pyspedas.projects.themis.dsl2gse(name_in: str, name_out: str, isgsetodsl: bool = False, ignore_input_coord: bool = False, probe: str = None, use_spinaxis_corrections: bool = True) → int[source]

Transform dsl to gse.

Parameters:

name_in (str) – Name of input tplot variable (e.g. ‘tha_fgl_dsl’)
name_out (str) – Name of output tplot variable (e.g. ‘tha_fgl_gse’)
isgsetodsl (bool) – If False (default) then DSL to GSE. If True, then GSE to DSL.
ignore_input_coord (bool) – if False (default), do not check the input coordinate system if True, fail and return 0 if input coordinate does not match the requested transform.
probe (str) – Usually optional, if the probe can be inferred from the input variable name (e.g. tha_xxx_yyy). Otherwise, one of [‘a’,’b’,’c’,’d’,’e’,’f’]
use_spinaxis_corrections (bool) – If True (default), use spin axis corrections from V03 state CDFs when available. If False, use the uncorrected spin axis variables.

Return type:

1 for successful completion.

pyspedas.projects.themis.gse2sse(name_in: str, name_out: str, isssetogse: bool = False, variable_type: str = 'Other', ignore_input_coord: bool = False, rotation_only: bool = False) → int[source]

Transform gse to sse.

Parameters:

name_in (str) – Name of input tplot variable (e.g. ‘tha_fgl_dsl’)
name_out (str) – Name of output tplot variable (e.g. ‘tha_fgl_sse’)
isssetogse (bool) – If False (default), then GSE to SSE. If True, then SSE to GSE.
ignore_input_coord (bool) – if False (default), do not check the input coordinate system if True, fail and return 0 if input coordinate does not match the requested transform.
variable_type (str) –

A string describing the type of data being transformed. If value is “pos” or “vel”, the appropriate
offsets (lunar position or velocity) are applied during the transform. Any other value will be treated as equivalent to rotate_only=True.
rotation_only (bool) –

if False (default), assume input variable is a position with units of km, and apply the earth-moon
offset before rotating to SSE, or after rotating to GSE

if True, assume the input variable is a velocity or some other quantity that does not need the earth-moon
translation step

Return type:

1 for sucessful completion.

pyspedas.projects.themis.sse2sel(name_in: str, name_out: str, isseltosse: bool = False, ignore_input_coord: bool = False) → int[source]

Transform sse to sel.

Parameters:

name_in (str) – Name of input tplot variable (e.g. ‘tha_state_pos_sse’ or ‘tha_state_pos_sel’)
name_out (str) – Name of output tplot variable (e.g. ‘tha_fgl_sse’)
isseltosse (bool) – If False (default), then SSE to SEL. If True, then SEL to SSE.
ignore_input_coord (bool) – if False (default), do not check the input coordinate system if True, fail and return 0 if input coordinate does not match the requested transform.
variable_type (str) –

A string describing the type of data being transformed. If value is “pos” or “vel”, the appropriate
offsets (lunar position or velocity) are applied during the transform. Any other value will be treated as equivalent to rotate_only=True.
rotate_only (bool) –

if False (default), assume input variable is a position with units of km, and apply the earth-moon
offset before rotating to SEL, or after rotating to SSE #TODO: please check

if True, assume the input variable is a velocity or some other quantity that does not need the earth-moon
translation step

Return type:

1 for sucessful completion.

pyspedas.projects.themis.ssl2dsl(name_in: str, name_out: str, isdsltossl: bool = False, ignore_input_coord: bool = False, probe: str = None, use_spinphase_correction: bool = True, eclipse_correction_level: int = 0) → int[source]

Transform ssl to dsl.

Parameters:

name_in (str) – Name of input tplot variable (e.g. ‘tha_fgl_ssl’)
name_out (str) – Name of output tplot variable (e.g. ‘tha_fgl_dsl’)
isdsltossl (bool) – If 0 (default) then SSL to DSL. If 1, then DSL to SSL.
ignore_input_coord (bool) – if False (default), then fail and return 0 if input coordinate system does not match requested transform if True, do not check input coordinate system.
probe (str) – Usually optional, if the variable name is prefixed with ‘tha’, ‘thb’, etc. Otherwise, one of [‘a’,’b’,’c’,’d’,’e’,’f’]
use_spinphase_correction (bool) – If True (default), use spin phase corrections from V03 STATE CDF if False, omit this
eclipse_correction_level (int) – Specify which of the three available spin models to use for this transform 0: (default) No eclipse correction 1: Eclipse corrections for waveform data 2: Eclipse corrections for particles and spin fits (includes additional angular offset)

Return type:

1 for successful completion.

Electron density estimates from spacecraft potential

pyspedas.projects.themis.scpot2dens(scpot, scptime, Te, Tetime, dens_e, dens_e_time, dens_i, dens_i_time, probe='c')[source]

Calculates spacecraft potential derived density.

This function processes spacecraft potential data (scpot), alongside interpolated electron temperature (Te), electron density (dens_e), and ion density (dens_i) data, to calculate electron and ion densities at specific time points (scptime). It interpolates Te, dens_e, and dens_i data to align with the scpot time base, It accounts for specific bias changes and offset matrices.

Parameters:

scpot (array_like) – Spacecraft potential data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peer_sc_pot’)
scptime (array_like) – The time base of scpot.
Te (array_like) – Electron temperature data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peer_avgtemp’)
Tetime (array_like) – The time base of Te.
dens_e (array_like) – Electron density data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peer_density’)
dens_e_time (array_like) – The time base for dens_e.
dens_i (array_like) – Ion density data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peir_density’)
dens_i_time (array_like) – The time base for dens_i.
probe_in (int or str, default 'c') – Identifier for the probe being used for measurements. Valid values are ‘a’, ‘b’, ‘c’, ‘d’, ‘e’.

Returns:

dens – The calculated densities at scpot time points. Returns None if the probe is invalid, if dens_e and dens_i are either not present or do not have at least two elements (indicating insufficient data for interpolation), or if the densities remain unmodified due to a lack of valid data.

Return type:

ndarray

Notes

Incorporates probe-specific adjustments through bias changes and offset matrices, applying different calculation methodologies across distinct plasma conditions and time periods.
Invalid inputs or insufficient density data lead to an early termination of the function with None as return.

Examples

Given a specific time range, the following example demonstrates how to load THEMIS spacecraft data for probe ‘c’, extract density, spacecraft potential, and temperature data, then calculate the plasma density from spacecraft potential using the scpot2dens function.

>>> import pyspedas
>>> import pyspedas
>>> from pyspedas.projects.themis import scpot2dens
>>>
>>> # Define the time range for which to load the data
>>> trange = ['2007-7-20/17:00:00', '2007-7-20/17:20:00']

>>> # Load THEMIS ESA data for probe 'c' within the specified time range
>>> pyspedas.projects.themis.esa(trange=trange,
>>>                    probe='c',
>>>                    varnames=['thc_peer_density', 'thc_peir_density', 'thc_peer_sc_pot', 'thc_peer_avgtemp'],
>>>                    level='l2')
>>>
>>> # Retrieve electron density
>>> dens_e_time, dens_e = get_data('thc_peer_density')
>>>
>>> # Retrieve ion density
>>> dens_i_time, dens_i = get_data('thc_peir_density')
>>>
>>> # Retrieve spacecraft potential
>>> sc_pot_time, sc_pot = get_data('thc_peer_sc_pot')
>>>
>>> # Retrieve electron temperature
>>> Te_time, Te = get_data('thc_peer_avgtemp')
>>>
>>> # Calculate the plasma density from spacecraft potential
>>> Npot = scpot2dens(sc_pot, sc_pot_time, Te, Te_time, dens_e, dens_e_time, dens_i, dens_i_time, 'c')

References

Based on IDL function THM_SCPOT2DENS.PRO by W.M.Feuerstein, 2009-05-18, with updates and bug fixes in subsequent versions. SPEDAS/projects/themis/common/thm_scpot2dens.pro

pyspedas.projects.themis.scpot2dens_nishimura(scpot, scptime, vth, vth_time, dens_i, dens_i_time, pos_gsm, pos_gsm_time, probe='a', ion_density_threshold=40, no_interp=False)[source]

Calculates spacecraft potential derived density, using Nishimura formula, as in the IDL SPEDAS SCPOT2DENS_OPT_N

This function processes spacecraft potential data (scpot), alongside interpolated electron thermal velocity (Vth), ion density (dens_i) data and spacecraft position (pos), to calculate electron and ion densities at specific time points (scptime). It interpolates all data to the scpot time base. If no_interp is set, only the position data is interpolated. Ion density is used to flag bad data; the calculation is expected to fail for high Ion density (Gt 40cm^(-3))

Parameters:

scpot (array_like) – Spacecraft potential data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peer_sc_pot’)
scptime (array_like) – The time base of scpot.
vth (array_like) – Electron thermal velocity data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peer_vthermal’)
vth_time (array_like) – The time base of vth.
dens_i (array_like) – Ion density data, expected as a 1-D array. (call pyspedas.projects.themis.esa, DATATYPE = ‘peir_density’)
dens_i_time (array_like) – The time base for dens_i.
pos_gsm (array_like) – Spacecraft position in GSM (or any earth-centered coordinates.).
pos_gsm_time (array_like) – The time base of pos_gsm
probe (int or str, default 'a') – Identifier for the probe being used for measurements. Valid values are ‘a’, ‘b’, ‘c’, ‘d’, ‘e’.
ion_density_threshold (Scalar, int or float, default 40) – Threshold for ion density, above which, data is set to ‘NaN’
no_interp (Boolean) – If True, then all of the probe ESA arrays are the same (typical for THEMIS ESA data), no need to interpolate times. Position data is always interpolated

Returns:

dens – The calculated densities at scpot time points. Returns None if the probe is invalid, if dens_i is not present or do not have at least two elements (indicating insufficient data for interpolation, for no_interp=False)

Return type:

ndarray

Notes

Incorporates probe-specific adjustments
Invalid inputs or insufficient data lead to an early termination of the function with None as return.

Examples

Given a specific time range, the following example demonstrates how to load THEMIS spacecraft data for probe ‘a’, extract density, spacecraft potential, and velocity data, then calculate the plasma density from spacecraft potential using the scpot2dens function.

>>> import pyspedas
>>> from pyspedas.projects.themis import scpot2dens_nishimura
>>> from pyspedas import get_data
>>>
>>> # Define the time range for which to load the data
>>> trange = ['2017-07-20', '2017-07-20']
>>>
>>> # Load THEMIS ESA data for probe 'a' within the specified time range
>>> pyspedas.projects.themis.esa(trange=trange,
>>>                     probe='a',
>>>                     varnames=['tha_peir_density', 'tha_peer_sc_pot', 'tha_peer_vthermal'],
>>>                     level='l2')
>>>
>>> # Load position data
>>> pyspedas.projects.themis.state(probe='a', trange=trange)
>>> pos_data = get_data('tha_pos_gsm')
>>> pos_gsm_time = pos_data.times
>>> pos_gsm = pos_data.y
>>>
>>> # Retrieve ion density
>>> dens_i_time, dens_i = get_data('tha_peir_density')
>>>
>>> # Retrieve spacecraft potential
>>> sc_pot_time, sc_pot = get_data('tha_peer_sc_pot')
>>>
>>> # Retrieve electron velocity
>>> vth_time, vth = get_data('tha_peer_vthermal')
>>>
>>> # Calculate the plasma density from spacecraft potential, ESA datatimes are all the same
>>> Npot = scpot2dens_nishimura(sc_pot, sc_pot_time, vth, vth_time, dens_i, dens_i_time, pos_gsm, pos_gsm_time, probe='a', no_interp=True)

References

Based on IDL function THM_SCPOT2DENS_OPT_N.PRO by Toshi Nishimura@UCLA/NAGOYA, 05/02/2009 (toshi at atmos.ucla.edu) SPEDAS/projects/themis/common/thm_scpot2dens_opt_n.pro