MMS analysis tools

Coordinate transforms

The MMS mission defines several coordinate systems: BCS, DBCS, DMPA, SMPA, and DSL. The MMS MEC data products contain quaternions enabling interconversion between these systems and the geophysical systems GSE, GSE2000, GSM, SM, GEO, ECI, and J2000.

The MMS MEC load routine must be called to load the quaternion data before performing coordinate transformations.

pyspedas.projects.mms.mec(trange=['2015-10-16', '2015-10-17'], probe='1', data_rate='srvy', level='l2', datatype='epht89q', varformat=None, varnames=[], suffix='', get_support_data=False, time_clip=False, no_update=False, available=False, notplot=False, latest_version=False, major_version=False, min_version=None, cdf_version=None, spdf=False, always_prompt=False)

Load the attitude/ephemeris data from the MMS MEC (Mission Ephemeris and Coordinates) files

Parameters:

  • trange (list of str) – time range of interest [start time, end time] with the format ‘YYYY-MM-DD’,’YYYY-MM-DD’] or to specify more or less than a day [‘YYYY-MM-DD/hh:mm:ss’,’YYYY-MM-DD/hh:mm:ss’] Default: [‘2015-10-16’, ‘2015-10-17’]

  • probe (str or list of str) – list of probes, valid values for MMS probes are [‘1’,’2’,’3’,’4’]. Default: ‘1’

  • data_rate (str or list of str) – instrument data rates for MEC include [‘brst’, ‘srvy’]. Default: ‘srvy’

  • level (str) – indicates level of data processing. Default: ‘l2’

  • datatype (str or list of str) – Valid datatypes for MEC are: [‘ephts04d’, ‘epht89q’, ‘epht89d’] Default: ‘epht89q’

  • get_support_data (bool) – Data with an attribute “VAR_TYPE” with a value of “support_data” will be loaded into tplot. Default: False

  • time_clip (bool) – Data will be clipped to the exact trange specified by the trange keyword. Default: False

  • varformat (str) – The file variable formats to load into tplot. Wildcard character “*” is accepted. Default: None (all variables are loaded)

  • varnames (list of str) – List of variable names to load. If list is empyt or not specified, all data variables are loaded) Default: [] (all variables are loaded)

  • suffix (str) – The tplot variable names will be given this suffix. Default: None

  • notplot (bool) – If True, then data are returned in a hash table instead of being stored in tplot variables (useful for debugging, and access to multidimensional data products) Default: False

  • available (bool) – If True, simply return the available data files (without downloading) for the requested parameters Default: False

  • no_update (bool) – Set this flag to preserve the original data. if not set and newer data is found the existing data will be overwritten Default: False

  • cdf_version (str) – Specify a specific CDF version # to load (e.g., cdf_version=’4.3.0’) Default: None

  • min_version (str) – Specify a minimum CDF version # to load Default: None

  • latest_version (bool) – Only grab the latest CDF version in the requested time interval Default: False

  • major_version (bool) – Only open the latest major CDF version (e.g., X in vX.Y.Z) in the requested time interval Default: False

  • always_prompt (bool) – Set this keyword to always prompt for the user’s username and password; useful if you accidentally save an incorrect password, or if your SDC password has changed Default: False

  • spdf (bool) – If True, download the data from the SPDF instead of the SDC Default: False

Notes

The default datatype was changed to ‘epht89q’ on 15Nov2021. There are sometimes issues with creating the Tsyganenko 04 data products, which leads to the ‘epht04d’ files not being available. The ‘epht89d’ files contain the same ephemeris data - the only difference are the data products that rely on the field model.

Returns:

List of tplot variables created.

Return type:

list of str

Example

>>> import pyspedas
>>> from pyspedas import tplot
>>> mec_data = pyspedas.projects.mms.mms_load_mec(trange=['2015-10-16', '2015-10-17'], probe='1')
>>> tplot(['mms1_mec_r_gsm', 'mms1_mec_v_gsm'])

Once the MEC data is loaded, call mms_qcotrans to perform the transforms.

pyspedas.projects.mms.mms_qcotrans(in_name=None, out_name=None, in_coord=None, out_coord=None, probe=None)[source]

Perform coordinate transformations using MMS MEC quaternions.

This routine uses SpacePy to do the quaternion transformation operations.

Parameters:

  • in_name (str or list of str) – Names of Tplot variables of vectors to be transformed

  • out_name (str or list of str) – Names of output variables

  • in_coord (str) – Input coordinate system, valid options: ‘bcs’, ‘dbcs’, ‘dmpa’, ‘smpa’, ‘dsl’, ‘ssl’, ‘gse’, ‘gse2000’, ‘gsm’, ‘sm’, ‘geo’, ‘eci’, ‘j2000’

  • out_coord (str) – Output coordinate system valid options: ‘bcs’, ‘dbcs’, ‘dmpa’, ‘smpa’, ‘dsl’, ‘ssl’, ‘gse’, ‘gse2000’, ‘gsm’, ‘sm’, ‘geo’, ‘eci’, ‘j2000’

  • probe (str) – MMS spacecraft # (must be 1, 2, 3, or 4)

Return type:

List of variables created

Examples

>>> from pyspedas.projects.mms import mec, mms_qcotrans # Import MMS namespace and mms_qcotrans routine
>>> from pyspedas import tplot # Import tplot routine to plot results
>>> mec(trange=['2015-10-16', '2015-10-17'], probe='1')   # Load quaternions, positions, and velocity variables from MEC data, using default datatypes
>>> mms_qcotrans('mms1_mec_v_sm', 'mms1_mec_v_sm_2gse', out_coord='gse') # Transform SM velocity to GSE
>>> tplot(['mms1_mec_v_sm','mms1_mec_v_sm_2gse']) # Plot input and output variables

