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

Last modified: Sat Jul 26 18:17:38 2025.

# Directory Listing of Routines

# projects/mms/common/cdf

- MMS_ADD_CDF_VERSIONS
  Adds MMS CDF version #s to plots (for version tracking)
- MMS_CDF2TPLOT
- MMS_CDF_INFO_TO_TPLOT
- MMS_CDF_LOAD_VARS
- UNH_MMS_FILE_FILTER

# Routine Descriptions

## MMS_ADD_CDF_VERSIONS

[Next Routine] [List of Routines]

     PROCEDURE:
           mms_add_cdf_versions

     PURPOSE:
           Adds MMS CDF version #s to plots (for version tracking)

     INPUT:
           instrument: name of the instrument that we're adding the version #s for
           versions: [n, 3] array of CDF version #s - returned by 'versions' keyword
               in load routines; where n is the number of CDF files loaded

     KEYWORDS:
           data_rate: include a data rate on the plot
           right_align: start placing version #s strings to the bottom right of the
               plot instead of the bottom left
           top_align:  start placing version #s strings on the top of the figure
               instead of the bottom
           charsize: character size; default is 1
           reset:  reset the position of the labels to the starting point

     EXAMPLE:
           MMS> mms_load_fpi, versions=fpi_versions
           MMS> tplot, 'mms3_des_energyspectr_par_fast'
           MMS> mms_add_cdf_versions, 'fpi', fpi_versions

     NOTES:
           1) Requires IDL 8.0+ to work

           2) the default location of the version #s is the bottom left;
              you can change this using the /right and /top keywords

           3) does not include duplicate version #s for the same instrument
              e.g., if you load FPI data from 7 v2.1.0 files, only one 'FPI v2.1.0'
              will be included

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-06-27 09:18:53 -0700 (Wed, 27 Jun 2018) $
     $LastChangedRevision: 25404 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cdf/mms_add_cdf_versions.pro $

(See projects/mms/common/cdf/mms_add_cdf_versions.pro)

## MMS_CDF2TPLOT

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

    mms_cdf2tplot ,files,varformat=varformat

    Keywords:

     VARFORMAT = PATTERN  ; PATTERN should be a string (wildcards accepted) that will match the CDF variable that should be made into tplot variables
     PREFIX = STRING      ; String that will be pre-pended to all tplot variable names.
     SUFFIX = STRING      ; String appended to end of each tplot variable created.
     VARNAMES = named variable ; CDF variable names are returned in this variable
     /GET_SUPPORT_DATA    ; Often required to get support data if the CDF file does not have all the needed depend attributes

     record=record if only one record and not full cdf-file is requested

    load_labels=load_labels ;copy labels from labl_ptr_1 in attributes into dlimits
             resolve labels implemented as keyword to preserve backwards compatibility

    Author: Davin Larson -  20th century
     Forked for MMS, 10/22/2015, egrimes@igpp

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-01-05 17:08:07 -0800 (Thu, 05 Jan 2017) $
     $LastChangedRevision: 22512 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cdf/mms_cdf2tplot.pro $

(See projects/mms/common/cdf/mms_cdf2tplot.pro)

## MMS_CDF_INFO_TO_TPLOT

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

     This is a new routine that needs further testing, development, and enhancements.
     PROCEDURE:  mms_cdf_info_to_tplot, cdfi
     Purpose:  Creates TPLOT variables from a CDF structure (obtained from "CDF_LOAD_VAR")
     This routine will only work well if the underlying CDF file follows the SPDF standard.

     Written by Davin Larson
     Forked for MMS, 10/22/2015, egrimes@igpp

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-06-01 11:45:12 -0700 (Fri, 01 Jun 2018) $
     $LastChangedRevision: 25314 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cdf/mms_cdf_info_to_tplot.pro $

(See projects/mms/common/cdf/mms_cdf_info_to_tplot.pro)

