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

Last modified: Sat Aug 2 18:17:35 2025.

# Directory Listing of Routines

# projects/mms/common/util

- FLATTEN_SPECTRA
  Create quick plots of spectra at a certain time (i.e., energy vs. eflux, PA vs. eflux, etc)
- FLATTEN_SPECTRA_CONVERT_UNITS
  Helper roputine for flatten_spectra and flatten_spectra_multi
- FLATTEN_SPECTRA_MULTI
  Create quick plots of spectra at multiple times (i.e., energy vs. eflux, PA vs. eflux, etc)
- MMS_CONVERT_VFRAME
- MMS_DRAW_CIRCLE
  Draws (and fills in) a circle
- MMS_REMOVE_OLD_FILES
  Removes old MMS CDF data files stored on your local file system.
- MMS_TEAM_KIBANA
  Opens the MMS Kibana page using your web browser; allows you to see which
- MMS_TRANSFORM_VELOCITY
- MMS_TRANSFORM_VELOCITY_LORENTZ
- TNAMES_CP
  Simple wrapper around the tnames() function that provides output that

# Routine Descriptions

## FLATTEN_SPECTRA

[Next Routine] [List of Routines]

     PROCEDURE:
             flatten_spectra

     PURPOSE:
             Create quick plots of spectra at a certain time (i.e., energy vs. eflux, PA vs. eflux, etc)

     KEYWORDS:
           REPLOT:    Recreate the figure with updated options (uses the previously selected time)
           [XY]LOG:   [XY] axis in log format
           [XY]RANGE: 2 element vector that sets [XY] axis range
           NOLEGEND:  Disable legend display
           COLORS:    n element vector that sets the colors of the line in order that they are in tplot_vars.options.varnames
                      n is number of tplot variables in tplot_vars.options.varnames

           PNG:         save png from the displayed windows (cannot be used with /POSTSCRIPT keyword)
           POSTSCRIPT: create postscript files instead of displaying the plot
           PREFIX:      filename prefix
           FILENAME:    custorm filename, including folder.
                        By default the folder is !mms.local_data_dir and filename includes tplot names and selected time (or center time)

           TIME_IN:     if the keyword is specified the time is determined from the variable, not from the cursor pick.
           TRANGE:      Two-element time range over which data will be averaged.
           SAMPLES:     Number of nearest samples to time to average. Override trange.
                        *** warning: using 'samples' with multiple variables containing data at different resolutions
                            can lead to different time ranges of data being used for each variable ***

           WINDOW:      Length in seconds over which data will be averaged. Override trange.
           CENTER_TIME: Flag denoting that time should be midpoint for window instead of beginning.
                        If TRANGE is specify, the the time center point is computed.
           RANGETITLE:  If keyword is set, display range of the averagind time instead of the center time
                        Does not affect deafult name of the png or postscript file
           TO_KEV:      Converts the x-axis to keV from eV (checks units in ysubtitle)
           TO_FLUX:     Converts the y-axis to units of flux, i.e., '1/(cm^2 s sr keV)', as with TO_KEV,
                         this keyword uses the units string in the ztitle
           XTITLE:      Manually set the title on the x-axis; if not set, the x-axis units are used
           YTITLE:      Manually set the title on the y-axis; if not set, the y-axis units are used
           XCLIP:       2 element array specifying the range of data to include in the plot (only plots the data between [xmin, xmax])
           YCLIP:       2 element array specifying the range of data to include in the plot (only plots the data between [ymin, ymax])
           XEXPONENTIAL_FORMAT: force the x-axis ticks to show as 10^3  e.g. ’10!U3!N’
           YEXPONENTIAL_FORMAT: force the y-axis ticks to show as 10^3  e.g. ’10!U3!N’
           LEGEND_LEFT: move the legend to the left-hand side of the figure
           LEGEND_BOTTOM: move the legend to the bottom of the figure

     EXAMPLE:
         To create line plots of FPI electron energy spectra for all MMS spacecraft:

           MMS> mms_load_fpi, datatype='des-moms', trange=['2015-12-15', '2015-12-16'], probes=[1, 2, 3, 4]
           MMS> tplot, 'mms?_des_energyspectr_omni_fast'
           MMS> flatten_spectra, /xlog, /ylog

           --> then click the tplot window at the time you want to create the line plots at

     NOTES:
         To change the legend names for variables, set the 'legend_name' option prior to creating the figure
             e.g.,
               options, 'mms3_des_energyspectr_omni_fast', 'legend_name', 'MMS3 FPI DES'

         work in progress; suggestions, comments, complaints, etc: egrimes@igpp.ucla.edu

    $LastChangedBy: jwl $
    $LastChangedDate: 2023-12-18 16:23:47 -0800 (Mon, 18 Dec 2023) $
    $LastChangedRevision: 32307 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/flatten_spectra.pro $

