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

- MMS_GET_HPCA_DIST
- MMS_GET_HPCA_INFO
- MMS_HPCA_ANG_ANG
  Create angle-angle and angle-energy plots of HPCA distribution functions
- MMS_HPCA_CALC_ANODES
  Sums/averages over anodes (or a given field of view) for HPCA ion data
- MMS_HPCA_ENERGIES
  Returns the hard-coded energy table; this is only used when
- MMS_HPCA_MODE
- MMS_HPCA_SET_METADATA
  Sets metadata for HPCA tplot variables
- MMS_HPCA_SPIN_SUM
  Calculates spin-summed fluxes and counts for the HPCA instrument
- MMS_LOAD_HPCA
  Load data from the MMS Hot Plasma Composition Analyzer (HPCA)
- MMS_LOAD_HPCA_FIX_DIST
  Replace supplementary fields in 3D distribution variables with actual

# Routine Descriptions

## MMS_GET_HPCA_DIST

[Next Routine] [List of Routines]

    Procedure:
      mms_get_hpca_dist

    Purpose:
      Returns pseudo-3D particle data structures containing mms hpca data
      for use with spd_slice2d.

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

    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
      units:  Specify units of input data if not present or correct in input_name

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

    Notes:
         The HPCA data is required to be at the center of the measurement interval for this routine
         to work properly; be sure to use the keyword: /center_measurement when calling mms_load_hpca

         Still a work in progress; report bugs to egrimes@igpp.ucla.edu

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-11-12 13:32:47 -0800 (Thu, 12 Nov 2020) $
    $LastChangedRevision: 29351 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_get_hpca_dist.pro $

(See projects/mms/hpca/mms_get_hpca_dist.pro)

## MMS_GET_HPCA_INFO

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

    Purpose:
      Returns structure containing hpca look directions, energies, and other info.
      This is primarily for testing of hpca distribution slices; it may change or disappear.

    Notes:
      Angles are in degrees.
      Elevations are in colatitude.
      Values were copied from hpca manual 20150817_0.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-01-29 15:22:13 -0800 (Fri, 29 Jan 2016) $
    $LastChangedRevision: 19853 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_get_hpca_info.pro $

(See projects/mms/hpca/mms_get_hpca_info.pro)

## MMS_HPCA_ANG_ANG

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

     PROCEDURE:
         mms_hpca_ang_ang

     PURPOSE:
         Create angle-angle and angle-energy plots of HPCA distribution functions

     INPUT:
         time: time of interest

     KEYWORDS:
         species: HPCA species; e.g., hplus, oplus, etc (default: hplus)
         probe: MMS spacecraft # (default: '1')
         level: data level (default: 'l2')
         data_rate: instrument data rate (default: brst)
         energy_range: energy range of figures, in eV (default: full energy range)
         center_measurement: center the HPCA measurements (default: enabled)
         flux: plot the flux instead of the distribution function
         png: save the plots as PNG files
         postscript: save the plots as PS files
         filename_suffix: append a suffix to the plot file names

     NOTES:
         warning: the data plotted by this routine are not omni-directional, i.e. spin-averaged/spin-summed,
                  so the azimuthal angles will be limited to those in the sample closest to
                  the requested time

         experimental, email questions to egrimes@igpp.ucla.edu

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

(See projects/mms/hpca/mms_hpca_ang_ang.pro)

## MMS_HPCA_CALC_ANODES

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

     PROCEDURE:
             mms_hpca_calc_anodes

     PURPOSE:
             Sums/averages over anodes (or a given field of view) for HPCA ion data

     KEYWORDS:
             tplotnames: names of tplot variables to pick the HPCA
                 ion spectra out of; will use tnames() if this is not set
             fov: field of view to sum/avg over
             anodes: anodes to sum/avg over (can not be set at the same time as fov)
             probe: MMS probe #
             suffix: if a suffix is used in the call to mms_load_hpca, you must specify it here

     EXAMPLE:
             See mms_load_hpca_crib for usage examples

     NOTES:
           This routine sums over anodes (or FoV) for products in units of counts, e.g.,
               *_count_rate, *_RF_corrected, *_bkgd_corrected, *_norm_counts

           and averages products in units of flux:
               *_flux

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-08-08 13:01:28 -0700 (Tue, 08 Aug 2017) $
    $LastChangedRevision: 23767 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_hpca_calc_anodes.pro $

(See projects/mms/hpca/mms_hpca_calc_anodes.pro)

## MMS_HPCA_ENERGIES

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

     PROCEDURE:
             mms_hpca_energies

     PURPOSE:
             Returns the hard-coded energy table; this is only used when
             the energy table is missing from the CDF (either not there, or
             all 0s)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-04-13 15:23:28 -0700 (Wed, 13 Apr 2016) $
    $LastChangedRevision: 20808 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_hpca_energies.pro $

(See projects/mms/hpca/mms_hpca_energies.pro)

