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/themis/spacecraft/particles/thm_part_products

- THM_PART_LOAD
- THM_PART_PRODUCTS
  Generate spectra and moments from THEMIS particle data.
- THM_PGS_CLEAN_CMB
- THM_PGS_CLEAN_ESA
  Helper routine for thm_part_products
- THM_PGS_CLEAN_SST
  Helper routine for thm_part_products
- THM_PGS_CLEAN_SUPPORT
- THM_PGS_DIST_ARRAY_DATA
- THM_PGS_DIST_ARRAY_START
- THM_PGS_DIST_ARRAY_TIMES
- THM_PGS_EXPAND_YAXIS
- THM_PGS_GET_DATATYPE
- THM_PGS_MAKE_FAC
  Generate the field aligned coordinate transformation matrix
- THM_PGS_MAKE_TPLOT
- THM_PGS_MOMENTS
- THM_PGS_MOMENTS_TPLOT
- THM_PGS_SET_SPEC_ZLIMITS
  Helper routine for thm_part_products

# Routine Descriptions

## THM_PART_LOAD

[Next Routine] [List of Routines]

    Name:
      thm_part_load

    Purpose:
      Load ESA or SST particle data.

    Calling Sequence:
      thm_part_load, probe=probe, datatype=datatype
                    [,trange=trange] [,sst_cal=sst_cal]
                    [,forceload=forceload]

    Keywords:
      probe: String or string array containing spacecraft designation (e.g. 'a')
      datatype: String or string array containing data type specification (e.g. 'peif')
      trange: Two element array specifying the desired time range
      sst_cal: Flag to use improved SST calibrations
      forceload: Flag to ignore check for existing data

    Notes:
      -If all requested data is already present the load will be
       skipped unless the forceload keyword is set.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2014-05-05 18:12:35 -0700 (Mon, 05 May 2014) $
    $LastChangedRevision: 15053 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_part_load.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_part_load.pro)

## THM_PART_PRODUCTS

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

    PROCEDURE:
      thm_part_products

    PURPOSE:
      Generate spectra and moments from  THEMIS particle data.
      Provides different angular view and angle restriction options
      in spacecraft and field alligned coordinates.

    Data Products:
      'energy' - energy spectrogram
      'phi' - azimuthal spectrogram
      'theta' - elevation spectrogram
      'gyro' - gyrophase spectrogram
      'pa' - pitch angle spectrogram
      'moments' - distribution moments (density, velocity, etc.)

    Calling Sequence:
      thm_part_products, probe=probe, datatype=datatype, trange=trange [,outputs=outputs] ...

    Example Usage:
      See crib sheets in .../themis/examples/

    Input Keywords:
      probe:  Spacecraft designation, e.g. 'a','b'
      datatype:  Particle datatype, e.g. 'psif, 'peib'
      trange:  Two element time range [start,end]

      outputs:  List of requested outputs, array or space separated list, default='energy'

      dist_array:  Data loaded manually with thm_part_dist_array or thm_part_combine.
                   If specified then probe and dataytpe are not needed; trange is optional.
                   Outputs will be in the data's units (probably counts, or eflux for combined)
                   unless specified with UNITS keyword.

      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

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

      regrid:  Two element array specifying the resolution [azimuth,elevation]
               used to regrid the data; default is [16,8].  Field aligned data
               is always regridded while phi and theta spectra are regridded if
               this keyword is specified.

      fac_type:  Select the field aligned coordinate system variant.
                 Existing options: 'phigeo', 'mphigeo', 'xgse'

      sst_sun_bins:  Array of which sst bins to decontaminate (list of bins numbers, not the old mask array)
                     Set to -1 to disable.
      esa_bgnd_remove:  Set to 0 to disable ESA background removal,
                        otherwise default anode-based background will be subtracted.
                        See thm_crib_esa_bgnd_remove for more keyword options.
      esa_bgnd_advanced:  Apply advanced ESA background subtraction.
                          Must call thm_load_esa_bkg first to calculate background.
                          Disables default background removal.

      suffix:  Suffix to append to output tplot variable names

      start_angle:  Set a start angle for azimuthal spectrogram y axis

      get_error:  Flag to return error estimates (*_sigma variables)

      datagap:  Setting for tplot variables, controls how long a gap must be before it is drawn.
                (can also manually degap)

      display_object:  Object allowing dprint to export output messages

      coord: if set, then velocity and flux variables are created for the
             input coordinate system, in addition to the DSL variables
    Output Keywords:
      tplotnames:  List of tplot variables that were created
      get_data_structures:  Set to named variable to return data structures when generating
                            field aligned outputs.  This may considerably slow the process!
      error:  Error status flag for calling routine, 1=error 0=success

    Notes:

    $LastChangedBy: jimm $
    $LastChangedDate: 2019-01-08 14:14:59 -0800 (Tue, 08 Jan 2019) $
    $LastChangedRevision: 26441 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_part_products.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_part_products.pro)

