This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/mms/mec

- MMS_LOAD_MEC
  Load the attitude/ephemeris data from the LANL MEC files
- MMS_MEC_FIX_METADATA
  Helper routine for setting metadata of MEC variables
- MMS_MEC_FORMATION_PLOT
  Creates a plot showing the spacecraft formation
- MMS_ORBIT_PLOT
  Creates a plot showing the spacecraft location

# Routine Descriptions

## MMS_LOAD_MEC

[Next Routine] [List of Routines]

     PROCEDURE:
             mms_load_mec

     PURPOSE:
             Load the attitude/ephemeris data from the LANL MEC files

     KEYWORDS:
             trange:       time range of interest [starttime, endtime] 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']
             probes:       list of probes, valid values for MMS probes are ['1','2','3','4'].
                           if no probe is specified the default is probe '1'
             datatype:     valid datatypes include ['ephts04d', 'epht89q', 'epht89d']
                           default is 'epht89q'; note: the default was updated to 'epht89q' on 15Nov2021
                           at the request of the MMS team
             data_rate:    instrument data rates include ['srvy', 'brst']. The default is 'srvy'.

             local_data_dir: local directory to store the CDF files; should be set if
                           you're on *nix or OSX, the default currently assumes Windows (c:\data\mms\)
             source:       specifies a different system variable. By default the MMS mission system
                           variable is !mms
             get_support_data: load support data (defined by support_data attribute in the CDF)
             tplotnames:   names for tplot variables
             no_color_setup: don't setup graphics configuration; use this keyword when you're
                           using this load routine from a terminal without an X server running
             time_clip:    clip the data to the requested time range; note that if you do not use
                           this keyword you may load a longer time range than requested
             no_update:    set this flag to preserve the original data. if not set and newer data is
                           found the existing data will be overwritten
             suffix:       appends a suffix to the end of the tplot variable name. this is useful for
                           preserving original tplot variable.
             varformat:    should be a string (wildcards accepted) that will match the CDF variables
                           that should be loaded into tplot variables
             cdf_filenames:  this keyword returns the names of the CDF files used when loading the data
             cdf_version:  specify a specific CDF version # to load (e.g., cdf_version='4.3.0')
             latest_version: only grab the latest CDF version in the requested time interval
                           (e.g., /latest_version)
             major_version: only open the latest major CDF version (e.g., X in vX.Y.Z) in the requested time interval
             min_version:  specify a minimum CDF version # to load
             cdf_records:  specify a number of records to load from the CDF files.
                           e.g., cdf_records=1 only loads in the first data point in the file
                           This is especially useful for loading S/C position for a single time
             spdf:         grab the data from the SPDF instead of the LASP SDC (only works for public access)
             available:    returns a list of files available at the SDC for the requested parameters
                           this is useful for finding which files would be downloaded (along with their sizes) if
                           you didn't specify this keyword (also outputs total download size)
             versions:     this keyword returns the version #s of the CDF files used when loading the data
             always_prompt: set this keyword to always prompt for the user's username and password;
                           useful if you accidently save an incorrect password, or if your SDC password has changed
             tt2000: flag for preserving TT2000 timestamps found in CDF files (note that many routines in
                           SPEDAS (e.g., tplot.pro) do not currently support these timestamps)

     EXAMPLES:
             to load/plot the S/C position data for probe 3 on 2/20/2016:
             MMS> mms_load_mec, probe=3, trange=['2016-02-20', '2016-02-21']
             MMS> tplot, 'mms3_mec_r_gsm'

     NOTES:
        UPDATETD DETAULT: due to the issue below ("MISSING DATA"), the default datatype was changed
                          to 'epht89q' on 15Nov2021

        MISSING DATA: if the MEC data are missing for a date you suspect should contain data (>30 days ago),
                      try loading the datatype 'epht89d' instead of the default of 'epht04d'.
                      There are sometimes issues with creating the Tsyganenko 04 data products,
                      which leads to the default '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.

        The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC

        Have questions regarding this load routine, or its usage?
              https://groups.google.com/forum/#!forum/spedas

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-11-15 12:00:06 -0800 (Mon, 15 Nov 2021) $
    $LastChangedRevision: 30420 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec/mms_load_mec.pro $