(See projects/mms/common/util/flatten_spectra.pro)

## FLATTEN_SPECTRA_CONVERT_UNITS

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

     FUNCTION:
         flatten_spectra_convert_units

     PURPOSE:
         Helper roputine for flatten_spectra and flatten_spectra_multi

     $LastChangedBy: egrimes $
     $LastChangedDate: 2021-08-13 11:48:37 -0700 (Fri, 13 Aug 2021) $
     $LastChangedRevision: 30205 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/flatten_spectra_convert_units.pro $

(See projects/mms/common/util/flatten_spectra_convert_units.pro)

## FLATTEN_SPECTRA_MULTI

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

     PROCEDURE:
             flatten_spectra_multi

     PURPOSE:
             Create quick plots of spectra at multiple times (i.e., energy vs. eflux, PA vs. eflux, etc)

     INPUT:
           num_spec: number of times to create spectra at

     KEYWORDS:
           [XY]LOG:   [XY] axis in log format
           [XY]RANGE: 2 element vector that sets [XY] axis range
           NOLEGEND:  Disable legend display
           COLORS:    n element vector that sets the colors of the line in order that they are in tplot_vars.options.varnames
                      n is number of tplot variables in tplot_vars.options.varnames

           PNG:         save png from the displayed windows (cannot be used with /POSTRSCRIPT keyword)
           POSTRSCRIPT: create postscript files instead of displaying the plot
           PREFIX:      filename prefix
           FILENAME:    custorm filename, including folder.
                        By default the folder is your IDL working directory and the filename includes tplot names and selected time (or center time)

           TIME:        if the keyword is specified the time is determined from the variable, not from the cursor pick.
           TRANGE:      Two-element time range over which data will be averaged.
           SAMPLES:     Number of nearest samples to time to average. Override trange.
           WINDOW:      Length in seconds over which data will be averaged. Override trange.
           CENTER_TIME: Flag denoting that time should be midpoint for window instead of beginning.
                        If TRANGE is specify, the the time center point is computed.
           RANGETITLE:  If keyword is set, display range of the averagind time instead of the center time
                        Does not affect deafult name of the png or postscript file
           TO_KEV:      Converts the x-axis to keV from eV (checks units in ysubtitle)
           TO_FLUX: Converts the y-axis to units of flux, i.e., '1/(cm^2 s sr keV)', as with TO_KEV,
                         this keyword uses the units string in the ztitle

     EXAMPLE:
         To create line plots of FPI electron energy spectra for all MMS spacecraft:

           MMS> mms_load_fpi, datatype='des-moms', trange=['2015-12-15', '2015-12-16'], probes=[1, 2, 3, 4]
           MMS> tplot, 'mms?_des_energyspectr_omni_fast'
           MMS> flatten_spectra_multi, 3, /xlog, /ylog

           --> then click the tplot window at the 3 times you want to create the line plots at

     NOTES:
         This is a fork of the code flatten_spectra

         currently only supports 1 panel per figure

         work in progress; suggestions, comments, complaints, etc: egrimes@igpp.ucla.edu

    $LastChangedBy: egrimes $
    $LastChangedDate: 2023-05-19 14:15:46 -0700 (Fri, 19 May 2023) $
    $LastChangedRevision: 31868 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/flatten_spectra_multi.pro $

(See projects/mms/common/util/flatten_spectra_multi.pro)

## MMS_CONVERT_VFRAME

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

    NAME:
    	mms_convert_vframe

    FUNCTION:  convert_vframe ,  dat,  velocity
    PURPOSE:   Change velocity frames
    INPUT:
      dat: 3d data structure
      velocity: SW velocity vector  [VX,VY,VZ]
    OUTPUT:  3d data structure.  Data will be in a different coordinate frame.
        (data will also be in units of distrubution function.)
    KEYWORDS:
       ETHRESH:  Threshold energy for interpolation.
       BINS:     Angle bins to be used
       EVALUES:
       INTERPOLATE:  set to non-zero value to have the data evaluated
       (interpolated) at the original energy steps.

    CREATED BY:	Davin Larson

    Forked for MMS by egrimes, 12/12/2018

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-12-12 14:08:01 -0800 (Wed, 12 Dec 2018) $
    $LastChangedRevision: 26317 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_convert_vframe.pro $

