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/particles

- MMS_CONVERT_FLUX_UNITS
- MMS_GET_DIST
- MMS_PART_CONV_UNITS
- MMS_PART_DES_PHOTOELECTRONS
  Loads and returns the FPI/DES photoelectron model based on stepper ID
- MMS_PART_GETPAD
  Quickly generate pitch angle spectrograms from multipad output from mms_part_getspec/mms_part_products
- MMS_PART_GETSPEC
- MMS_PART_ISEE3D
- MMS_PART_PRODUCTS
- MMS_PART_SLICE2D
- MMS_PGS_CLEAN_DATA
- MMS_PGS_CLEAN_SUPPORT
- MMS_PGS_MAKE_E_SPEC
- MMS_PGS_MAKE_FAC
  Generate the field aligned coordinate transformation matrix
- MMS_PGS_MAKE_MULTIPAD_SPEC
- MMS_PGS_MAKE_PHI_SPEC
- MMS_PGS_MAKE_THETA_SPEC
- MMS_PGS_MAKE_TPLOT
- MMS_PGS_SPLIT_HPCA
- MMS_SLICE1D_PLOT_FPI
  Create 1D plot from a 2D particle slice

# Routine Descriptions

## MMS_CONVERT_FLUX_UNITS

[Next Routine] [List of Routines]

    Procedure:
      mms_convert_flux_unit

    Purpose:
      Perform unit conversions for MMS particle data structures

    Supported Units:
      flux   -   # / (cm^2 * s * sr * eV)
      eflux  -  eV / (cm^2 * s * sr * eV)
      df_cm  -  s^3 / cm^6
      df_km     -  s^3 / km^6

      'psd' is treated as 'df_km'

      'df' is no longer supported by these routines due to inconsistencies with THEMIS/other missions in SPEDAS

    Calling Sequence:
      mms_convert_flux_units, dist, units=units, output=output

    Arguments/Keywords:
      dist: Single MMS 3D particle data structure
      units: String specifying output units
      output: Set to named variable that will hold converted structure

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-11-21 18:02:57 -0800 (Wed, 21 Nov 2018) $
    $LastChangedRevision: 26169 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_convert_flux_units.pro $

(See projects/mms/particles/mms_convert_flux_units.pro)

## MMS_GET_DIST

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

    Procedure:
      mms_get_dist

    Purpose:
      Retrieve particle distribution structures/pointers from data loaded
      into tplot.

    Calling Sequence:
      data = mms_get_dist( input_name [,trange=trange] [/times] [/structure]
                           [,probe=probe] [,species=species]
                           [,instrument=instrument] [,units=units] )

    Input:
      input_name:  Name of tplot variable containing particle data (must be original name)
      single_time: Return a single time nearest to the time specified by single_time (supersedes trange and index)
      trange:  Optional two element time range
      times:  Flag to return array of full distribution sample times
      structure:  Flag to return structures instead of pointer to structures

      probe: specify probe if not present or correct in input_name
      species:  specify particle species if not present or correct in input_name
                    e.g. 'hplus', 'i', 'e'
      instrument:  specify instrument if not present or correct in input_name
                      'hpca' or 'fpi'
      units:  (HPCA only) specify units of input data if not present or correct in input_name
                  e.g. 'flux', 'df_cm'  (note: 'df_km' is in km, 'df_cm' is in cm)

    Output:
      return value:  Pointer to structure array or structure array if /structure used.
                     Array of times if /times is used
                     0 for any error case

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-04-03 12:46:57 -0700 (Tue, 03 Apr 2018) $
    $LastChangedRevision: 24987 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_get_dist.pro $

(See projects/mms/particles/mms_get_dist.pro)

## MMS_PART_CONV_UNITS

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

    Procedure:
      mms_part_conv_units

    Purpose:
      simple wrapper around mms_convert_flux_units that can be used
      as the 'units_procedure' in our 3d particle data structure

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-03-10 08:56:27 -0800 (Fri, 10 Mar 2017) $
    $LastChangedRevision: 22934 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_convert_flux_units.pro $