(See projects/mms/mec/mms_load_mec.pro)

## MMS_MEC_FIX_METADATA

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
             mms_mec_fix_metadata

     PURPOSE:
             Helper routine for setting metadata of MEC variables

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-01-12 10:31:13 -0800 (Tue, 12 Jan 2021) $
    $LastChangedRevision: 29593 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec/mms_mec_fix_metadata.pro $

(See projects/mms/mec/mms_mec_fix_metadata.pro)

## MMS_MEC_FORMATION_PLOT

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
           mms_mec_formation_plot

     PURPOSE:
           Creates a plot showing the spacecraft formation
           at a given time

     INPUT:
           time:   string containing the date and time to create
                   the plot for. e.g., 'YYYY-MM-DD/HH:MM'

     KEYWORDS:
           projection:   project the spacecraft positions
                   onto all planes

           xy_projection: project the S/C positions onto the XY plane
           xz_projection: project the S/C positions onto the XZ plane
           yz_projection: project the S/C positions onto the YZ plane

           quality_factor: include the tetrahedron quality factor
           coord: coordinate system of the formation plot; default is GSE
                  valid options are eci, gsm, geo, sm, gse, gse2000
           xyz: a 3 x 3 rotation matrix for rotating position data to an
                arbitrary coordinate system from the coordinate system
                defined by coord
           lmn: a 3 x 3 rotation matrix for rotating position data to an
                LMN coordinate system from the coordinate system
                defined by coord (do not use with xyz keyword)
           sundir: direction of the sun (+x) in the figure (right or left); default is 'right'
                   (+N direction for LMN coordinate)
           independent_axes: by default, the same scale is used for each axis; set this keyword
                to use different scales for the x, y, and z axes
           plotmargin: margin of the figure (default: 0.3)
           sc_size: size of the spacecraft on the figure (default: 3)

     VECTOR KEYWORDS:
       The following keywords allow you to add various types of vectors to the figure, and control the look of the vectors
             bfield_center: add the average B-field vector to the center of the figure (average of all 4 spacecraft; GSE or GSM coordinates only)
             bfield_sc: add the B-field vector at each spacecraft (GSE or GSM coordinates only)
             bfield_color: change the color of the B-field vector (default: red)
             fgm_data_rate: B-field data rate to use (default: srvy)
             fgm_normalization: normalization factor of the B-field vector (allows you to scale down/up the vector; default: 1)

             dis_center: add the average DIS bulk velocity vector to the center of the figure (average of all 4 spacecraft; GSE coordinates only)
             des_center: add the average DES bulk velocity vector to the center of the figure (average of all 4 spacecraft; GSE coordinates only)
             dis_sc: add the DIS bulk velocity vector at each spacecraft (GSE coordinates only)
             des_sc: add the DES bulk velocity vector at each spacecraft (GSE coordinates only)
             dis_color: change the color of the DIS bulk velocity vector
             des_color: change the color of the DES bulk velocity vector
             fpi_data_rate: data rate of the DIS/DES data to use when plotting the vectors (default: fast)
             fpi_normalization: normalization factor of the bulk velocity vectors (allows you to scale down/up the vectors)

             vector_x: include a user-specified vector on the plot (x-components)
             vector_y: include a user-specified vector on the plot (y-components)
             vector_z: include a user-specified vector on the plot (z-components)
             vector_colors: color of the user-specified vectors on the plot

     EXAMPLES:
           mms_mec_formation_plot, '2016-1-08/2:36', /xy_projection, coord='gse'

           should create something like:
           https://lasp.colorado.edu/mms/sdc/public/data/sdc/mms_formation_plots/mms_formation_plot_20160108023624.png

           With vectors
           mms_mec_formation_plot,'2016-1-08/2:36',fpi_data_rate='fast',fpi_normalization=0.1d,fgm_normalization=1.d,/dis_center,/des_center,/bfield_center,/projection,plotmargin=1.0,sc_size=2.0,sundir='left'
           mms_mec_formation_plot,'2016-1-08/2:36',fpi_data_rate='fast',fpi_normalization=0.1d,fgm_normalization=1.d,/dis_sc,/des_sc,/bfield_sc,/projection,plotmargin=1.0,sc_size=2.0,sundir='left'
           mms_mec_formation_plot,'2015-10-16/13:07:02.40',fpi_data_rate='brst',fpi_normalization=0.02d,fgm_data_rate='brst',fgm_normalization=1.d,/dis_center,/des_center,/bfield_center,/projection,plotmargin=0.3,sc_size=2,sundir='left'
           mms_mec_formation_plot,'2015-10-16/13:07:02.40',fpi_data_rate='brst',fpi_normalization=0.02d,fgm_data_rate='brst',fgm_normalization=1.d,/dis_sc,/des_sc,/bfield_sc,/projection,plotmargin=1.2,sc_size=1.5,sundir='left'

           Sun to the left:
           mms_mec_formation_plot, '2016-1-08/2:36', /xy_projection, coord='gse', sundir='left'

           Specify an LMN transformation:
           mms_mec_formation_plot, '2016-1-08/2:36', /xy_projection, coord='gse', lmn=[[0.00,0.00,1.00],[0.00,-1.00,0.00],[1.00,0.00,0.00]], sundir='left'

           Specify an XYZ transformation:
           mms_mec_formation_plot, '2016-1-08/2:36', /xy_projection, coord='gse', xyz=[[0.00,0.00,1.00],[0.00,-1.00,0.00],[1.00,0.00,0.00]], sundir='left'

     HISTORY:
           March 2020: Many updates to vector keywords from Naritoshi Kitamura
           August 2016: Lots of updates from Naritoshi Kitamura

           The original copy of this comes from the
           SDC version, which was written by Kris Larsen
           and Kim Kokkonen at LASP

     $LastChangedBy: egrimes $
     $LastChangedDate: 2021-01-12 10:07:57 -0800 (Tue, 12 Jan 2021) $
     $LastChangedRevision: 29592 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec/mms_mec_formation_plot.pro $