## THM_PGS_CLEAN_CMB

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

    Procedure:
      thm_pgs_clean_cmb

    Purpose:
      Sanitize combined particle data structures for use with
      thm_part_products.  Excess fields will be removed and
      field names conformed to standard.

    Input:
      data: Single combined particle data structure.
      units: String specifying a units type ('flux', 'eflux', or 'df')

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

    Notes:
      -not much should be happening here since the combined structures
       are already fairly pruned

    $LastChangedBy: aaflores $
    $LastChangedDate: 2014-01-10 18:02:25 -0800 (Fri, 10 Jan 2014) $
    $LastChangedRevision: 13850 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_cmb.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_cmb.pro)

## THM_PGS_CLEAN_ESA

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

    PROCEDURE: thm_pgs_clean_esa
    PURPOSE:
      Helper routine for thm_part_products
      Maps ESA data into simplified format for high-level processing.
      Creates consistency for downstream routines and throws out extra fields to save memory

    Inputs(required):
      data: ESA particle data structure from thm_part_dist, get_th?_pe??, thm_part_dist_array, etc...
      units: string specifying the units (e.g. 'eflux')

    Outputs:
       output structure elements:
             data - particle data 2-d array, energy by angle. (Float or double)
          scaling - scaling coefficient corresponding to 1 count/bin, used for error calculation (float or double)
             time - sample start time(1-element double precision scalar)
         end_time - sample end time(1-element double precision scalar)
              phi - Measurment angle in plane parallel to spacecraft spin.(2-d array matching data array.) (Float or double)
             dphi - Width of measurement angle in plane parallel to spacecraft spin.(2-d array matching data array.) (Float or double)
            theta - Measurment angle in plane perpendicular to spacecraft spin.(2-d array matching data array.) (Float or double)
           dtheta - Width of measurement angle in plane perpendicular to spacecraft spin. (2-d array matching data array.) (Float or double)
           energy - Contains measurment energy for each component of data array. (2-d array matching data array.) (Float or double)
          denergy - Width of measurment energy for each component of data array. (2-d array matching data array.)
             bins - 0-1 array, indicating which bins are enabled for subsequent calculations. (2-d array matching data array.)  (Integer type.)
           charge - expected particle charge (1-element float scalar)
             mass - expected particle mass (1-element float scalar)
             magf - placeholder for magnetic field vector (3-element float array)
            scpot - placeholder for spacecraft potential (1-element float scalar)

    Keywords:

      esa_max_energy: Set to maximum energy to toss bins that are having problems from instrument contamination.
      esa_bgnd_advanced: Flag to apply advanced background subtraction
                             Background must be pre-calculated with thm_load_esa_bkg

    $LastChangedBy: jimm $
    $LastChangedDate: 2019-02-19 11:17:18 -0800 (Tue, 19 Feb 2019) $
    $LastChangedRevision: 26643 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_esa.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_esa.pro)

