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

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/mms/fpi

- MMS_FPI_ANG_ANG
  Creates various plots directly from the
- MMS_FPI_BURST_ENERGIES
  Returns the energies for burst mode FPI spectra. This routine uses
- MMS_FPI_CORRECT_PHOTOELECTRONS
- MMS_FPI_DIST_ANGLES
  Returns the azimuth/colatitude for FPI sky maps.
- MMS_FPI_FIX_METADATA
  Helper routine for setting FPI metadata. Original metadata from L2 QL plots script
- MMS_FPI_MAKE_COMPRESSIONLOSSBARS
  Make compressionloss flag bars
- MMS_FPI_MAKE_ERRORFLAGBARS
  Make error flag bars
- MMS_FPI_QUALITY_BAR
- MMS_FPI_REMOVE_SW
  Removes the solar wind component from the FPI ion distribution data
- MMS_FPI_SPLIT_TENSOR
  Splits FPI tensor variables (pressure, temperature) into their components
- MMS_GET_FPI_DIST
- MMS_GET_FPI_INFO
- MMS_LOAD_FPI
  Load data from the Fast Plasma Investigation (FPI) onboard MMS
- MMS_LOAD_FPI_CALC_PAD
  Calculates the omni-directional pitch angle distribution (summed and averaged)

# Routine Descriptions

## MMS_FPI_ANG_ANG