MMS also provides a routine to transform input data to boundary-normal (LMN) coordinates.

pyspedas.projects.mms.mms_cotrans_lmn(name_in, name_out, gsm=False, gse=False, probe=None, data_rate='srvy')[source]

Tranforms MMS vector fields from GSM coordinates to LMN (boundary-normal) coordinates using the Shue et al., 1998 magnetopause model

Input

name_in: str

Name of the input tplot variable

name_out: str

Name of the output tplot variable

Parameters:

  • gsm (bool) – Flag to indicate the input data are in GSM coordinates

  • gse (bool) – Flag to indicate the input data are in GSE coordinates; note: the input data will be transformed to GSM prior to transforming to LMN

  • probe (str) – Spacecraft probe #; if not specified, the routine attempts to extract from the input variable name

  • data_rate (str) – Data rate of the ephemeris support data to be loaded; default is ‘srvy’

rtype:

Name of the variable containing the data in LMN coordinates.

Particle distribution tools

The mms_part_getspec routine can be used to calculate plasma moments and spectra from 3-D particle distributions.

pyspedas.projects.mms.mms_part_getspec(instrument='fpi', probe='1', species='e', data_rate='fast', trange=None, output=['energy', 'theta', 'phi', 'pa', 'gyro'], units='eflux', energy=None, phi=None, theta=None, pitch=None, gyro=None, mag_name=None, mag_data_rate=None, pos_name=None, sc_pot_name=None, sc_pot_data_rate=None, fac_type='mphigeo', center_measurement=False, spdf=False, correct_photoelectrons=False, internal_photoelectron_corrections=False, disable_photoelectron_corrections=False, zero_negative_values=False, regrid=[32, 16], no_regrid=False, prefix='', suffix='', subtract_bulk=False, vel_name=None, vel_data_rate=None, sdc_units=False)[source]

Generate spectra and moments from 3D MMS particle data

Parameters:

  • trange (list of str) – Time range

  • units (str) –

    Specify units of output variables; must be ‘eflux’ to calculate moments. Valid options:

    'flux'   -  # / (cm^2 * s * sr * eV)
'eflux'  -  eV / (cm^2 * s * sr * eV)  <default>
'df_cm'  -  s^3 / cm^6
'df_km'  -  s^3 / km^6

    Default: ‘eflux’

  • species (str) – Specify the species of the input tplot variable (Default: ‘e’)

  • data_rate (str) – Data rate of the input data (Default: ‘fast’)

  • instrument (str) – Instrument (FPI or HPCA)

  • probe (int or str) – Spacecraft probe # (Default: 1)

  • output (str or list of str) –

    Output variables; options:

    'energy': energy spectrograms
'theta': theta spectrograms
'phi': phi spectrograms
'pa': pitch-angle spectrograms
'gyro': gyro-phase spectrograms
'moments': plasma moments

    Default: [‘energy’, ‘theta’, ‘phi’, ‘pa’, ‘gyro’]

  • energy (list of float) – Energy range [min, max], in eV

  • phi (list of float) – Phi range [min, max], in degrees

  • theta (list of float) – Theta range [min, max], in degrees

  • pitch (list of float) – Pitch-angle range [min, max], in degrees

  • gyro (list of float) – Gyro-angle range [min, max], in degrees

  • mag_name (str) – Tplot variable containing magnetic field data for moments and FAC transformations

  • mag_data_rate (str) – Data rate to use when loading the spacecraft potential data (‘fast’, ‘srvy’ or ‘brst’) If not given, defaults to value of ‘data_rate’.

  • pos_name (str) – Tplot variable containing spacecraft position for FAC transformations. If not given, defaults to ‘mmsN_mec_r_gse’

  • sc_pot_name (str) – If set, overrides default sc_pot variable name constructed from sc_pot_data_rate below. Default: None

  • sc_pot_data_rate (str) – Data rate to use when loading the spacecraft potential data (‘fast’, ‘srvy’ or ‘brst’) If not given, defaults to value of ‘data_rate’.

  • fac_type (str) –

    Field aligned coordinate system variant; options:

    'phigeo'
'mphigeo'
'xgse'

    Default: ‘mphigeo’

  • ### ADDED 4.16.2025, TESTING BULK VELOCITY SUBTRACTION

  • subtract_bulk (bool) – subtract the bulk velocity prior to doing the calculations

  • vel_name (str) – Tplot variable containing velocity data in km/s for use with /subtract_bulk

  • vel_data_rate (str) – Data rate to use when loading the bulk velocity data (‘fast’ or ‘brst’)

  • #################

  • correct_photoelectrons (bool) – Flag to correct FPI data for photoelectrons (defaults to True for FPI electron data - disable with the parameter below)

  • disable_photoelectron_corrections (bool) – Flag to disable FPI photoelectron corrections

  • internal_photoelectron_corrections (bool) – Apply internal photoelectron corrections

  • zero_negative_values (bool) – Turn negative values to 0 after doing the photoelectron corrections (DES)

  • regrid (array of int) – Dimensions for regridded data array (see no_regrid flag below) Default: [32,16]

  • no_regrid (bool) – Flag to disable regridding of data array

  • prefix (str) – Prefix for output tplot variables. Default: ‘’

  • suffix (str) – Suffix for output tplot variables. Default: ‘’

  • sdc_units (bool) – If True, convert moments ptens and qflux values and units to nPa and mW/m^2 respectively, for compatibility with MMS SDC products Default: False

Returns:

Creates tplot variables containing spectrograms and moments

Return type:

None

The mms_part_slice2d routine can be used to visualize 2-D slices through 3-D particle distributions, with several choices of orientation for the slice.