(See projects/mms/mec/mms_mec_formation_plot.pro)

## MMS_ORBIT_PLOT

[Previous Routine] [List of Routines]

     PROCEDURE:
           mms_orbit_plot

     PURPOSE:
           Creates a plot showing the spacecraft location

     KEYWORDS:
           trange: time range of interest
           probes: probes to include in the orbits plot
           plane: orbital plane to plot (default: 'xy', other options include: 'yz', 'xz')
           xrange: min and max of the horizontal axis
           yrange: min and max of the vertical axis
           coord: coordinate system of the plot (default: gse)
                 other options include: 'eci', 'gsm', 'geo', 'sm', 'gse2000'
           title: title of the plot; defaults to the time range of the orbit
           noearth: disable the image of Earth on the figure

     EXAMPLES:
           IDL> mms_orbit_plot, probe=[1, 2, 3, 4], trange=['2015-12-15', '2015-12-16']

     HISTORY:
           Based on SDC routine that produces historical orbit plots for MMS originally
           by Kris Larsen, Kim Kokkonen, Chris Lindholm; egrimes heisted the important parts
           and turned this into a SPEDAS routine on November 27, 2017

     NOTES:
           terminator line on Earth is probably going to be incorrect when plane is specified to be YZ

     $LastChangedBy: egrimes $
     $LastChangedDate: 2020-05-27 17:05:37 -0700 (Wed, 27 May 2020) $
     $LastChangedRevision: 28740 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec/mms_orbit_plot.pro $

(See projects/mms/mec/mms_orbit_plot.pro)