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

Last modified: Mon Aug 25 17:13:29 2025.

# Directory Listing of Routines

# projects/mms/common/cotrans

- DMPA2DSL
- DMPA2GSE
- MMS_COTRANS
- MMS_COTRANS_LMN
  Tranforms MMS vector fields from GSM coordinates to LMN (boundary-normal) coordinates
- MMS_COTRANS_PARSE
- MMS_COTRANS_QROTATE
- MMS_COTRANS_QTRANSFORMER
- MMS_COTRANS_TRANSFORMER
- MMS_MP_LMN
- MMS_QCOTRANS
- MMS_QCOTRANS_CHECK_RATE

# Routine Descriptions

## DMPA2DSL

[Next Routine] [List of Routines]

    Procedure:
      dmpa2dsl

    Purpose: MMS coordinate transformation:
                DMPA <--> DSL

             ----------------------------------------------
             |  This is currently a placeholder and only  |
             |  performs an identity transformation!      |
             -----------------------------------------------

    Inputs
      TBD

    Keywords:
       /dsl2dmpa:  Inverse transformation
       /IGNORE_DLIMITS:  If the specified from coord is different from the
                         coord system labeled in the dlimits structure of the
                         tplot variable setting this keyword prevents an error.

    Example:

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-12-21 19:27:01 -0800 (Mon, 21 Dec 2015) $
    $LastChangedRevision: 19640 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/dmpa2dsl.pro $

(See projects/mms/common/cotrans/dmpa2dsl.pro)

## DMPA2GSE

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

    Procedure: dmpa2gse

    Purpose: MMS coordinate transformation:
                DMPA <--> GSE

             interpolates, right ascension, declination
             updates coord_sys attribute of output tplot variable.

    inputs

         name_mms_xxx_in   ... data to transform (dmpa coordinates)
       name_mms_spinras     ... right ascension of the L-vector (J2000 coordinates)
       name_mms_spindec     ... declination of the L-vector (J2000 coordinates)
       name_mms_xxx_out     ... name for output (t-plot variable name)

    keywords:

       /GSE2DMPA inverse transformation

       /IGNORE_DLIMITS if the specified from coord is different from the
    coord system labeled in the dlimits structure of the tplot variable
    setting this keyword prevents an error

    Example:

    Notes:
        Based on dsl2gse from THEMIS, forked 6/22/2015

        dmpa2gse is functionally equivalent to dsl2gse, and with proper
        input it can be used to perform a DSL to GSE transformation,
        as described below.

        MEC L_vec assumes rigid-body rotation even when the wire booms
        are oscillating, and thus, at any point in time it does not
        give L, but rather the average orientation of the nutating
        MPA (which is also assumed fixed relative to the rigid body)
        as it wobbles in inertial space with a period of ~7 minutes.

        When the user wants a DSL to GSE transformation, this can be done
        if the spinra/spindec give the actual orientation of the angular
        momentum vector.  This can come from:
               predatt (e.g. via AFG/DFG QL RADec_gse), or
               defatt, (e.g. via MEC L_vec data), sufficiently smoothed to remove any ‘wobble’
                 - The wobble is large: it can be as large as 0.2 degrees in amplitude
                   right after a maneuver, and still as large as 0.1 degrees 12 hours
                   after a maneuver.
                 - A gaussian filter with a low-pass cutoff low enough to clobber the
                   7-minute wobble works well.

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-06-12 15:08:37 -0700 (Mon, 12 Jun 2017) $
     $LastChangedRevision: 23455 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/dmpa2gse.pro $

(See projects/mms/common/cotrans/dmpa2gse.pro)

## MMS_COTRANS

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

    Procedure:
      mms_cotrans

    Purpose:
      Transform between MMS and geophysical coordinate systems.

    Calling Sequence:
      mms_cotrans, input_name [,output_name]
                   ,out_coord=out_coord [,out_suffix=out_suffix]
                   [,in_coord=in_coord] [,in_suffix=in_suffix] ...

    Example Usage:
      mms_cotrans, 'mms1_fgm_b_gse_srvy_l2_bvec', in_coord='gse', out_coord='gsm', $
                    out_suffix='_gsm', /ignore_dlimits

    Arguments:
      input_name: String or string array of input tplot variable(s).  Standard tplot
                  wildcards may be used to specify multiple variables.
      output_name (optional) String or string array of output tplot variable names.
                  Number of output names must match number of input names once
                  wildcards are considered.

    Keywords:
      in_coord:  String specifying the coordinate system of the input(s).
                 This keyword is optional if the dlimits.data_att.coord_sys attribute
                 is present for the tplot variable, and if present, it must match
                 the value of that attribute (see cotrans_set_coord, cotrans_get_coord).
                   e.g. 'gse', 'gsm', 'sm', 'gei','geo', 'mag'
      out_coord:  String specifying the desitnation coordinate system.
                    e.g. 'gse', 'gsm', 'sm', 'gei','geo', 'mag'
      in_suffix:  Suffix of input variable name.  This specifies the portion of
                  the input variable's name that will be replace with the output
                  suffix.  If specified, the name effective input name will be
                  input_name + in_suffix
      out_suffix:  Suffix appended to the output name.  If in_suffix is present or
                   the input coordinates are part of the input variable's name then
                   they will be replaced with out_suffix.
      support_suffix:  Suffix appended to standard support data names when looking
                       for support data (i.e. RA & Dec)

      out_vars: return a list of the names of any transformed variables

      valid_names:  return valid coordinate system names in named variables supplied to
                    in_coord and/or out_coord keywords.
      ignore_dlimits: set this keyword to true so that an error will not
                      be produced if the internal label of the coordinate system clashed
                      with the user provided coordinate system.
      no_update_labels: Set this keyword if you want the routine to not update the labels automatically

    Notes:
      Based on thm_cotrans

      egrimes disabled DMPA coordinate transformations on 2July18 - please use mms_qcotrans for
      these transformations

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-05-18 12:42:05 -0700 (Mon, 18 May 2020) $
    $LastChangedRevision: 28709 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans.pro $