(See projects/mms/particles/mms_part_conv_units.pro)

## MMS_PART_DES_PHOTOELECTRONS

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

     FUNCTION:
             mms_part_des_photoelectrons

     PURPOSE:
             Loads and returns the FPI/DES photoelectron model based on stepper ID

     INPUT:
             dist_var: DES distribution data

     NOTES:
             see: https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-07-08 07:52:14 -0700 (Wed, 08 Jul 2020) $
    $LastChangedRevision: 28860 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_des_photoelectrons.pro $

(See projects/mms/particles/mms_part_des_photoelectrons.pro)

## MMS_PART_GETPAD

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

     PROCEDURE:
             mms_part_getpad

     PURPOSE:
             Quickly generate pitch angle spectrograms from multipad output from mms_part_getspec/mms_part_products

     NOTES:
             still a work in progress

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-09-20 15:04:07 -0700 (Thu, 20 Sep 2018) $
     $LastChangedRevision: 25838 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_getpad.pro $

(See projects/mms/particles/mms_part_getpad.pro)

## MMS_PART_GETSPEC

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

     Procedure:
             mms_part_getspec

     Purpose:
             This is a wrapper around mms_part_products that loads required
             support data (if not already loaded), and optionally creates
             angular spectrograms with B-field and S/C ram directions specified
             using symbols

     Keywords:
             probes: array of probes
             instrument: fpi or hpca
             species: depends on instrument:
                 FPI: 'e' for electrons, 'i' for ions
                 HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
             outputs: list of requested output types,
                 'energy' - energy spectrogram
                 'phi' - azimuthal spectrogram
                 'theta' - latitudinal spectrogram
                 'gyro' - gyrophase spectrogram
                 'pa' - pitch angle spectrogram
                 'multipad' - pitch angle spectrogram at every energy
                     (multi-dimensional PAD variable, to be used by mms_part_getpad)
                 'moments' - distribution moments (density, velocity, etc.)
             add_bfield_dir: add B-field direction (+, -) to the angular spectrograms (phi, theta)
             add_ram_dir: add S/C ram direction (X) to the angular spectrograms (phi, theta)
             dir_interval: number of seconds between B-field and S/C ram direction symbols on angular spectrogram plots

             subtract_bulk: subtract the bulk velocity prior to doing the calculations
             subtract_error: subtract the distribution error prior to doing the calculations (FPI only, currently)
             subtract_spintone: subtract the spin-tone from the velocity vector prior to bulk velocity subtraction (FPI versions 3.2 and later only)

             photoelectron_corrections: *experimental* photoelectron corrections for DES; enabled by default for DES moments; you can disable with photoelectron_corrections=0
             remove_fpi_sw: Flag to remove the solar wind component from the FPI ion DFs prior to performing the calculations
             sdc_units: Flag to convert moments_3d pressure tensor and heat flux outputs to nPa and mW/m^2 respectively, for compatibility with MMS SDC moments

         The following are found by default for the requested instrument/probe/data_rate; use these keywords
         to override the defaults:
             mag_name:  Use a different tplot variable containing magnetic field data for moments and FAC transformations
             pos_name:  Use a different tplot variable containing spacecraft position for FAC transformations
             vel_name:  Use a different tplot variable containing velocity data in km/s when subtracting the bulk velocity
             sc_pot_name: Use a different tplot variable containing spacecraft potential data

     Notes:
             Updated to automatically center HPCA measurements if not specified already, 18Oct2017

             Updated to automatically correct FPI-DES moments for photoelectrons, 20Sept2018

             FPI-DES internal photoelectrons are corrected using Dan Gershman's photoelectron model; see the following for details:
                 Spacecraft and Instrument Photoelectrons Measured by the Dual Electron Spectrometers on MMS
                 https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518

             Spacecraft photoelectrons are corrected in moments_3d

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-07-12 19:14:21 -0700 (Sat, 12 Jul 2025) $
    $LastChangedRevision: 33459 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_getspec.pro $

