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

Last modified: Sun Jul 27 18:17:41 2025.

# Directory Listing of Routines

# projects/mms/particles/deprecated

- MMS_PART_PROCESS
- MMS_PART_PRODUCTS_NEW
- MMS_PART_PRODUCTS_OLD
- MMS_PART_WRITE_ASCII
- MOKA_MMS_PAD
- MOKA_MMS_PAD_CRIB
- SPD_SLICE2D_PLOT1

# Routine Descriptions

## MMS_PART_PROCESS

[Next Routine] [List of Routines]

    Procedure:
      mms_part_process

    Purpose:
      Apply standard processing to particle distribution array
      and pass out the processed copy.  This routine will apply
      perform a unit conversion and call the standard processing
      routines.

    Calling Sequence:
      mms_part_process, in, out [,units=units]

    Input:
      in:  Pointer array from mms_get_???_dist
      units:  String specifying new units
      _extra: Passed to sanitization routines

    Output:
      out:  Pointer array to processed copy of the data

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-03-10 09:00:31 -0800 (Fri, 10 Mar 2017) $
    $LastChangedRevision: 22936 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/deprecated/mms_part_process.pro $

(See projects/mms/particles/deprecated/mms_part_process.pro)

## MMS_PART_PRODUCTS_NEW

[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)

      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.

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

(See projects/mms/particles/deprecated/mms_part_products_new.pro)

## MMS_PART_PRODUCTS_OLD

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

    Procedure:
      mms_part_products_old (deprecated copy of mms_part_products)

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

       -----------------------------------------------------------------------------------------
       |  !!!!!! words of caution <------ by egrimes, 4/7/2016:                                |
       |   While you can use mms_part_products to generate particle moments for FPI from       |
       |   the distributions, these calculations are currently missing several important       |
       |   components, including photoelectron removal and S/C potential corrections.          |
       |   The official moments released by the team include these, and are the scientific     |
       |   products you should use in your analysis; see mms_load_fpi_crib to see how to load  |
       |   the FPI moments released by the team (des-moms, dis-moms datatypes)                 |
       -----------------------------------------------------------------------------------------

    Data Products:
      'energy' - energy spectrogram
      'phi' - azimuthal spectrogram
      'theta' - latitudinal spectrogram
      'gyro' - gyrophase spectrogram
      'pa' - pitch angle spectrogram
      '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:  Secify 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 velocity vector from distribution before
                      calculation of field aligned angular spectra.

      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!

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

(See projects/mms/particles/deprecated/mms_part_products_old.pro)

## MMS_PART_WRITE_ASCII

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

    Procedure:
      mms_part_write_ascii

    Purpose:
      Write standard 3D distribution structure to ascii file for
      use with geotail tool stel3d.pro.

    Calling Sequence:
      mms_part_write_ascii, dist [filename=filename]

    Input:
      dist: Pointer to standard 3D distribution structure array
      filename: String specifying the filename, path may be included

    Output:
      none/writes file

    Notes:
      Ideally this is a temporary solution for using MMS
      data with stel3d

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-13 14:40:51 -0700 (Fri, 13 May 2016) $
    $LastChangedRevision: 21082 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/deprecated/mms_part_write_ascii.pro $

(See projects/mms/particles/deprecated/mms_part_write_ascii.pro)

## MOKA_MMS_PAD

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

    #############################################
      DEPRECATED --> Please use moka_mms_pad_fpi
    #############################################

    Procedure:
      moka_mms_pad

    Purpose:
      Returns a pitch-angle-distribution from MMS FPI data (angle vs energy plot)
      as well as energy spectrum in the omni, para, perp and anti-para directions.
      One-count-level is also returned.

    Calling Sequence:
      structure = moka_mms_pad(bname, tname [,index] [,trange=trange] [,units=units],[,/norm],
                                            [,nbin=nbin], [,vname=vname] [,/structure])

     INPUT:
       bname: magnetic field, tplot-variable name, use burst data
       tname: FPI data, tplot-variable such as "mms?_des_dist_brst"
       index: (NOW DEPRECATED! after a struggle with apj2016_egyspec.pro)
       trange:  Two element time range to constrain the requested data (See also mms_get_fpi_dist)
       nbin: number of bins in the pitch-angle direction
       vname: bulk flow velocity for frame transformation, tplot-variable name,
              vname & tname should have the same data_rate
       norm: Set this keyword for normalizing the data at each energy bin
       units: units for both the pitch-angle-distribution (pad) and energy spectrum.
              Options are 'eflux' [eV/(cm!U2!N s sr eV)] or
                          'df'    [s!U3!N / km!U6!N']
              The default is 'eflux'. The return structure contains a tag "UNITS".
       pr___0: pitch angle range for the "para" spectrum, default = [0,45]
       pr__90: pitch angle range for the "perp" spectrum, default = [45,135]
       pr_180: pitch angle range for the "anti-para" spectrum, default = [135,180]

    Output:
       a structure containing the result

    Example:
      MMS> trange = '2015-11-04/'+['04:57:49','04:57:50']
      MMS> tname = 'mms3_des_dist_brst'
      MMS> bname = 'mms3_fgm_b_dmpa_brst_l2_bvec'
      MMS> vname = 'mms3_des_bulk_dbcs_brst'
      MMS> pad = moka_mms_pad(bname, tname, trange, vname=vname)
      MMS> plotxyz,pad.PA, pad.EGY, pad.DATA,/noisotropic,/ylog,zlog=1,$
                   xrange=[0,180],zrange=[1e+5,1e+9],xtitle='pitch angle',ytitle='energy'

    History:
      Created by Mitsuo Oka on 2016-05-15
      Fixed energy bin mistake 2017-01-28
      Fixed para and anti-para mistake (thanks to R. Mistry) 2017-03-14
      Fixed eflux calculation 2017-05-12
      Added SUBTRACT_ERROR keyword 2017-10-17
      Removed unnecessary vname check 2017-10-19

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

(See projects/mms/particles/deprecated/moka_mms_pad.pro)

## MOKA_MMS_PAD_CRIB

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

    Procedure:
      moka_mms_pad_crib

    Purpose:
      Demonstrates usage of 'moka_mms_pad' (a program for Pitch Angle Distribution (PAD)).

    History:
      Created by Mitsuo Oka on 2017-01-05

    $LastChangedBy: moka $
    $LastChangedDate: 2017-10-19 12:43:56 -0700 (Thu, 19 Oct 2017) $
    $LastChangedRevision: 24187 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/deprecated/moka_mms_pad_crib.pro $

(See projects/mms/particles/deprecated/moka_mms_pad_crib.pro)

## SPD_SLICE2D_PLOT1

[Previous Routine] [List of Routines]

    Procedure:
      spd_slice2d_plot

    Purpose:
      Create plots for 2D particle slices.

    Calling Sequence:
      spd_slice2d_plot, slice

    Arguments:
      SLICE: 2D array of values to plot

    Plotting Keywords:
      LEVELS: Number of color contour levels to plot (default is 60)
      OLINES: Number of contour lines to plot (default is 0)
      ZLOG: Boolean indicating logarithmic countour 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)
      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 inegers.
      [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')

      WINDOW:  Index of plotting window to be used.
      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.

    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.

    Created by:
      Aaron Flores, based on work by Bryan Kerr and Arjun Raj

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-13 14:40:51 -0700 (Fri, 13 May 2016) $
    $LastChangedRevision: 21082 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/deprecated/spd_slice2d_plot1.pro $

(See projects/mms/particles/deprecated/spd_slice2d_plot1.pro)