(See projects/mms/common/cotrans/mms_cotrans.pro)

## MMS_COTRANS_LMN

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

     PROCEDURE:
             mms_cotrans_lmn

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

     KEYWORDS:
             gsm: input vector is in GSM coordinates (note: if the coordinate system is stored in the tplot metadata, these keywords are not required)
             gse: input vector is in GSE coordinates
             probe: MMS probe #; not required if the input variable follows the standard MMS naming scheme, e.g., mms1_mec_r_gsm
             data_rate: data rate of the MEC data
             resol: desired time resolution of the solar wind data in seconds
                 if not set, SW data are provided in original time resolution
             wind - use WIND observations for solar wind data (they are convolved to desired resolution and
                 then time-shifted to the bow-shock nose using OMNI-2 methodology. The
                 code checks if the SW speed irregularities are too large and warns
                 user when more sophisticated processing may be needed.
             min5 - use 5 min HRO merged database for solar wind inputs (default is to use 1 min HRO merged data)
             h1 - use OMNI-2 1 hour SW database for solar wind inputs. No convolution employed and parameter
                 resol is ignored

     NOTES:
             Based on the THEMIS version, thm_cotrans_lmn

             Also accepts all keywords available to solarwind_load

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-04-13 13:15:22 -0700 (Tue, 13 Apr 2021) $
    $LastChangedRevision: 29876 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans_lmn.pro $

(See projects/mms/common/cotrans/mms_cotrans_lmn.pro)

## MMS_COTRANS_PARSE

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

    Procedure:
      mms_cotrans_parse

    Purpose:
      Parse input coordinates stored in suffix string.
      This should allow coordinates systems denoted non-three-character strings
      and handle disambiguation between systems with identical substrings.

    Calling Sequence:
      coord_string = mms_cotrans_parse(input_string, valid_strings)

    Input:
      input_string:  The suffix to be parsed (scalar)
      valid_strings:  Array of valid coordinate strings

    Output:
      return value:  Returns recognized coordinate or empty string if none found.

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-05-25 15:38:52 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21208 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans_parse.pro $

(See projects/mms/common/cotrans/mms_cotrans_parse.pro)

## MMS_COTRANS_QROTATE

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

    Procedure:
      mms_cotrans_qrotate

    Purpose:
      Perform a quaternion rotation on a tplot variable

    Calling Sequence:
      mms_cotrans_qrotate, name_in, quaternion_name [,name_out] [,inverse=inverse]

    Input:
      name_in:  Tplot variable to be transformed
      quaternion_name:  Tplot variable containing MMS rotation quaternion
      name_out:  New name for output variable, if not specified the original is overwritten
      inverse:  Flag to apply inverse rotation
      out_coord:  String specifying output coordinates for updating dlimits

    Output:
      none, may alter or create new tplot variable

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-25 18:22:33 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21214 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans_qrotate.pro $

(See projects/mms/common/cotrans/mms_cotrans_qrotate.pro)

## MMS_COTRANS_QTRANSFORMER

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

    Procedure:
      mms_cotrans_qtransformer

    Purpose:
      Helps simplify transformation logic code using a recursive formulation.
      Rather than specifying the set of transformations for each combination of
      in_coord & out_coord, this routine will perform only the nearest transformation
      then make a recursive call to itself, with each call performing one additional
      step in the chain.  This makes it so only neighboring coordinate transforms
      need be specified.

      All possible transformations currently go through ECI coordinates

    Input:
      in_name:  name of variable to be transformed
      out_name:  output name for transformed variable
      in_coord:  coordinate system of the input
      out_coord:  coordinate system of the output
      probe:  probe designation for input variable

    Output:
      No explicit output, calls transformation routines and itself

    Notes:
      Modeled after thm_cotrans_transform_helper

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-25 18:22:33 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21214 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans_qtransformer.pro $

(See projects/mms/common/cotrans/mms_cotrans_qtransformer.pro)

## MMS_COTRANS_TRANSFORMER

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

    Procedure:
      mms_cotrans_transformer

    Purpose:
      Helps simplify transformation logic code using a recursive formulation.
      Rather than specifying the set of transformations for each combination of
      in_coord & out_coord, this routine will perform only the nearest transformation
      then make a recursive call to itself, with each call performing one additional
      step in the chain.  This makes it so only neighboring coordinate transforms
      need be specified.

      The set of possible transformations forms the following graph:
                GSE<->AGSM
                 |
         DMPA<->GSE<->GSM<->SM
                 |
                GSE<->GEI<->GEO<->MAG
                       |
                      GEI<->J2000

    Input:
      in_name:  name of variable to be transformed
      out_name:  output name for transformed variable
      in_coord:  coordinate system of the input
      out_coord:  coordinate system of the output

      spinras:  name of spacecraft right ascension variable
      spindec:  name of spacecraft declination variable

      ingnore_dlimits:  ignore variable metadata

    Output:
      No explicit output, calls transformation routines and itself

    Notes:
      - Modeled after thm_cotrans_transform_helper

      - the dmpa2dsl transformation is an identity
        transformation (dmpa is approximately the same as dsl;
        see the notes in the header of dmpa2gse for more info)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-12 15:08:37 -0700 (Mon, 12 Jun 2017) $
    $LastChangedRevision: 23455 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_cotrans_transformer.pro $

(See projects/mms/common/cotrans/mms_cotrans_transformer.pro)

## MMS_MP_LMN

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

     PROCEDURE:
         mms_mp_lmn

     NOTES:
         For more info, see:
         Determining L‐M‐N Current Sheet Coordinates at the Magnetopause From Magnetospheric Multiscale Data by Denton et al.

         http://dx.doi.org/10.1002/2017JA024619

     HISTORY:
         Originally provided by Jef Broll; added to SPEDAS by egrimes, April 2019

     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-04-29 12:07:53 -0700 (Mon, 29 Apr 2019) $
     $LastChangedRevision: 27132 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_mp_lmn.pro $

(See projects/mms/common/cotrans/mms_mp_lmn.pro)

## MMS_QCOTRANS

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

    Procedure:
      mms_qcotrans

    Purpose:
      Perform coordinate transformations using MMS MEC quaternions.
      This routine mirrors mms_cotrans but applies a different transformation.

    Calling Sequence:
      mms_qcotrans, input_name [,output_name]
                    ,out_coord=out_coord [,out_suffix=out_suffix]
                    [,in_coord=in_coord] [,in_suffix=in_suffix] ...

    Example Usage:
      mms_qcotrans, 'mms1_fgm_b_gse_srvy_l2_bvec', in_coord='gse', out_coord='gsm', $
                    out_suffix='_gsm'

    Arguments:
      input_name: String or string array of input tplot variable(s).  Standard tplot
                  wildcards may be used to specify multiple variables.
      output_name (optional) String or string array of output tplot variable names.
                  Number of output names must match number of input names once
                  wildcards are considered.

    Keywords:
      in_coord:  String specifying the coordinate system of the input(s).
                 This keyword is optional if the dlimits.data_att.coord_sys attribute
                 is present for the tplot variable, and if present, it must match
                 the value of that attribute (see cotrans_set_coord, cotrans_get_coord).
                   e.g. 'bcs','gse','gse2000','gsm','sm','geo','eci'
      out_coord:  String specifying the output coordinate system.
                    e.g. 'bcs','gse','gse2000','gsm','sm','geo','eci'
      in_suffix:  Suffix of input variable name.  This specifies the portion of
                  the input variable's name that will be replace with the output
                  suffix.  If specified, the name effective input name will be
                  input_name + in_suffix
      out_suffix:  Suffix appended to the output name.  If in_suffix is present or
                   the input coordinates are part of the input variable's name then
                   they will be replaced with out_suffix.

      out_vars: return a list of the names of any transformed variables

      valid_names:  return valid coordinate system names
      no_update_labels: Set this keyword if you want the routine to not update the labels automatically

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-02-01 15:58:09 -0800 (Thu, 01 Feb 2018) $
    $LastChangedRevision: 24622 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_qcotrans.pro $

(See projects/mms/common/cotrans/mms_qcotrans.pro)

## MMS_QCOTRANS_CHECK_RATE

[Previous Routine] [List of Routines]

    Procedure:
      mms_qcotrans_check_rate

    Purpose:
      Verify that quaternion transformations have sufficient time
      resolution for spinning/despinning data.

    Calling Sequence:
      bool = mms_qcotrans_check_times(in_coord, out_coord, probe)

    Input:
      in_coord:  input coordinates string
      out_coord:  output coordinates
      probe:  probe designation

    Output:
      return value:
        1 if required quaternion are present and have insufficient resolution
        0 otherwise

    Notes:
      -Assumes all tranformations performed through ECI

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-05-25 15:38:52 -0700 (Wed, 25 May 2016) $
    $LastChangedRevision: 21208 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/cotrans/mms_qcotrans_check_rate.pro $

(See projects/mms/common/cotrans/mms_qcotrans_check_rate.pro)