## MMS_CDF_LOAD_VARS

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

     FUNCTION cdfi = mms_cdf_load_vars(file)
     INPUT:
       file = CDF filename(s)
     OUTPUT:
       CDFI = A structure containing pointers to the data and attributes
              for the files, with tags:
       CDFI.FILENAME = The filename(s)

       CDFI.INQ = A structure with information about the file:
       CDFI.INQ.NDIMS = CDF Dims attribute, for rVariables typically 0
                      (rVariables are rarely used anymore See http://cdf.gsfc.nasa.gov/html/FAQ.html#intro)
       CDFI.INQ.DECODING = 'HOST_DECODING' (can be network or host)
       CDFI.INQ.ENCODING = 'NETWORK_ENCODING' (can be network or host)
       CDFI.INQ.MAJORITY = 'ROW_MAJOR' (can be row or column)
       CDFI.INQ.MAXREC = Max number of records (Default is -1)
       CDFI.INQ.NVARS =  number of rVariables, usually 0
       CDFI.INQ.NZVARS = number of zVariables, usually all of them
       CDFI.INQ.NATTS = number of variable attributes
       CDFI.INQ.DIM = dimensions of rVariables

       CDFI.g_atttributes = CDF global attributes, structure varies
       Here is a sample from THEMIS EFI:

       PROJECT         STRING    'THEMIS'
       SOURCE_NAME     STRING    'THA>Themis Probe A'
       DISCIPLINE      STRING    'Space Physics>Magnetospheric Science'
       DATA_TYPE       STRING    'EFI'
       DESCRIPTOR      STRING    'L2>L2 DATA'
       DATA_VERSION    STRING    '1'
       PI_NAME         STRING    'V. Angelopoulos, J. Bonnell & F. Mozer'
       PI_AFFILIATION  STRING    'UCB, NASA NAS5-02099'
       TITLE           STRING    'Electric Field Instrument (EFI) Measurements'
       TEXT            STRING    'THEMIS-A: Electric Field Instrument (EFI) Electric field measurements. The L2 product is a 3D estimate of'...
       INSTRUMENT_TYPE STRING    'Electric Fields (space)'
       MISSION_GROUP   STRING    'THEMIS'
       LOGICAL_SOURCE  STRING    'tha_l2_efi'
       LOGICAL_FILE_ID STRING    'tha_l2_efi_20131001_v01'
       LOGICAL_SOURCE_DESCRIPTION
                       STRING    'Spacecraft-collected (EFI) Electric field'
       TIME_RESOLUTION STRING    '3-1/8s'
       RULES_OF_USE    STRING    'Open Data for Scientific Use'
       GENERATED_BY    STRING    'THEMIS SOC'
       GENERATION_DATE STRING    'Sun Oct  6 03:11:38 2013'
       ACKNOWLEDGEMENT STRING    'NASA Contract NAS5-02099'
       MODS            STRING    'Rev- 2009-09-16'
       ADID_REF        STRING    'NSSD0110'
       LINK_TEXT       STRING    Array[3]
       LINK_TITLE      STRING    Array[3]
       HTTP_LINK       STRING    Array[3]
       FILE_NAMING_CONVENTION
                       STRING    'source_descriptor_datatype'
       CAVEATS         STRING    'See THEMIS website for caveats'
       VALIDITY        STRING    'to be validated'
       VALIDATOR       STRING    'tbd'
       VALIDATE        STRING    'Compatible with the ISTP CDF Standards'
       INST_MOD        STRING    'THM>xxxx'
       PARENTS         STRING    'xxxx'
       INST_SETTINGS   STRING    'Not used'
       SOFTWARE_VERSION
                       STRING    '13273'

      CDFI.NV = Number of variables

      CDFI.VARS = AN array of CDFI.NV structures, one for each zvariable:
      CDFI.VARS.NAME = The variable name
      CDFI.VARS.NUM  = The index of the given variable in the cdfi.vars array
      CDFI.VARS.IS_ZVAR = 1 for a zVariable
      CDFI.VARS.DATATYPE = The data type, e.g.'CDF_FLOAT'
      CDFI.VARS.TYPE = The numerical IDL data type (float is 4, etc...)
      CDFI.VARS.NUMATTR = -1,  Not sure about this one, returned from CDF_VARGET
      CDFI.VARS.NUMELEM = Number of elements in a record, returned from CDF_VARGET
      CDFI.VARS.RECVARY = Set to 1 if variable varies from record to record
      CDFI.VARS.NUMREC = the number of records input.
      CDFI.VARS.NDIMEN = the number dimensions in the data
      CDFI.VARS.D = A six-element array with the number of dimensions for
                    each index
      CDFI.VARS.DATAPTR = A pointer to the data array:
      CDFI.VARS.ATTRPTR  = A pointer to the variable attributes
                           structure for each variable. Content varies,
                           here is a sample from THEMIS EFI Electric
                           field data:
       CATDESC         STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FIELDNAM        STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FILLVAL         FLOAT               NaN
       VALIDMIN        FLOAT     Array[3]
       VALIDMAX        FLOAT     Array[3]
       VAR_TYPE        STRING    'data'
       DISPLAY_TYPE    STRING    'time_series'
       FORMAT          STRING    'E13.6'
       LABL_PTR_1      STRING    'tha_eff_dot0_gsm_labl'
       UNITS           STRING    'mV/m'
       DEPEND_TIME     STRING    'tha_eff_dot0_time'
       DEPEND_EPOCH0   STRING    'tha_eff_dot0_epoch0'
       DEPEND_0        STRING    'tha_eff_dot0_epoch'
       DEPEND_1        STRING    'tha_eff_dot0_gsm_compno'
       VAR_NOTES       STRING    'Units are in mV/m'
       COORDINATE_SYSTEM
                       STRING    'GSM'
       REPRESENTATION_1
                       STRING    'Rep_xyz_gsm'
       TENSOR_ORDER    STRING    '1'
       AVG_TYPE        STRING    'standard'
       PROPERTY        STRING    'vector'
       SC_ID           STRING    'a'
       SCALE_TYP       STRING    'linear'
       DICT_KEY        STRING    'electric_field>vector_GSM'
       SI_CONVERSION   STRING    '1e-3>V/m'
       LABEL_1         STRING    'tha_eff_dot0_gsm_labl'

     Each variable may have a different set of attributes, but this
     example is a minimal structure that will be ISTP compliant.

     KEYWORDS:
       VARFORMAT = string or string array:  a string or string array (which may contain wildcard
                             characters) that specifies the CDF variable names to load.  Use
                              'VARFORMAT='*' to load all variables. NOTE
                              THAT VARFORMAT MUST BE SET IF YOU ACTUALLY
                              WANT TO READ DATA.
       VARNAMES = named variable   ;output variable for variable names that were loaded.
       SPDF_DEPENDENCIES :   Set to 1 to have SPDF defined dependent variables also loaded.
       VAR_TYPE = string or string array;  Variables that have a VAR_TYPE matching these strings will
                             be loaded.
       CONVERT_INT1_TO_INT2  Set this keyword to convert signed one byte to signed 2 byte integers.
                             This is useful because IDL does not have the equivalent of INT1   (bytes are unsigned)
       RECORD: Specify the record index where you want to start reading.  By default, this option will read one record.
       NUMBER_RECORDS: Specify the number of records that you want to read.  By default, this option will begin at record zero.

     Note: Record & Number_Records can be used together to specify a range of records to be read.

     Author: Davin Larson - 2006
     Forked for MMS, 10/22/2015, egrimes@igpp

     Side Effects:
       Data is returned in pointer variables. Calling routine is responsible for freeing up heap memory - otherwise a memory leak will occur.

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-11-19 16:12:09 -0800 (Mon, 19 Nov 2018) $
     $LastChangedRevision: 26155 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cdf/mms_cdf_load_vars.pro $

(See projects/mms/common/cdf/mms_cdf_load_vars.pro)

## UNH_MMS_FILE_FILTER

[Previous Routine] [List of Routines]

       Filter MMS file names by time and version. File names are assumed to be identical
       except in the TSTART and VERSION fields.

     :Params:
           FILENAMES:      in, required, type=string/strarr
                           Names of files to be filtered.

     :Keywords:
           COUNT:          out, optional, type=integer
                           Number of output files that passed filter.
           TRANGE:         in, optional, type=strarr(2), default=time_string(timerange())
                           Time interval over which to select files.
           MAJOR_VERSION:  in, optional, type=boolean, default=0
                           If set, only the latest major version of each file is returned. Cannot
                               be used with `MIN_VERSION`, LATEST_VERSION or `VERSION`
           LATEST_VERSION: in, optional, type=boolean, default=0
                           If set, only the latest version of each file is returned. Cannot
                               be used with `MIN_VERSION` or `VERSION`
           MIN_VERSION:    in, optional, type=string
                           Minimum file version to accept, formatted as 'X.Y.Z', where
                               X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
                               or `VERSION`.
           VERSION:        in, optional, type=string
                           Version of files to accept, formatted as 'X.Y.Z', where
                               X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
                               or `MIN_VERSION`.

     :Returns:
           FILES_OUT:      Those files within `FILENAMES` that pass the filter criterion.

           LOADED_VERSIONS: The CDF version #s

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-09-26 12:18:29 -0700 (Tue, 26 Sep 2017) $
     $LastChangedRevision: 24031 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cdf/unh_mms_file_filter.pro $

(See projects/mms/common/cdf/unh_mms_file_filter.pro)