## MMS_HPCA_MODE

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

     Function:
           mms_hpca_mode

     Input:
           brst_in: hpca burst data tplot variable
           srvy_in: hpca survey data tplot variable

     Output:
           mode_out: creates a tplot variable with the name data_in + _mode
           (with brst or srvy stripped off, containing flags
           for each mode (e.q. data.x=brst_srvy time and
           data.y:[brst_flag, srvy_flag].
           Returns the name of the tplot variable it created.

           NOTE: This only handles burst and survey type hpca data.
                 When fast data becomes available this will need
                 to be modified to handle that mode as well.

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-04-27 12:47:46 -0700 (Wed, 27 Apr 2016) $
     $LastChangedRevision: 20937 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_hpca_mode.pro $

(See projects/mms/hpca/mms_hpca_mode.pro)

## MMS_HPCA_SET_METADATA

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

     PROCEDURE:
             mms_hpca_set_metadata

     PURPOSE:
             Sets metadata for HPCA tplot variables

     KEYWORDS:
             prefix: prefix for names of the tplot variables, typically 'mms#' where # is the S/C number
             fov: field of view of the summed/averaged counts/fluxes
             anodes: anodes of the summed/averaged counts/fluxes (shouldn't be used with fov keyword)
             suffix: suffix of the summed/averaged counts/fluxes

     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-01-08 12:02:58 -0800 (Tue, 08 Jan 2019) $
     $LastChangedRevision: 26437 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_hpca_set_metadata.pro $

(See projects/mms/hpca/mms_hpca_set_metadata.pro)

## MMS_HPCA_SPIN_SUM

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

     PROCEDURE:
             mms_hpca_spin_sum

     PURPOSE:
             Calculates spin-summed fluxes and counts for the HPCA instrument

     KEYWORDS:
             probe: observatory # to spin sum the spectra for (e.g., probe='1')
             datatype: type of data to spin sum; potential options include:
                 flux, count_rate, RF_corrected, bkgd_corrected, norm_counts
             fov: field of view of the spectra created with mms_hpca_calc_anodes;
                 default is [0, 360]
             tplotnames: list of tplot variable names already loaded; should
                 include the HPCA spectra variables you would like to spin-sum;
                 if not provided, uses tnames() by default.
             avg: average instead of sum
             suffix: suffix that was used when the data were loaded; if you provide a suffix
             to mms_load_hpca and mms_hpca_calc_anodes, you'll need to apply a suffix
             here as well

     OUTPUT:
             Creates tplot variables containing the spin summed fluxes and counts;
             the new variables have the suffix "_spin" appended to their names

     NOTES:
             Must have HPCA data loaded and summed/averaged over the FoV (or anodes); i.e.,
             you must have already called mms_load_hpca and mms_hpca_calc_anodes prior to
             calling this routine.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-03-02 09:40:53 -0800 (Tue, 02 Mar 2021) $
    $LastChangedRevision: 29721 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_hpca_spin_sum.pro $

(See projects/mms/hpca/mms_hpca_spin_sum.pro)

## MMS_LOAD_HPCA

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

     PROCEDURE:
             mms_load_hpca

     PURPOSE:
             Load data from the MMS Hot Plasma Composition Analyzer (HPCA)

     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 '1'
             level:        indicates level of data processing. levels include 'l2', 'l1b', 'sitl'.
                           the default if no level is specified is 'L2'.
             datatype:     data types include (note that not all levels have all datatypes):
                           L2: ['ion', 'moments']
                           sitl, l1b: ['combined', 'bkgd_corr', 'count_rate', 'flux', 'moments', 'rf_corr', 'vel_dist'].
                           if no value is given the default is 'moments'.
             data_rate:    instrument data rates include 'brst' and 'srvy'; the default is 'srvy'.
             local_data_dir: local directory to store the CDF files
             varformat:    format of the variable names in the CDF to load
             source:       specifies a different system variable. By default the MMS system
                           variable is !mms
             get_support_data: load support data (defined by VAR_TYPE="support_data" 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; this keyword is required 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 names
             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 data)
             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)
             disable_mem_usage: disable memory usage checks and warnings

     EXAMPLE:
         Simple HPCA example:
         MMS>  mms_load_hpca, probes='1', trange=['2015-12-15', '2015-12-16'], datatype='ion'

         MMS>  mms_hpca_calc_anodes, fov=[0, 360] ; sum over the full field of view (FoV)
         MMS>  tplot, 'mms1_hpca_hplus_flux_elev_0-360' ; plot the H+ spectra (full FoV)

         MMS> mms_hpca_spin_sum, probe='1'
         MMS> tplot, ['mms1_hpca_hplus_flux_elev_0-360_spin', 'mms1_hpca_hplus_flux_elev_0-360']

         See crib sheets: mms_load_hpca_crib, mms_load_hpca_burst_crib, and mms_load_hpca_crib_qlplots
         for more usage examples

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

         The HPCA Data Products Guide can be found at:

         https://lasp.colorado.edu/galaxy/display/mms/HPCA+Data+Products+Guide

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

         When loading HPCA energy spectra with this routine, all of the data are loaded in
            initially. To plot a meaningful spectra, the user must call mms_hpca_calc_anodes
            to sum/average the data over the look directions for the instrument. This will append
            the field of view (or anodes) used in the calculation to the name of the tplot variable.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-07-10 14:19:15 -0700 (Wed, 10 Jul 2019) $
    $LastChangedRevision: 27435 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_load_hpca.pro $

(See projects/mms/hpca/mms_load_hpca.pro)

## MMS_LOAD_HPCA_FIX_DIST

[Previous Routine] [List of Routines]

     PROCEDURE:
             mms_load_hpca_fix_dist

     PURPOSE:
             Replace supplementary fields in 3D distribution variables with actual
             values from supplementary tplot variables (theta).

     NOTE:
             Expect this routine to be made obsolete after the CDFs are updated

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-01-16 09:13:41 -0800 (Tue, 16 Jan 2018) $
    $LastChangedRevision: 24519 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/hpca/mms_load_hpca_fix_dist.pro $

(See projects/mms/hpca/mms_load_hpca_fix_dist.pro)