[Next Routine] [List of Routines]

     PROCEDURE:
             mms_fpi_ang_ang

     PURPOSE:
             Creates various plots directly from the
             FPI distribution functions, including:

             - angle-angle (azimuth vs zenith)
             - angle-energy (azimuth and zenith vs energy)
             - pitch angle - energy

     INPUT:
              time: exact time you'd like to see plotted

     KEYWORDS:
              all_energies: generate azimuth vs zenith plots at
                  all energies, one plot for each energy

              probe: probe to plot
              energy_range: energy range to include in the
                  angle-angle and angle-energy plots (default: 10-30000 eV)
              data_rate: FPI data rate ('fast' or 'brst')
              species: FPI species - 'e' for electrons or 'i' for ions (defaults to 'e')
              subtract_bulk: subtract the bulk velocity prior to
                  creating the PA-energy figure
              pa_en_units: units for the PA-energy figure (defaults to 'df_cm')
              postscript: save the plots as postscript files (can't be set with /png)
              png: save the plots as PNG files (can't be set with /postscript)
              center_measurement: shift the data to the center of the
                  measurement interval
              xsize: x-size of the figures (default: 550px)
              ysize: y-size of the figures (default: 450px)
              filename_suffix: suffix to append to the end of PNG/postscript file names
              nocontours: disable pitch angle contours on the angle-angle plots

     NOTES:
              Bulk velocity subtraction (via the /subtract_bulk keyword) only
              works for PA-energy figures (i.e., angle-angle and angle-energy plots
              are created as the data exists in the data files)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-09-17 12:04:17 -0700 (Tue, 17 Sep 2019) $
    $LastChangedRevision: 27764 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_ang_ang.pro $

(See projects/mms/fpi/mms_fpi_ang_ang.pro)

## MMS_FPI_BURST_ENERGIES

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

     PROCEDURE:
             mms_fpi_burst_energies

     PURPOSE:
             Returns the energies for burst mode FPI spectra.  This routine uses
                the alternating energy tables set by the parity bit

     NOTE:
             Burst mode FPI data must be loaded prior to calling this function

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-02-24 14:52:46 -0800 (Wed, 24 Feb 2016) $
    $LastChangedRevision: 20165 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_burst_energies.pro $

(See projects/mms/fpi/mms_fpi_burst_energies.pro)

## MMS_FPI_CORRECT_PHOTOELECTRONS

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

    Procedure:
      mms_fpi_correct_photoelectrons

    Purpose:
      Returns 3D particle data structures containing MMS FPI
      data for use with SPEDAS particle routines. This routine removes
      DES photoelectrons from the distribution using Dan Gershman's model
      prior to returning

    Input:
      tname: Tplot variable containing the desired data

    Keywords:
      scpot: tplot variable containing S/C potential data; loaded automatically if not otherwise specified
      subtract_error: subtract the distErr (variable specified by the keyword: error)
             data before returning; the error is subtracted prior to photoelectron removal
      error: variable name of the disterr variable, e.g.:
            'mms#_des_disterr_fast'

            for fast survey electron data

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-04-13 14:32:42 -0700 (Tue, 13 Apr 2021) $
    $LastChangedRevision: 29877 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_correct_photoelectrons.pro $

(See projects/mms/fpi/mms_fpi_correct_photoelectrons.pro)

## MMS_FPI_DIST_ANGLES

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

     PROCEDURE:
             mms_fpi_dist_angles

     PURPOSE:
             Returns the azimuth/colatitude for FPI sky maps.

     NOTE:
             Angle values describe the instrument look directions.
             This routine might be obsolete once the angles are added to the data CDFs.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-09-02 17:52:09 -0700 (Fri, 02 Sep 2016) $
    $LastChangedRevision: 21796 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_dist_angles.pro $

(See projects/mms/fpi/mms_fpi_dist_angles.pro)

## MMS_FPI_FIX_METADATA

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

     PROCEDURE:
             mms_fpi_fix_metadata

     PURPOSE:
             Helper routine for setting FPI metadata. Original metadata from L2 QL plots script

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-11-15 09:45:38 -0800 (Thu, 15 Nov 2018) $
    $LastChangedRevision: 26125 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_fix_metadata.pro $

(See projects/mms/fpi/mms_fpi_fix_metadata.pro)

## MMS_FPI_MAKE_COMPRESSIONLOSSBARS

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

     PROCEDURE:
             mms_fpi_make_compressionlossbars

     PURPOSE:
             Make compressionloss flag bars

     KEYWORDS:
             tname:   tplot variable name of dis or des compressionloss
             lossy:   the value for lossy compression (use this keyword only for special case)

     EXAMPLES:
         MMS>  mms_fpi_make_compressionlossbars,'mms1_des_compressionloss_brst'
         MMS>  mms_fpi_make_compressionlossbars,'mms1_dis_compressionloss_brst'

     FLAG:
         0: Lossless compression
         1: Lossy compression
       In old files (v2.1.0 or older until the end of Phase 1A)
         1: Lossless compression
         3: Lossy compression

     In cases when data had been lossy compressed, some artifacts may appear in the data due to the compression.
     Since all of fast survey data are lossy compressed, it is not nesessary to make this bar for fast survey data.

         Original by Naritoshi Kitamura

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-08-30 07:29:09 -0700 (Tue, 30 Aug 2016) $
    $LastChangedRevision: 21768 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_make_compressionlossbars.pro $

(See projects/mms/fpi/mms_fpi_make_compressionlossbars.pro)

## MMS_FPI_MAKE_ERRORFLAGBARS

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

     PROCEDURE:
             mms_fpi_make_errorflagbars

     PURPOSE:
             Make error flag bars

             For DES/DIS moments
              tname+'_flagbars_full': Detailed flag bars (all bars)
              tname+'_flagbars_main': Standard flag bars (4 bars)
              tname+'_flagbars_mini': Smallest flag bar (1 bars)

             For DES/DIS distribution function
              tname+'_flagbars_dist': Standard flag bars (2 bars)

     INPUT:
             tname:   tplot variable name of dis or des errorflag

     KEYWORDS:
             level:   level of the data to create the errorflags bar for
                     (default is l2 - this only needs to be set for QL data)

     EXAMPLES:
         MMS>  mms_fpi_make_errorflagbars,'mms1_des_errorflags_fast'
         MMS>  mms_fpi_make_errorflagbars,'mms1_dis_errorflags_fast'
         MMS>  mms_fpi_make_errorflagbars,'mms1_des_errorflags_brst'
         MMS>  mms_fpi_make_errorflagbars,'mms1_dis_errorflags_brst'

       For DES/DIS distribution function (Brst and Fast):
         bit 0 = manually flagged interval --> contact the FPI team for direction when utilizing this data; further correction is required
         bit 1 = overcounting/saturation effects likely present in skymap

       For DES/DIS moments (Brst):
         bit 0 = manually flagged interval  --> contact the FPI team for direction when utilizing this data; further correction is required
         bit 1 = overcounting/saturation effects likely present in skymap
         bit 2 = reported spacecraft potential above 20V
         bit 3 = invalid/unavailable spacecraft potential
         bit 4 = significant (>10%) cold plasma (<10eV) component
         bit 5 = significant (>25%) hot plasma (>30keV) component
         bit 6 = high sonic Mach number (v/vth > 2.5)
         bit 7 = low calculated density (n_DES < 0.05 cm^-3)
         bit 8 = onboard magnetic field used instead of brst l2pre magnetic field
         bit 9 = srvy l2pre magnetic field used instead of brst l2pre magnetic field
         bit 10 = no internally generated photoelectron correction applied
         bit 11 = compression pipeline error
         Bit 12 = spintone calculation error (DBCS only)
         Bit 13 = significant (>=20%) penetrating radiation (DIS only)
         Bit 14 = high MMS3 spintone due to DIS008 anomaly (DIS only)

       For DES/DIS moments (Fast):
         bit 0 = manually flagged interval --> contact the FPI team for direction when utilizing this data; further correction is required
         bit 1 = overcounting/saturation effects likely present in skymap
         bit 2 = reported spacecraft potential above 20V
         bit 3 = invalid/unavailable spacecraft potential
         bit 4 = significant (>10%) cold plasma (<10eV) component
         bit 5 = significant (>25%) hot plasma (>30keV) component
         bit 6 = high sonic Mach number (v/vth > 2.5)
         bit 7 = low calculated density (n_DES < 0.05 cm^-3)
         bit 8 = onboard magnetic field used instead of srvy l2pre magnetic field
         bit 9 = not used
         bit 10 = no internally generated photoelectron correction applied
         bit 11 = compression pipeline error
         Bit 12 = spintone calculation error (DBCS only)
         Bit 13 = significant (>=20%) penetrating radiation (DIS only)
         Bit 14 = high MMS3 spintone due to DIS008 anomaly (DIS only)

         Original by Naritoshi Kitamura

         June 2016: minor updates by egrimes

     $LastChangedBy: jwl $
     $LastChangedDate: 2024-09-12 11:27:33 -0700 (Thu, 12 Sep 2024) $
     $LastChangedRevision: 32829 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_make_errorflagbars.pro $

(See projects/mms/fpi/mms_fpi_make_errorflagbars.pro)

## MMS_FPI_QUALITY_BAR

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

     FUNCTION:
           mms_fpi_quality_bar

     INPUT:
           probe: probe #
           data_rate: brst, fast

     OUTPUT:
           Returns the name of a combined tplot variable with the DIS/DES quality bars

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-02-25 17:59:46 -0800 (Thu, 25 Feb 2016) $
     $LastChangedRevision: 20195 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_quality_bar.pro $

(See projects/mms/fpi/mms_fpi_quality_bar.pro)

## MMS_FPI_REMOVE_SW

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

     PROCEDURE:
             mms_fpi_remove_sw

     PURPOSE:
             Removes the solar wind component from the FPI ion distribution data

     KEYWORDS:
             probe: spacecraft probe # (default: 1)
             trange: time range (if the dist keyword isn't specified)
             dist: distribution structures (optional)
             data_rate: data rate (fast by default)
             cal_moment: calculate moments
             interpolate: interpolate the sw hole
             create_tplot: create tplot variables of moments and Vsw
             dvr: ?
             mag_name:
             sc_pot_name: name of tplot variable containing the spacecraft potential data
             newdist: set to a named variable to output the new distribution structure
             moment_output: output the moments
             vsw_output: output the solar wind velocity
             quiet: flag to disable printing out the processing status

     NOTES:
           Originally by Terry Liu (UCLA); minor updates by Eric Grimes

     $LastChangedBy:  $
     $LastChangedDate:  $
     $LastChangedRevision:  $
     $URL:  $

(See projects/mms/fpi/mms_fpi_remove_sw.pro)

## MMS_FPI_SPLIT_TENSOR

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

     PROCEDURE:
           mms_fpi_split_tensor

     PURPOSE:
           Splits FPI tensor variables (pressure, temperature) into their components

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-01-05 18:04:40 -0800 (Thu, 05 Jan 2017) $
     $LastChangedRevision: 22516 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_fpi_split_tensor.pro $

(See projects/mms/fpi/mms_fpi_split_tensor.pro)

## MMS_GET_FPI_DIST

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

    Procedure:
      mms_get_fpi_dist

    Purpose:
      Returns 3D particle data structures containing MMS FPI
      data for use with SPEDAS particle routines.

    Calling Sequence:
      data = mms_get_fpi_dist(tname [,index] [,trange=trange] [,/times] [,/structure]
                                    [,probe=probe] [,species=species] )

    Input:
      tname: Tplot variable containing the desired data.
      single_time: Return a single time nearest to the time specified by single_time (supersedes trange and index)
      index:  Index of time samples to return (supersedes trange)
      trange:  Two element time range to constrain the requested data
      times:  Flag to return full array of time samples
      structure:  Flag to return a structure array instead of a pointer.

      probe: specify probe if not present or correct in input_name
      species:  specify species if not present or correct in input_name
      subtract_error: subtract the distErr (variable specified by the keyword: error) data before returning
      error: variable name of the disterr variable, e.g.:
            'mms#_des_disterr_fast'

            for fast survey electron data

    Output:
      return value: pointer to array of 3D particle distribution structures
                    or 0 in case of error

    Notes:
      -FPI angles stored in tplot describe instrument look directions,
       this converts those to presumed trajectories (swaps direction).

      - Updated to accept FPI error data on 22Sept2017

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-04-10 08:51:06 -0700 (Wed, 10 Apr 2019) $
    $LastChangedRevision: 26986 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_get_fpi_dist.pro $

(See projects/mms/fpi/mms_get_fpi_dist.pro)

## MMS_GET_FPI_INFO

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

    Purpose:
      Returns structure containing supplementary information
      for analysis of FPI data.

    Return value:
      Info structure containing tables to be indexed by energy table
      and energy/angle bin index.
          {
            electron_energy: 3 x 32 array of electron energy tables
            ion_energy:      3 x 32 array of ion energy tables
            azimuth:         Azimuth of instrument look direction
            elevation:       Colatitude of instrument look direction
           }

    Notes:
      These values are approximate and should only be used in the absense of official support data!
      Energies are in eV from stepper tables.
      The first two columns of energies correspond to stepperTableParity = 0,1 for burst data (may be indexed).
      The last energy row is a geometric average of first two and is applicable to fast survey data.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-09-02 17:52:09 -0700 (Fri, 02 Sep 2016) $
    $LastChangedRevision: 21796 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_get_fpi_info.pro $

(See projects/mms/fpi/mms_get_fpi_info.pro)

## MMS_LOAD_FPI

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

     PROCEDURE:
             mms_load_fpi

     PURPOSE:
             Load data from the Fast Plasma Investigation (FPI) onboard MMS

     KEYWORDS:
             trange:       time range of interest [starttime, endtime] with the format
                           ['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
                           ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
             probes:       list of probes, valid values for MMS probes are ['1','2','3','4'].
                           If no probe is specified the default is probe '3'
             level:        indicates level of data processing. FPI levels currently include 'l2',
                           'l1b', 'sitl', 'ql'.
             datatype:     valid datatypes are:
                             Quicklook: ['des', 'dis']
                             SITL: '' (none; loads both electron and ion data from single CDF)
                             L1b/L2: ['des-dist', 'dis-dist', 'dis-moms', 'des-moms', 'dis-auxmoms', 'des-auxmoms', 'dis-partmoms', 'des-partmoms']
             data_rate:    instrument data rates for MMS FPI include 'fast', 'brst'.
             local_data_dir: local directory to store the CDF files; should be set if
                           you're on *nix or OSX, the default currently assumes Windows (c:\data\mms\)
             source:       specifies a different system variable. By default the MMS mission system
                           variable is !mms
             get_support_data: load support data (defined by support_data attribute in the CDF)
             tplotnames:   returns a list of the names of the tplot variables loaded by the load routine
             no_color_setup: don't setup graphics configuration; use this keyword when you're
                           using  this load routine from a terminal without an X server running
             time_clip:    clip the data to the requested time range; note that if you do not use
                           this keyword you may load a longer time range than requested
             no_update:    set this flag to preserve the original data. if not set and newer
                           data is found the existing data will be overwritten
             suffix:       appends a suffix to the end of the tplot variable name. this is useful for
                           preserving original tplot variable.
             varformat:    should be a string (wildcards accepted) that will match the CDF variables
                           that should be loaded into tplot variables
             cdf_filenames:  this keyword returns the names of the CDF files used when loading the data
             cdf_version:  specify a specific CDF version # to load (e.g., cdf_version='4.3.0')
             latest_version: only grab the latest CDF version in the requested time interval
                           (e.g., /latest_version)
             major_version: only open the latest major CDF version (e.g., X in vX.Y.Z) in the requested time interval
             min_version:  specify a minimum CDF version # to load
             spdf:         grab the data from the SPDF instead of the LASP SDC (only works for public access)
             center_measurement: set this keyword to shift the data to the center of the measurement interval
                           using the DELTA_PLUS_VAR/DELTA_MINUS_VAR attributes
             available:    returns a list of files available at the SDC for the requested parameters
                           this is useful for finding which files would be downloaded (along with their sizes) if
                           you didn't specify this keyword (also outputs total download size)
             versions:     this keyword returns the version #s of the CDF files used when loading the data
             always_prompt: set this keyword to always prompt for the user's username and password;
                           useful if you accidently save an incorrect password, or if your SDC password has changed
             tt2000: flag for preserving TT2000 timestamps found in CDF files (note that many routines in
                           SPEDAS (e.g., tplot.pro) do not currently support these timestamps)

     EXAMPLE:
         MMS>  timespan, '2015-09-19', 1, /day
         load FPI burst mode data
         MMS>  mms_load_fpi, probes = ['1'], level='l2', data_rate='brst', datatype='des-moms'

         load FPI FS data
         MMS>  mms_load_fpi, probes='3', level='l2', data_rate='fast', datatype='des-moms'

         See mms_load_fpi_crib, mms_load_fpi_burst_crib, and mms_load_fpi_crib_qlplots
         for usage examples

     NOTES:
         The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC

         Please see the notes at:
            https://lasp.colorado.edu/galaxy/display/mms/FPI+Release+Notes

         Have questions regarding this load routine, or its usage?
              https://groups.google.com/forum/#!forum/spedas

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-05-30 12:47:35 -0700 (Fri, 30 May 2025) $
    $LastChangedRevision: 33354 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_load_fpi.pro $

(See projects/mms/fpi/mms_load_fpi.pro)

## MMS_LOAD_FPI_CALC_PAD

[Previous Routine] [List of Routines]

     PROCEDURE:
             mms_load_fpi_calc_pad

     PURPOSE:
             Calculates the omni-directional pitch angle distribution (summed and averaged)
             from the individual tplot variables

    $LastChangedBy: jwl $
    $LastChangedDate: 2024-08-29 16:35:34 -0700 (Thu, 29 Aug 2024) $
    $LastChangedRevision: 32805 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/fpi/mms_load_fpi_calc_pad.pro $

(See projects/mms/fpi/mms_load_fpi_calc_pad.pro)