(See projects/mms/common/util/mms_convert_vframe.pro)

## MMS_DRAW_CIRCLE

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

     PROCEDURE:
             mms_draw_circle

     PURPOSE:
             Draws (and fills in) a circle

     NOTES:
             Taken from mms_fpi_dist_slice_comparison_crib, 8/26/16

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-08-26 09:12:48 -0700 (Fri, 26 Aug 2016) $
     $LastChangedRevision: 21731 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_draw_circle.pro $

(See projects/mms/common/util/mms_draw_circle.pro)

## MMS_REMOVE_OLD_FILES

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

     PROCEDURE:
             mms_remove_old_files

     PURPOSE:
             Removes old MMS CDF data files stored on your local file system.

     KEYWORDS:
             trange: time range of interest; default is full mission
             probes: list of probes - values for MMS SC #; default is all probes
             instruments: ['fpi', 'hpca', 'fgm'], etc; default is all instruments
             levels: level of data processing; default is all levels
             data_rates: instrument data rate; default is all data rates
             no_warning: disable warning before deleting files

     NOTES:
             WARNING: this routine requires an internet connection

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-04-10 13:26:52 -0700 (Wed, 10 Apr 2019) $
    $LastChangedRevision: 26996 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_remove_old_files.pro $

(See projects/mms/common/util/mms_remove_old_files.pro)

## MMS_TEAM_KIBANA

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

     PROCEDURE:
             mms_team_kibana

     PURPOSE:
             Opens the MMS Kibana page using your web browser; allows you to see which
             data files are available at the SDC, and when they're available

     KEYWORDS:
             only one keyword allowed specifying the instrument you're interested in, e.g.,
             /fgm for FGM data, /fpi for FPI data, etc.

     NOTES:
             The webpage is restricted to MMS team-members only

     EXAMPLE:
             to open the Kibana page for FPI CDF files:
             MMS> mms_team_kibana, /fpi

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-02-21 09:06:31 -0800 (Wed, 21 Feb 2018) $
     $LastChangedRevision: 24755 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_team_kibana.pro $

(See projects/mms/common/util/mms_team_kibana.pro)

## MMS_TRANSFORM_VELOCITY

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

    NAME:
     mms_transform_velocity

    PROCEDURE:   mms_transform_velocity,  vel, theta, phi,  deltav
    PURPOSE:  used by the convert_vframe routine to transform arrays of velocity
        thetas and phis by the offset deltav
    INPUT:
      vel:  array of velocities
      theta: array of theta values
      phi:   array of phi values
      deltav: [vx,vy,vz]  (transformation velocity)
    KEYWORDS:
     vx,vy,vz: return vx,vy,vz separately as well as in vector form

    CREATED BY:  Davin Larson

    Forked for MMS by egrimes, 12/12/2018

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-12-12 14:03:56 -0800 (Wed, 12 Dec 2018) $
    $LastChangedRevision: 26315 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_transform_velocity.pro $

(See projects/mms/common/util/mms_transform_velocity.pro)

## MMS_TRANSFORM_VELOCITY_LORENTZ

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

    NAME:
     mms_transform_velocity_lorentz

    PROCEDURE:   mms_transform_velocity_lorentz,  vel, theta, phi,  deltav
    PURPOSE:  used by the convert_vframe routine to transform arrays of velocity
        thetas and phis by the offset deltav
    INPUT:
      vel:  array of velocities
      theta: array of theta values
      phi:   array of phi values
      deltav: [vx,vy,vz]  (transformation velocity)
    KEYWORDS:
     vx,vy,vz: return vx,vy,vz separately as well as in vector form

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-12-12 14:04:37 -0800 (Wed, 12 Dec 2018) $
    $LastChangedRevision: 26316 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/mms_transform_velocity_lorentz.pro $

(See projects/mms/common/util/mms_transform_velocity_lorentz.pro)

## TNAMES_CP

[Previous Routine] [List of Routines]

     FUNCTION:
         tnames_cp

     PURPOSE:
         Simple wrapper around the tnames() function that provides output that
         can be copy+pasted from the console to create new figures.

         See the header of tnames for all input and keyword options

     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-07-09 13:13:14 -0700 (Tue, 09 Jul 2019) $
     $LastChangedRevision: 27421 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/common/util/tnames_cp.pro $

(See projects/mms/common/util/tnames_cp.pro)