## THM_PGS_CLEAN_SST

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

    PROCEDURE: thm_pgs_clean_sst
    PURPOSE:
      Helper routine for thm_part_products
      Maps SST data into simplified format for high-level processing. Converts into physical untis
      Creates consistency for downstream routines and throws out extra fields to save memory

    Inputs(required):

      data:  An SST particle data structure, produced by thm_part_dist or thm_sst_ps?? etc...
      units:  The requested units for the data.

    Outputs:
      output:  A sanitized SST data structure.  Any instrument specific corrections should be applied.
               Extraneous fields are discarded.  All dimensions should be in ascending order.
               Structure definition:
                   ** Structure <afc6c05c>, 10 tags, length=30736, data length=30736, refs=1:
                   DATA            FLOAT     Array[16, 64]
                   TIME            DOUBLE       1.1746086e+09
                   END_TIME        DOUBLE       1.1746086e+09
                   PHI             FLOAT     Array[16, 64]
                   DPHI            FLOAT     Array[16, 64]
                   THETA           FLOAT     Array[16, 64]
                   DTHETA          FLOAT     Array[16, 64]
                   ENERGY          FLOAT     Array[16, 64]
                   DENERGY         FLOAT     Array[16, 64]
                   BINS            INT       Array[16, 64]
                   CHARGE          FLOAT          0.000000
                   MASS            FLOAT         0.0104390
                   MAGF            FLOAT     Array[3]
                   SC_POT          FLOAT          0.000000

    Keywords:
      sst_sun_bins:  The bin numbers that should be flagged as contaminated by sun and interpolated
      sst_method_clean: how to decontaminate the sst data.  Right now the only option is 'manual', but selects a good set of default sst_sun_bins, if not user specified.
      sst_min_energy: Set to minimum energy to toss bins that are having problems from instrument degradation.
    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-08-24 18:29:05 -0700 (Wed, 24 Aug 2016) $
    $LastChangedRevision: 21724 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_sst.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_sst.pro)

## THM_PGS_CLEAN_SUPPORT

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

    Procedure:
      thm_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
      mag_tvar_in: String specifying a tplot variable containing magnetic field data
      sc_pot_tvar_in: String specifying a tplot variable containing spacecraft potential data

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

    Notes:
      If no valid tplot variables are specified for:
        magnetic field - vector will be [0,0,0] at all times
        spacecraft potential - will be 0

    $LastChangedBy: jimm $
    $LastChangedDate: 2019-02-19 11:17:18 -0800 (Tue, 19 Feb 2019) $
    $LastChangedRevision: 26643 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_support.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_support.pro)

## THM_PGS_DIST_ARRAY_DATA

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

    Procedure:
      thm_pgs_dist_array_data

    Purpose:
      Returns the selected data structure, increments the dist_array indexes

    Input:
      dist_array: A dist-array data structure
      dist_ptr_index=dist_ptr_index: dist_ptr_index for the dist_array(modifed by this routine)
      dist_seg_index=dist_seg_index: dist_seg_index for the dist_array(modified by this routine)
    Output:
      data=data:  The data structure idenfitied by the indexes

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-07-12 13:17:02 -0700 (Fri, 12 Jul 2013) $
    $LastChangedRevision: 12674 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_data.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_data.pro)

## THM_PGS_DIST_ARRAY_START

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

    Procedure:
      thm_pgs_dist_array_start

    Purpose:
      Identifies the start indexes for the dist_array data structure

    Input:
      dist_array: A dist-array data structure
      time_idx: A 1-d array of indexes into a time array
    Output:
      dist_ptr_idx: The index to the starting mode for the requested time range
      dist_seg_idx: The index to the first sample of the mode for the requested time range

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-07-12 11:09:50 -0700 (Fri, 12 Jul 2013) $
    $LastChangedRevision: 12671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_start.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_start.pro)

## THM_PGS_DIST_ARRAY_TIMES

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

    Procedure:
      thm_pgs_dist_array_times

    Purpose:
      Concatenates a 1-d array of times from a thm_part_dist_array structure

    Input:
      dist_array: A dist-array data structure

    Output:
      times: An array of times

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-07-12 11:09:50 -0700 (Fri, 12 Jul 2013) $
    $LastChangedRevision: 12671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_times.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_times.pro)

## THM_PGS_EXPAND_YAXIS

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

    Procedure:
      thm_pgs_expand_yaxis

    Purpose:
      Convert single-dimension y axes from new spectrogram code
      to two dimensions to match the output from the old code.

    Calling Sequence
      thm_pgs_expand_axis, tplotnames

    Inputs:
      tplotnames: list of tplot variables whose y axes may need
                  expansion to two dimensions

    Outputs:
      none

    Keywords:
      none

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2013-09-11 16:40:34 -0700 (Wed, 11 Sep 2013) $
    $LastChangedRevision: 13023 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_expand_yaxis.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_expand_yaxis.pro)