(See projects/mms/particles/mms_part_getspec.pro)

## MMS_PART_ISEE3D

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

     Procedure:
             mms_part_isee3d

     Purpose:
             This is a wrapper around isee_3d that loads required
             support data and plots the distribution

     Keywords:
             probe: MMS s/c # to create the 2D slice for
             instrument: fpi or hpca
             species: depends on instrument:
                 FPI: 'e' for electrons, 'i' for ions
                 HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
             level: level of the data you'd like to plot
             data_rate: data rate of the distribution data you'd like to plot
             trange: two-element time range over which data will be averaged (optional, ignored if 'time' is specified)
             spdf: load the data from the SPDF instead of the LASP SDC

     Notes:
             This routine always centers the distribution/moments data

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-04-30 09:44:09 -0700 (Tue, 30 Apr 2019) $
    $LastChangedRevision: 27150 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_isee3d.pro $

(See projects/mms/particles/mms_part_isee3d.pro)

## MMS_PART_PRODUCTS

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

    Procedure:
      mms_part_products

    Purpose:
      Generate spectra and moments from 3D MMS particle data.

    Data Products:
      'energy' - energy spectrogram
      'phi' - azimuthal spectrogram
      'theta' - latitudinal spectrogram
      'gyro' - gyrophase spectrogram
      'pa' - pitch angle spectrogram
      'multipad' - pitch angle spectrogram at each energy (multi-dimensional tplot variable,
           you'll need to use mms_part_getpad to generate PADs at various energies)
      'moments' - distribution moments (density, velocity, etc.)

    Calling Sequence:
      mms_part_products, tplot_name [,trange=trange] [outputs=outputs] ...

    Example Usage:
      -energy, phi, and theta spectrograms
        mms_part_products, 'mms2_des_dist_brst', outputs='phi theta energy'

      -field aligned spectrograms, limited time range
        mms_part_products, 'mms2_des_dist_brst', output='pa gyro', $
                           pos_name = 'mms2_defeph_pos', $
                           mag_name = 'mms2_fgm_bvec'

      -limit range of input data (gyro and pa limits do not affect phi/theta spectra)
        mms_part_products, 'mms2_des_dist_brst', output = 'energy pitch', $
                           energy = [15,1e5], $  ;eV
                           pitch = [45,135]

    Arguments:
      tplot_name:  Name of the tplot variable containing MMS 3D particle distribution data

    Input Keywords:
      trange:  Two element time range [start,end]
      outputs:  List of requested outputs, array or space separated list, default='energy'

      energy:  Two element energy range [min,max], in eV
      phi:  Two element phi range [min,max], in degrees, spacecraft spin plane
      theta:  Two element theta range [min,max], in degrees, latitude from spacecraft spin plane
      pitch:  Two element pitch angle range [min,max], in degrees, magnetic field pitch angle
      gyro:  Two element gyrophase range [min,max], in degrees, gyrophase

      mag_name:  Tplot variable containing magnetic field data for moments and FAC transformations
      pos_name:  Tplot variable containing spacecraft position for FAC transformations
      sc_pot_name:  Tplot variable containing spacecraft potential data for moments corrections
      vel_name:  Tplot variable containing velocity data in km/s for use with /subtract_bulk

      units:  Specify units of output variables.  Must be 'eflux' to calculate moments.
                'flux'   -   # / (cm^2 * s * sr * eV)
                'eflux'  -  eV / (cm^2 * s * sr * eV)  <default>
                'df_cm'  -  s^3 / cm^6
                'df_km'     -  s^3 / km^6

      fac_type:  Select the field aligned coordinate system variant.
                 Existing options: "phigeo,mphigeo, xgse"
      regrid:  Two element array specifying the resolution of the field-aligned data.
               [n_gyro,n_pitch], default is [32,16]
      no_regrid:  (experimental) Skip regrid step when converting to field aligned coordinates.

      suffix:  Suffix to append to output tplot variable names

      probe:  Specify probe designation when it cannot be parsed from tplot_name
      species:  Specify species when it cannot be parsed from tplot_name
      instrument:  Specify instrument when it cannot be parsed from tplot_name
      input_units:  (HPCA only) Specify units of input data when they cannot be parsed from tplot_name

      start_angle:  Set a start angle for azimuthal spectrogram y axis

      datagap:  Setting for tplot variables, controls how long a gap must be before it is drawn.
                (can also manually degap)
      subtract_bulk:  Flag to subtract bulk velocity (experimental)
      remove_fpi_sw: Flag to remove the solar wind component from the FPI ion DFs prior to performing the calculations
      use_sdc_units: Flag to convert moments_3d pressure tensor and qflux outputs to nPa and mW/m^2 respectively, for compatibility with MMS SDC moments

      display_object:  Object allowing dprint to export output messages

    Output Keywords:
      tplotnames:  List of tplot variables that were created
      get_data_structures:  Set to named variable to return structures directly when
                            generating field aligned outputs.  This may considerably
                            slow the process!
      error:  Error status flag for calling routine, 1=error 0=success

    Notes:
      -See warning above in purpose description!

      -FPI-DES photoelectrons are corrected using Dan Gershman's photoelectron model; see the following for details:
         Spacecraft and Instrument Photoelectrons Measured by the Dual Electron Spectrometers on MMS
         https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518

      -Note that there may still be slight differences between the PGS moments and the official moments released by the team.
         The official moments released by the team are the scientific
         products you should use in your analysis.

      - Note: versions of this code between 28July2021 and 5Nov2021 automatically removed negative values
              after photoelectron corrections; this functionality is now available by setting the keyword: /zero_negative_values

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-07-12 19:14:21 -0700 (Sat, 12 Jul 2025) $
    $LastChangedRevision: 33459 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_products.pro $

(See projects/mms/particles/mms_part_products.pro)

## MMS_PART_SLICE2D

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

     Procedure:
             mms_part_slice2d

     Purpose:
             This is a wrapper around spd_slice2d and spd_slice2d_plot that loads required
             support data, creates and plots the slice

     Keywords:
             PROBE: MMS s/c # to create the 2D slice for
             INSTRUMENT: fpi or hpca
             SPECIES: depends on instrument:
                 FPI: 'e' for electrons, 'i' for ions
                 HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
             LEVEL: level of the data you'd like to plot
             DATA_RATE: data rate of the distribution data you'd like to plot
             TIME: time of the 2D slice
             TRANGE: two-element time range over which data will be averaged (optional, ignored if 'time' is specified)
             SPDF: load the data from the SPDF instead of the LASP SDC
             OUTPUT: returns the computed slice
             UNITS: units of the slice (default is df_cm - other options include 'df_km', 'flux', 'eflux')

             TRANGE: Two-element time range over which data will be averaged. (string or double)
             TIME: Time at which the slice will be computed. (string or double)
               SAMPLES: Number of nearest samples to TIME to average. (int/double)
                 If neither SAMPLES nor WINDOW are specified then default=1.
               WINDOW: Length in seconds from TIME over which data will be averaged. (int/double)
                 CENTER_TIME: Flag denoting that TIME should be midpoint for window instead of beginning.

               SUM_SAMPLES: Flag denoting that the data should be summed over the requested trange rather than averaged

             THREE_D_INTERP: Flag to use 3D interpolation method (described below)
             TWO_D_INTERP: Flag to use 2D interpolation method (described below)
             GEOMETRIC: Flag to use geometric interpolation method (described below)

             RESOLUTION: Integer specifying the resolution along each dimension of the
                  slice (defaults:  2D/3D interpolation: 150, geometric: 500)
             SMOOTH: An odd integer >=3 specifying the width of a smoothing window in #
                  of points.  Smoothing is applied to the final plot using a gaussian
                  convolution. Even entries will be incremented, 0 and 1 are ignored.

             ENERGY: Flag to plot data against energy (in eV) instead of velocity.
             LOG: Flag to apply logarithmic scaling to the radial measure (i.e. energy/velocity).
                  (on by default if /ENERGY is set)

             ERANGE: Two element array specifying the energy range to be used in eV.

             THETARANGE: (2D interpolation only)
                  Angle range, in degrees [-90,90], used to calculate slice.
                  Default = [-20,20]; will override ZDIRRANGE.
             ZDIRRANGE: (2D interpolation only)
                 Z-Axis range, in km/s, used to calculate slice.
                 Ignored if called with THETARANGE.

             AVERAGE_ANGLE: (geometric interpolation only)
                     Two element array specifying an angle range over which
                     averaging will be applied. The angle is measured
                     from the slice plane and about the slice's horizontal axis;
                     positive in the right handed direction. This will
                     average over all data within that range.

                     Note: for the default rotation='xy', the angle is measured from the XY
                     slice plane and about the x-axis
                        e.g. rotation='xy', average_angle=[-25,25] will average data within 25 degrees
                             of the XY slice plane about it's x-axis
                        or
                             rotation='yz', average_angle=[-25,25] will average data within 25 degrees
                             of the YZ slice plane about it's y-axis

             SUM_ANGLE: (geometric interpolation only)
                     Two element array specifying an angle range over which
                     summing will be applied. The angle is measured
                     from the slice plane and about the slice's horizontal axis;
                     positive in the right handed direction. This will
                     sum over all data within that range.

                     Note: for the default rotation='xy', the angle is measured from the XY
                     slice plane and about the x-axis
                        e.g. rotation='xy', sum_angle=[-25,25] will sum data within 25 degrees
                             of the XY slice plane about it's x-axis
                        or
                             rotation='yz', sum_angle=[-25,25] will sum data within 25 degrees
                             of the YZ slice plane about it's y-axis

             DETERM_TOLERANCE:  tolerance of the determinant of the custom rotation matrix
               (maximum acceptable difference from determ(C)=1 where C is the
               user's custom rotation matrix); default is 1e-6

             SUBTRACT_BULK: subtract the bulk velocity prior to doing the calculations
             PERP_SUBTRACT_BULK: subtract the perpendicular bulk velocity in field-aligned coordinates
                     i.e., finds the perp velocity by rotating into the 'bv' system, then sets the X component
                     of velocity to zero, and inverse, then subtracts this velocity instead of the full bulk
                     velocity
             REMOVE_FPI_SW: remove the solar wind component from the FPI ion DF prior to calculating

    Orientation Keywords:
             ROTATION: Aligns the data relative to the magnetic field and/or bulk velocity.
                This is applied after the CUSTOM_ROTATION. (BV and BE are invariant
                between coordinate systems)

                'BV':  The x axis is parallel to B field; the bulk velocity defines the x-y plane
                'BE':  The x axis is parallel to B field; the B x V(bulk) vector defines the x-y plane
                'xy':  (default) The x axis is along the data's x axis and y is along the data's y axis
                'xz':  The x axis is along the data's x axis and y is along the data's z axis
                'yz':  The x axis is along the data's y axis and y is along the data's z axis
                'xvel':  The x axis is along the data's x axis; the x-y plane is defined by the bulk velocity
                'perp':  The x axis is the bulk velocity projected onto the plane normal to the B field; y is B x V(bulk)
                'perp_xy':  The data's x & y axes are projected onto the plane normal to the B field
                'perp_xz':  The data's x & z axes are projected onto the plane normal to the B field
                'perp_yz':  The data's y & z axes are projected onto the plane normal to the B field

             CUSTOM_ROTATION: Applies a custom rotation matrix to the data.  Input may be a
                       3x3 rotation matrix or a tplot variable containing matrices.
                       If the time window covers multiple matrices they will be averaged.
                       This is applied before other transformations

             SLICE_X & SLICE_NORM: These keywords respectively specify the slice plane's
                            x-axis and normal within the coordinates specified by
                            CUSTOM_ROTATION and ROTATION. Both keywords take
                            3-vectors as input. (See note below)

                            If SLICE_X is not specified then the given coordinate's
                            x-axis will be used. If SLICE_X is not perpendicular to
                            the normal it's projection onto the slice plane will be used.
                            An error will be thrown if no projection exists.

                            If SLICE_NORM is not specified then the given coordinate's
                            z-axis will be used (slice along by x-y plane in those
                            coordinates).

                  examples:
                    Slice along the data's x-z plane:
                      ROTATION='xz'

                    Slice plane's x axis is GSM x and y is in the direction of the bulk velocity:
                      CUSTOM_ROTATION='my_gsm_tvar', ROTATION='xvel'

                    Slice is perpendicular to "tvar1" and x axis is defined by projection of "tvar2"
                      SLICE_NORM='tvar1', SLICE_X='tvar2'

           NOTE: Update at 06/04/2018 - The SLICE_X & SLICE_NORM are defined after CUSTOM_ROTATION
             but before the ROTATION.

            DISPLACEMENT: Vector. New center of the coordinate system.
                  example:
                    Slice at the point x=0.5, y = 0.5 and z=0.1.
                    DISPLACEMENT = [0.5, 0.5. 0.1]

    Plotting Keywords:
            LEVELS: Number of color contour levels to plot (default is 60)
            OLINES: Number of contour lines to plot (default is 0)
            CONTOURS_OPLOT: Boolean indicating to only plot contours, not the data.
               this is especially useful if you're interested in plotting
               2-d or 3-d interpolated contours onto plots using geometric
               interpolation; requires an already existing 2d slice plot
            ZLOG: Boolean indicating logarithmic contour scaling (on by default)
            ECIRCLE: Boolean to plot circle(s) designating min/max energy
               from distribution (on by default)
            SUNDIR: Boolean to plot the projection of scaled sun direction (black line).
              Requires GET_SUN_DIRECTION set with spd_dist_array.
            PLOTAXES: Boolean to plot x=0 and y=0 axes (on by default)
            PLOTBULK: Boolean to plot projection of bulk velocity vector (red line).
                (on by default)
            PLOTORIGIN: Boolean to plot a new origin at the bulk velocity and/or sun location
                  instead of plotting the projection
            PLOTBFIELD: Boolean to plot projection of scaled B field (cyan line).
                  Requires B field data to be loaded and specified to
                  spd_slice2d with mag_data keyword.

            TITLE: String used as plot's title
            SHORT_TITLE: Flag to only use time range and # of samples for title
            CLABELS: Boolean to annotate contour lines.
            CHARSIZE: Specifies character size of annotations (1 is normal)
            [XYZ]RANGE: Two-element array specifying x/y/z axis range.
            [XYZ]TICKS: Integer(s) specifying the number of ticks for each axis
            [XYZ]PRECISION: Integer specifying annotation precision (sig. figs.).
                      Set to zero to truncate printed values to integers.
            [XYZ]STYLE: Integer specifying annotation style:
                 Set to 0 (default) for style to be chosen automatically.
                 Set to 1 for decimal annotations only ('0.0123')
                 Set to 2 for scientific notation only ('1.23e-2')
            [B,V,SUN]_COLOR: Specify the color of the corresponding support vector.
                       (e.g. "b_color=0", see IDL graphics documentation for options)
            NOCOLORBAR: Suppress z axis color bar.

            PLOTSIZE: The size of the plot in device units (usually pixels)
                (Not implemented for postscript).

            CUSTOM:  Flag that to disable automatic window creation and allow
               user-controlled plots.

            BACKGROUND_COLOR_INDEX: Integer (0-255) specifying a custom background color
               where data = 0.0

            BACKGROUND_COLOR_RGB: 3D array of integers (0-255) representing RGB values
                of the background color where data == 0.0; this keyword modifies the
                current color table to include this color at index = 7

    Exporting keywords:
            EXPORT: String designating the path and file name of the desired file.
              The plot will be exported to a PNG image by default.
            EPS: Boolean indicating that the plot should be exported to
              encapsulated postscript.

    Interpolation Methods:

       3D Interpolation:
         The entire 3-dimensional distribution is linearly interpolated onto a
         regular 3d grid and a slice is extracted from the volume.

       2D Interpolation:
         Datapoints within the specified theta or z-axis range are projected onto
         the slice plane and linearly interpolated onto a regular 2D grid.

       Geometric (default):
         Each point on the plot is given the value of the bin it intersects.
         This allows bin boundaries to be drawn at high resolutions.

     Examples:
             You can find examples in the following crib sheets:

             mms/examples/advanced/mms_slice2d_fpi_crib.pro
             mms/examples/advanced/mms_slice2d_hpca_crib.pro

     Notes:
             This routine always centers the distribution/moments data

             Default interpolation changed to geometric (from 3D), egrimes, 27Feb2020
               (requested by the FPI team at last year's GEM)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2023-03-28 12:25:34 -0700 (Tue, 28 Mar 2023) $
    $LastChangedRevision: 31675 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_part_slice2d.pro $

(See projects/mms/particles/mms_part_slice2d.pro)

## MMS_PGS_CLEAN_DATA

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

    Procedure:
      mms_pgs_clean_data

    Purpose:
      Sanitize mms FPI/HPCA data structures for use with
      mms_part_products.  Excess fields will be removed and
      field names conformed to standard.

      Reforms energy by theta by phi to energy by angle
      Converts units

    Input:
      data_in: Single combined particle data structure

    Output:
      output: Sanitized output structure for use within mms_part_products.

    Notes:
      -not much should be happening here since the combined structures
       are already fairly pruned
      -use for fpi and hpca for now

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
    $LastChangedRevision: 23532 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_clean_data.pro $

(See projects/mms/particles/mms_pgs_clean_data.pro)

## MMS_PGS_CLEAN_SUPPORT

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

    Procedure:
      mms_pgs_clean_support

    Purpose:
      Transform and/or interpolate support data to match the particle data.

    Arguments:
      times: Array of sample times for particledata
      probe: String specifying the spacecraft

    Input Keywords
      mag_name: String specifying a tplot variable containing magnetic field data
      sc_pot_name: String specifying a tplot variable containing spacecraft potential data
      vel_name: String specifying a tplot variable containing velocity data in km/s

    Output Keywords:
      mag_out: Array of magnetic field vectors corresponding to TIMES
      sc_pot_out: Array of spacecraft potential data corresponding to TIMES
      vel_out: Array of velocity vectors corresponding to TIMES

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-08-07 13:36:40 -0700 (Tue, 07 Aug 2018) $
    $LastChangedRevision: 25597 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_clean_support.pro $

(See projects/mms/particles/mms_pgs_clean_support.pro)

## MMS_PGS_MAKE_E_SPEC

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

    Procedure:
      mms_pgs_make_e_spec

    Purpose:
      Builds energy spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-04-24 16:23:53 -0700 (Tue, 24 Apr 2018) $
    $LastChangedRevision: 25106 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_e_spec.pro $

(See projects/mms/particles/mms_pgs_make_e_spec.pro)

## MMS_PGS_MAKE_FAC

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

    PROCEDURE: mms_pgs_make_fac
    PURPOSE:
      Generate the field aligned coordinate transformation matrix
      Specifically
      #1 guarantee mag_data is in dsl and pos data is in  gei
      #2 guarantee that time grid matches particle data

    Inputs(required):

    Outputs:

    Keywords:

    Notes:
      Needs to be vectorized because mms_cotrans is waaaay too slow if fed single vectors at a time
      If an error occurs fac_output will be undefined on return

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-07-02 15:28:15 -0700 (Mon, 02 Jul 2018) $
    $LastChangedRevision: 25430 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_fac.pro $

(See projects/mms/particles/mms_pgs_make_fac.pro)

## MMS_PGS_MAKE_MULTIPAD_SPEC

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

    Procedure:
      mms_pgs_make_multipad_spec

    Purpose:
      Builds theta (latitudinal) spectrogram from simplified particle data structure.
      this is like mms_pgs_make_theta_spec, except it's per energy and this routine expects
      'spec' to be sent already initialized

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ntimes x n_energy x ny)
      yaxis: The y axis (ny OR ny x ntimes)
      colatitude: Flag to specify that data is in colatitude

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:
     forked from mms_pgs_make_theta_spec by egrimes on 23 April 2018

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
    $LastChangedRevision: 23532 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_theta_spec.pro $

(See projects/mms/particles/mms_pgs_make_multipad_spec.pro)

## MMS_PGS_MAKE_PHI_SPEC

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

    Procedure:
      mms_pgs_make_phi_spec

    Purpose:
      Builds phi (longitudinal) spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
    $LastChangedRevision: 23532 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_phi_spec.pro $

(See projects/mms/particles/mms_pgs_make_phi_spec.pro)

## MMS_PGS_MAKE_THETA_SPEC

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

    Procedure:
      mms_pgs_make_theta_spec

    Purpose:
      Builds theta (latitudinal) spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)
      colatitude: Flag to specify that data is in colatitude

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
    $LastChangedRevision: 23532 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_theta_spec.pro $

(See projects/mms/particles/mms_pgs_make_theta_spec.pro)

## MMS_PGS_MAKE_TPLOT

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

    Procedure:
      mms_pgs_make_tplot

    Purpose:
      Create tplot variable with standard spectrogram settings.

    Input:
      name: name of new tplot variable to create
      x: x axis (time)
      v1: first dimension
      v2: second dimension
      z: z axis (data)
      _extra: Any other keywords used will be passed to tplot and
              set in the dlimits of the new variable.
              (e.g. ylog=1 to set logarithmic y axis)

    Output:
      Creates a tplot variable.
      tplotnames=tplotnames : Concatenates the name of the new variable onto tnames argument

    Notes:
      Forked from spd_pgs_make_tplot, on 3/13/2018, to support creating multi-dimensional tplot variables
      in mms_part_products_new

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-03-20 10:00:31 -0700 (Tue, 20 Mar 2018) $
    $LastChangedRevision: 24910 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_tplot.pro $

(See projects/mms/particles/mms_pgs_make_tplot.pro)

## MMS_PGS_SPLIT_HPCA

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

    Procedure:
      mms_pgs_split_hpca

    Purpose:
      Split hpca elevation bins so that dphi == dtheta.
      Combined with updates to spectra generation code this should allow
      the regrid step for FAC spectra to be skipped in mms_part_products.

    Input:
      data:  Sanitized hpca data structure

    Output:
      output:  New structure with theta bins split in two
               (2x data points in angle dimension)

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
    $LastChangedRevision: 23532 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_split_hpca.pro $

(See projects/mms/particles/mms_pgs_split_hpca.pro)

## MMS_SLICE1D_PLOT_FPI

[Previous Routine] [List of Routines]

     PROCEDURE:
      spd_slice1d_plot with FPI modifications by Simon Wellenzohn

     PURPOSE:
       Create 1D plot from a 2D particle slice

       This version allows you to plot the integral over a certain angle section (white lines in the plot) of the 2D distribution.
       The X axis of the plot created is a histogram with the width of the columns representing the energy channels of FPI.

     EXAMPLES:

      MMS> mms_slice1d_plot_fpi, slice, alpha=[0,0], width=[30,30], xrange=[-2500, 2500], yrange=[1e-25, 1d-22], export=export_dir

     INPUT:
      slice: slice returned by spd_slice2d
      alpha: angle in degrees to the x axis marking the center of the circle sector given for both the - and + x side
      width: angle in degrees which sets the width of the circle sector given for both - and + x side
      xrange: sets the xrange in km/s
      yrange: sets y range in integrated flux
      export: export path as string

     NOTES:
        minor modifications by egrimes, Jan 2020

     $LastChangedBy: egrimes $
     $LastChangedDate: 2020-01-28 17:59:08 -0800 (Tue, 28 Jan 2020) $
     $LastChangedRevision: 28247 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_slice1d_plot_fpi.pro $

(See projects/mms/particles/mms_slice1d_plot_fpi.pro)