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_ascii

- MMS_GET_LOCAL_STATE_FILES
- MMS_GET_STATE_DATA
  Helper routine for mms_load_state
- MMS_LOAD_ATT_TPLOT
  Loads ASCII attitude files into tplot variables
- MMS_LOAD_EPH_TPLOT
  Loads ASCII ephemeris files into tplot variables
- MMS_LOAD_STATE
  Load MMS state (position, attitude) data
- MMS_READ_DEF_ATT_FILE
  Reads the ASCII definitive attitude files into IDL structures
- MMS_READ_EPH_FILE
  Reads the ASCII ephemeris files into IDL structures
- MMS_READ_PRED_ATT_FILE
  Reads the ASCII predicted attitude files into IDL structures

# Routine Descriptions

## MMS_GET_LOCAL_STATE_FILES

[Next Routine] [List of Routines]

    Procedure:
      mms_get_local_state_files

    Purpose:
      Search for local state MMS files in case a list cannot be retrieved from the
      remote server.  Returns a sorted list of file paths.

    Calling Sequence:

      files = mms_get_local_state_files(probe=probe, level=level, filetype=filetype, trange=trange)

    Input:
      probe:  (string) Full spacecraft designation, e.g. 'mms1'
      filetype:  (string) state file type, e.g. 'eph' or 'att'
      level: (string) state level; either 'def' (for definitive) or 'pred' (for predicted)
      trange:  (string/double) Two element time range, e.g. ['2015-06-22','2015-06-23']

    Output:
      return value:  Sorted string array of file paths, if successful; 0 otherwise

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-09-08 13:45:22 -0700 (Tue, 08 Sep 2020) $
    $LastChangedRevision: 29123 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_get_local_state_files.pro $

(See projects/mms/mec_ascii/mms_get_local_state_files.pro)

## MMS_GET_STATE_DATA

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

     PROCEDURE:
             mms_get_state_data

     PURPOSE:
             Helper routine for mms_load_state

     data product:
       defatt - definitive attitude data; currently loads RAs, decl of L vector
       defeph - definitive ephemeris data; should load position, velocity
       predatt - predicted attitude data
       predeph - predicted ephemeris data

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-05-25 14:40:54 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21203 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_get_state_data.pro $

(See projects/mms/mec_ascii/mms_get_state_data.pro)

## MMS_LOAD_ATT_TPLOT

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

     PROCEDURE:
             mms_load_att_tplot

     PURPOSE:
             Loads ASCII attitude files into tplot variables

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-05-25 14:40:54 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21203 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_load_att_tplot.pro $

(See projects/mms/mec_ascii/mms_load_att_tplot.pro)

## MMS_LOAD_EPH_TPLOT

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

     PROCEDURE:
             mms_load_eph_tplot

     PURPOSE:
             Loads ASCII ephemeris files into tplot variables

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-03-16 16:11:23 -0700 (Fri, 16 Mar 2018) $
    $LastChangedRevision: 24897 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_load_eph_tplot.pro $

(See projects/mms/mec_ascii/mms_load_eph_tplot.pro)