## THM_PGS_GET_DATATYPE

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

    Procedure:
      thm_pgs_get_datatype

    Purpose:
      Returns probe and datatype designations from standard particle distribution pointer array.

    Arguments:
      dist_array: pointer(s) to particle structure arrays

    Output Keywords:
      probe: String denoting probe
      datatype: String denoting particle data type (e.g. peif, pseb)
      instrument: String denoting instrument ('esa', 'sst', 'combined')

    History:
      2015-08-24 - Allow to work on non-THEMIS data for testing with MMS

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-08-24 11:31:21 -0700 (Mon, 24 Aug 2015) $
    $LastChangedRevision: 18591 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_get_datatype.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_get_datatype.pro)

## THM_PGS_MAKE_FAC

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

    PROCEDURE: thm_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 thm_cotrans is waaaay too slow if fed single vectors at a time
      If an error occurs fac_output will be undfined on return

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-02-10 19:03:17 -0800 (Wed, 10 Feb 2016) $
    $LastChangedRevision: 19949 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_fac.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_fac.pro)

## THM_PGS_MAKE_TPLOT

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

    Procedure:
      thm_pgs_make_tplot

    Purpose:
      Create tplot variable with standard spectrogram settings.

    Input:
      name: name of new tplot variable to create
      x: x axis (time)
      y: y axis
      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:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-04-05 13:48:59 -0700 (Wed, 05 Apr 2017) $
    $LastChangedRevision: 23120 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_tplot.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_tplot.pro)

## THM_PGS_MOMENTS

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

    Procedure:
      thm_pgs_moments

    Purpose:
      Calculates moments from a simplified particle data structure.

    Arguments:
      data: single sanitized data structure

    Input Keywords:
      get_error: Flag indicating that error esitmates (sigma) should be returned
      mag_data: Optional array containing magnetic field vectors for all time samples
      scpot_data: Optional array containing spacecraft potential data for all time samples
      index: Index into mag_data/scpot_data specifying which sample to use

    Output Keywords:
      moments: Structure output from moments_3d containing the data.
      sigma: Structure output from moments_3d containing error estimates.

    Notes:

    $LastChangedBy: jimm $
    $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $
    $LastChangedRevision: 24078 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments.pro)

## THM_PGS_MOMENTS_TPLOT

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

    Procedure:
      thm_pgs_moments_tplot

    Purpose:
      Creates tplot variables from moments structures

    Arguments:
      moments:  Array of moments structures returned from moments_3d

    Keywords:
      get_error: Flag indicating that the current moment structure
                 contains error estimates.
      prefix: Tplot variable name prefix (e.g. 'tha_peif_')
      suffix: Tplot variable name suffix
      tplotnames: Array of tplot variable names created by the parent
                  routine.  Any tplot variables created in this routine
                  should have their names appended to this array.
      coord: if set, then velocity, flux, pressure tensor and momentum
             flux tensor variables are created for the
             input coordinate system, in addition to the DSL variables

    Notes:
      Much of this code was copied from thm_part_moments.pro

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-07-10 22:30:45 -0700 (Thu, 10 Jul 2025) $
    $LastChangedRevision: 33445 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments_tplot.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments_tplot.pro)

## THM_PGS_SET_SPEC_ZLIMITS

[Previous Routine] [List of Routines]

    PROCEDURE: thm_pgs_set_spec_zlimits
    PURPOSE:
      Helper routine for thm_part_products
      Sets zlimits to good default minimums for spectrograms

    Inputs(required):
     in_name: name or names of the tplot variable to be modified
     units: of in_name(s) lower-case string

    Outputs:
      None, just mutates in_name

    Notes:
      Uses a fixed formula for limits.  They vary a little bit for different possible unit selections

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-09-16 10:56:21 -0700 (Mon, 16 Sep 2013) $
    $LastChangedRevision: 13039 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_set_spec_zlimits.pro $

(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_set_spec_zlimits.pro)