## MMS_LOAD_STATE

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

     PROCEDURE:
             mms_load_state

     PURPOSE:
             Load MMS state (position, attitude) data
             NOTE: MEC data may also be loaded if the date is current date-4days
                   AND the level is not set to 'pred'

     KEYWORDS:
             trange:     time range of interest [starttime, endtime] with the format
                         ['YYYY-MM-DD','YYYY-MM-DD'] or for more specifi times
                         ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss'] see examples below
             probes:     list of probes, valid values for MMS probes are ['*','1','2','3','4']
                         where '*' specifies all probes. If no probe is specified the default
                         is all probes
             level:      ['def', 'pred'] for predicted or definitive attitude or position data.
                         the default is to search for definitive data first and if not found
                         search for predicted data. To turn this feature off use the keyword
                         pred_or_def (see below)
             datatypes:  ephemeris and attitude data types include ['*','pos', 'vel', 'spinras', 'spindec'].
                         If no value is given the default is '*' where all types will be loaded
                         (all MEC values might also be loaded - see NOTE in 'PURPOSE' (above))
             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
             remote_data_dir: This is the URL of the server that can provide the data files.
                         if the software does not find a needed file in LOCAL_DATA_DIR, then it will
                         attempt to download the data from the URL and REMOTE_DATA_DIR is defined,
                         the software will attempt to download the file from REMOTE_DATA_DIR, place it
                         in LOCAL_DATA_DIR with the same relative pathname, and then continue
                         processing.
             attitude_only: flag to only load L-right ascension and L-declination attitude data, this
                         is only true for predicted data
             ephemeris_only: flag to only load position and velocity data, this is only true for predicted data
             no_download: set flag to use local data only (no download)
             login_info: string containing name of a sav file containing a structure named "auth_info",
                         with "username" and "password" tags that include your SDC login information
             tplotnames: names for tplot variables
             pred_or_def: set this flag to turn off looking for predicted data if definitive not found
                         (pred_or_def=0 will return only the level that was requested). The default is
                         to load predicted data if definitive data is not found
             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
             suffix:     appends a suffix to the end of the tplot variable name. this is useful for
                         preserving original tplot variable.
             ascii:      force loading the state data from the ASCII files (will not use the MEC files)

     OUTPUT: tplot variables

     EXAMPLES:

       MMS> tr=['2015-07-21','2015-07-22']
       MMS> mms_load_state, probe='1', trange=tr
       MMS> mms_load_state, probe='*', level='def', trange=tr
       MMS> mms_load_state, probe=['1','3'], datatypes='pos', trange=tr
       MMS> mms_load_state, probe=['1','3'], datatypes=['pos', 'spinras'], trange=tr
       MMS> mms_load_state, probe=['1','2','3'], datatypes='*', level='pred', trange=tr
       MMS> mms_load_state, probe='1', /attitude_only, trange=tr
       MMS> mms_load_state, probe='*', /ephemeris_only, level='pred', trange=tr

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

         1) See the following regarding rules for the use of MMS data:
             https://lasp.colorado.edu/galaxy/display/mms/MMS+Data+Rights+and+Rules+for+Data+Use

         2) CDF version 3.6.3+ is required to correctly handle leap seconds.

         3) If no level ('pred' or 'def') is specified the routine defaults to 'def'. When 'def' data is
            retrieved and the start time requested is the same as the time of the last available definitive
            file or near the current date it's possible that only partial definitive data is available or that
            no data is available. Partial data is due to the fact that MMS files don't go from 0-24hrs but
            rather start at ~midday. Whenever partial data is available a warning message is displayed in the
            console window and the partial data is loaded.

            When no data is available the user is notified and no further action is taken. The user can re-request
            the data by adding or changing the keyword level to 'pred' or in the GUI by clicking on 'pred' in the
            level text box.

            Time frames can span several days or weeks. If long time spans start in the definitive range and
            end in the predicted time range the user will get either partial 'def' or 'pred' depending on
            what the level keyword is set to.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-02-21 14:47:40 -0800 (Wed, 21 Feb 2018) $
    $LastChangedRevision: 24756 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_load_state.pro $

(See projects/mms/mec_ascii/mms_load_state.pro)

## MMS_READ_DEF_ATT_FILE

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

     FUNCTION:
             mms_read_def_att_file

     PURPOSE:
             Reads the ASCII definitive attitude files into IDL structures

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-12-10 07:24:31 -0800 (Thu, 10 Dec 2020) $
    $LastChangedRevision: 29460 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_read_def_att_file.pro $

(See projects/mms/mec_ascii/mms_read_def_att_file.pro)

## MMS_READ_EPH_FILE

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

     FUNCTION:
             mms_read_eph_file

     PURPOSE:
             Reads the ASCII ephemeris files into IDL structures

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-12-10 07:24:31 -0800 (Thu, 10 Dec 2020) $
    $LastChangedRevision: 29460 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_read_eph_file.pro $

(See projects/mms/mec_ascii/mms_read_eph_file.pro)

## MMS_READ_PRED_ATT_FILE

[Previous Routine] [List of Routines]

     FUNCTION:
             mms_read_pred_att_file

     PURPOSE:
             Reads the ASCII predicted attitude files into IDL structures

    $LastChangedBy: egrimes $
    $LastChangedDate: 2015-12-10 14:31:13 -0800 (Thu, 10 Dec 2015) $
    $LastChangedRevision: 19594 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/mec_ascii/mms_read_pred_att_file.pro $

(See projects/mms/mec_ascii/mms_read_pred_att_file.pro)