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

Last modified: Wed Oct 1 18:17:54 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles/moments

- THM_APPLY_ESA_MOM_DTC
  Corrects ESA on-board moments for dead time. Note that this will
- THM_CORRECTED_PXXM_POT
  Returns an offset corrected time-shifted value of the PXXM pot variable from
- THM_ESA_DTC4MOM
  calculates a dead-time correction value for ESA particle moments,
- THM_GMOM_QUALITY_FLAGS
- THM_LOAD_MOM
- THM_LOAD_MOM_L2
- THM_PART_MOMENTS
  Generate moments from particle data.
- THM_PART_MOMENTS_APPLY_ECLIPSE
  Apply eclipse corrections (when present) to 3D data structures
- THM_PART_SPEC_CALC
- THM_READ_MOM_CAL_FILE
  reads in the text version of the MOM cal

# Routine Descriptions

## THM_APPLY_ESA_MOM_DTC

[Next Routine] [List of Routines]

    NAME:
     thm_apply_esa_mom_dtc
    PURPOSE:
     Corrects ESA on-board moments for dead time. Note that this will
     apply the dead-time correction to all of the moments for the given
     probe and species.
    CALLING SEQUENCE:
     thm_apply_esa_mom_dtc, probe=probe, instrument=instrument,
                            out_suffix=out_suffix,in_suffix=in_suffix
    INPUT:
     All via keyword
    OUTPUT:
     None explicit, a number of tplot variables are created.
    KEYWORDS:
     probe='a','b','c','d' or 'e'
     instrument='peim' or 'peem', similar in use to the 'instrument'
                keyword for thm_part_moments
     use_esa_mode = 'f','r', or 'b', use this mode for the ESA data to get
                    the dead time correction, the default is 'f'
     out_suffix= a suffix to add to new tplot variables for the
                 moments. The default is the null string, so that
                 variables are overwritten.
     in_suffix= if set, only variables with this suffix will be
                corrected, to avoid correcting variables that have been
                loaded without corrections.
    HISTORY:
     13-may-2011, jmm, jimm@ssl.berkeley.edu
     27-may-2011, jmm, dropped save_esa_vars keywords, to avoid suffix
                  confusion, also passes out_suffix keyword through to
                  thm_esa_dtc4mom
     9-aug-2011, jmm, added in_suffix keyword
     $LastChangedBy: aaflores $
     $LastChangedDate: 2015-04-30 15:28:49 -0700 (Thu, 30 Apr 2015) $
     $LastChangedRevision: 17458 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_apply_esa_mom_dtc.pro $

(See projects/themis/spacecraft/particles/moments/thm_apply_esa_mom_dtc.pro)

## THM_CORRECTED_PXXM_POT

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

    NAME:
     thm_corrected_pxxm_pot
    PURPOSE:
     Returns an offset corrected time-shifted value of the PXXM pot variable from
     MOM (on-board moment) files
    CALLING SEQUENCE:
     thm_corrected_pxxm_pot,suffix=suffix
    INPUT:
     No Input, the program detects the presence of variables
     'thx_pxxm_pot' and corrects each one.
    OUTPUT:
     None explicit, tplot variables are created which are time-shifted
     and offset corrected pxxm_pot variables.
    KEYWORDS:
     suffix = is set, this will be appended to the variable names, the
              default value is '_corrected'
     no_time_shift = if set, no time shifting is performed.
    HISTORY:
     8-feb-2010, jmm, jimm@ssl.berkeley.edu
    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-04-27 11:26:29 -0700 (Mon, 27 Apr 2015) $
    $LastChangedRevision: 17433 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_corrected_pxxm_pot.pro $

(See projects/themis/spacecraft/particles/moments/thm_corrected_pxxm_pot.pro)

## THM_ESA_DTC4MOM

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

    NAME:
     thm_esa_dtc4mom
    PURPOSE:
     calculates a dead-time correction value for ESA particle moments,
     which then can be applied to on-board MOM data.
    CALLING SEQUENCE:
     thm_esa_dtc4mom, probe=probe, trange=trange
    INPUT:
     All via keyword
    OUTPUT:
     None explicit, a number of tplot variables are created.
    KEYWORDS:
     probe='a','b','c','d' or 'e'
     trange = an input time range, otherwise the current time range is
              used.
     noload = if set, make the assumption that the data is there, and
              don't load it
     use_esa_mode = 'f','r', or 'b', use this mode for the ESA data to get
                    the dead time correction, the default is 'f'
     scpot_correct = if set, use thm_load_esa_pot to correct for SC
                     potential in moments. The default is to avoid the correction
    HISTORY:
     10-may-2011, jmm, jimm@ssl.berkeley.edu
     27-may-2011, jmm, This version deletes the temporary ESA moments
     5-dec-2014, jmm, uses thm_part_products directly
     10-jan-2017, jmm, set ESA background removal to 0
     $LastChangedBy: jimm $
     $LastChangedDate: 2017-01-10 12:46:45 -0800 (Tue, 10 Jan 2017) $
     $LastChangedRevision: 22565 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_esa_dtc4mom.pro $

(See projects/themis/spacecraft/particles/moments/thm_esa_dtc4mom.pro)

## THM_GMOM_QUALITY_FLAGS

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

    Procedure:
      thm_sst_quality_flags

    Description:
      makes a bitpacked tplot variable containing quality flags for ground moments

      ESA:
      bit0 = pre-efi boom deployment (using zeroed spacecraft potential)
      bit1 = counter overflow flag
      bit2 = solar wind mode flag(disabled)
      bit3 = flow flag, flow less than threshold is flagged
      bit4 = earth shadow
      bit5 = lunar shadow
      bit6 = manuever flag

      SST:
      Bit 8: saturated. (psef_count_rate > 10k)
      Bit 9: attenuator error (stuck attenuator or incorrect indicator)
      Bit 10: too low(<2.5 s) or too high(>5s) spin period
      Bit 11: earth shadow
      Bit 12: lunar shadow

      Set timespan by calling timespan outside of this routine.(e.g. time/duration is not an argument)

      Keywords:
        probe:the probe letter string for the quality flags(e.g. 'a')
        esa_flow_threshold:  flow threshold for quality flag bit 3
        esa_datatype:  the datatype string for the esa flags (e.g. 'peif')
        sst_datatype: the datatype string for sst flags (e.g. 'psif')
        time_array: the time array(or tplot variable) for interpolation(if not provided, interpolates onto ESA)

     $LastChangedBy: jimm $
     $LastChangedDate: 2017-05-03 16:44:48 -0700 (Wed, 03 May 2017) $
     $LastChangedRevision: 23267 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_gmom_quality_flags.pro $

(See projects/themis/spacecraft/particles/moments/thm_gmom_quality_flags.pro)

## THM_LOAD_MOM

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

    Procedure: THM_LOAD_MOM

    Purpose:  Loads THEMIS moments data

    keywords:
      probe = Probe name. The default is 'all', i.e., load all available probes.
              This can be an array of strings, e.g., ['a', 'b'] or a
              single string delimited by spaces, e.g., 'a b'
      datatype = The type(s) of data to be loaded.  May be single string of
                 space-separate elements.  All data will be loaded if not set.

                 For level 1 this can specify type and specific quantity.
                   e.g.  'psim', 'flags', 'ptem_density', 'pxxm_pot'

                 For level 2 it must specify a specific variable.
                   e.g.  'peim_flux', 'ptem_velocity_dsl'

      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
      level = the level of the data, the default is 'l1', or level-1
              data. A string (e.g., 'l2') or an integer can be used. 'all'
              can be passed in also, to get all levels.
      coord = (optional) String denoting coordinates system to transform
              valid 3-vectors into (e.g. 'gsm').
      CDF_DATA: named variable in which to return cdf data structure: only works
              for a single spacecraft and datafile name.
      VARNAMES: names of variables to load from cdf: default is all.
      /GET_SUPPORT_DATA: load support_data variables as well as data variables
                          into tplot variables.
      /DOWNLOADONLY: download file but don't read it.
      /valid_names, if set, then this routine will return the valid probe, datatype
              and/or level options in named variables supplied as
              arguments to the corresponding keywords.
      files   named variable for output of pathnames of local files.
              WARNING: performing operations on the file paths returned by this
              keyword will break abstraction.  This can decrease the maintainability
              of code based upon thm_load_mom.
      /VERBOSE  set to output some useful info
      raw     if set, then load raw data, without calibrating
      type    added for compatibility with other THM_LOAD routines, if
              set to 'raw', then load raw data with no calibration,
              otherwise the default is to load calibrated data.
      /NO_TIME_CLIP: Disables time clipping, which is the default
      /dead_time_correct: If set, then calculate dead time correction
                          based on ESA moments
      /return_mag_rmat: If set, return a tplot variable (ntimes, 3, 3)
                        for the rotation matrix used to rotate
                        to field-aligned "_mag" variables. Note that this
                        matrix needs to be inverted to be used correctly
                        with TVECTOR_ROTATE, as here it is used with
                        velocity as a column vector.
    Example:
       thm_load_mom,/get_suppport_data,probe=['a', 'b']
    Notes:
      Written by Davin Larson Jan 2007.
      Updated keywords KRB Feb 2007
      If you aren't getting data and can't figure out why try
      increasing your debug output level using:
      'dprint,setdebug=3'

      New calibrations for ESA moments solar wind mode and non-solar wind
      mode added Jul 23,2010 by pcruce (under Jim McFadden's direction.)
      Detailed descriptions of methods in code.  These updated calibrations correct
      most of the discrepancy between ground and on-board moments.
      Some uncorrectable difference remains because on-board calculations
      don't account for variation in energy sweep, different spacecraft
      potential, and efficiency.

     $LastChangedBy: jimm $
     $LastChangedDate: 2019-04-26 15:25:09 -0700 (Fri, 26 Apr 2019) $
     $LastChangedRevision: 27102 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_load_mom.pro $

(See projects/themis/spacecraft/particles/moments/thm_load_mom.pro)

## THM_LOAD_MOM_L2

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

    Procedure: THM_LOAD_MOM_l2

    Purpose:  Loads THEMIS Level 2 moments data

    keywords:
      probe = Probe name. The default is 'all', i.e., load all available probes.
              This can be an array of strings, e.g., ['a', 'b'] or a
              single string delimited by spaces, e.g., 'a b'
      datatype = The type of data to be loaded, for this case, there is only
              one option, the default value of 'fgm', so this is a
              placeholder should there be more that one data type. 'all'
              can be passed in also, to get all variables.
      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
      /DOWNLOADONLY: download file but don't read it.
      /valid_names, if set, then this routine will return the valid probe, datatype
              and/or level options in named variables supplied as
              arguments to the corresponding keywords.
      files   named variable for output of pathnames of local files.
      /VERBOSE  set to output some useful info
      /NO_TIME_CLIP: Disables time clipping, which is the default
    Example:
       thm_load_mom,/get_suppport_data,probe=['a', 'b']
    Notes:
      Temporary version, to avoid conflicts, but can read Level 2 data, jmm
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-04-22 14:24:42 -0700 (Mon, 22 Apr 2019) $
     $LastChangedRevision: 27056 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_load_mom_l2.pro $

(See projects/themis/spacecraft/particles/moments/thm_load_mom_l2.pro)

## THM_PART_MOMENTS

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

    PROCEDURE: thm_part_moments

    PURPOSE:
      Generate moments from particle data.
      This routine is a wrapper that allows backwards compatibility
      with calls to the old moments routine (thm_part_moments.pro).

    Input Keywords:
      Argument description inline below.

    Deprecated Keywords:

    Notes:
      Old version in particles/deprecated

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

(See projects/themis/spacecraft/particles/moments/thm_part_moments.pro)

## THM_PART_MOMENTS_APPLY_ECLIPSE

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

    PURPOSE:
      Apply eclipse corrections (when present) to 3D data structures
      within thm_part_moments.pro

    ARGUMENTS:
      dat: Valid 3D data structure

    KEYWORDS:
      domega: Array of weights used inside the Wind routines to calculate
              vector and tensore components.  This array should be set to
              0 if a correction is being applied or if a correction was
              applied on the last loop.
      eclipse: Flag used by this routine to determine when an ecplise
               starts or ends (assists output messages). Should be set
               to 1 at the start of an eclipse and 0 at the end.
      previous: Stores the delta phi value from the last time through the
                loop.  Helps determine when domega should be zeroed.

    NOTES:

(See projects/themis/spacecraft/particles/moments/thm_part_moments_apply_eclipse.pro)

## THM_PART_SPEC_CALC

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

     procedure: thm_part_spec_calc
     Purpose: Calculates moments and spectra for themis particle distributions.
     Author: Davin Larson 2007
     $Id: thm_part_spec_calc.pro 17458 2015-04-30 22:28:49Z aaflores $

(See projects/themis/spacecraft/particles/moments/thm_part_spec_calc.pro)

## THM_READ_MOM_CAL_FILE

[Previous Routine] [List of Routines]

    NAME:
     thm_read_mom_cal_file
    PURPOSE:
     reads in the text version of the MOM cal
     file. tha_l1_mom_cal_v02.txt.
     Note that the cal file for THEMIS A is used for the data for all
     probes.
    CALLING SEQUENCE:
     caldata = thm_read_mom_cal_file(probe=probe)
    INPUT:
     all via keyword
    OUTPUT:
     caldata = a structure containing scalings for normal (mom_scale) and
               solar wind (mom_scale_sw1) modes. Also contains a single
               value used for scaling the spacecraft potential
               (scpot_scale)
    KEYWORDS:
     probe = in here in case somebody decides to create a separate file
             for each probe.
     cal_file = the name of the calibration file, output so that
                thm_load_mom message doesn't crash
    HISTORY:
     4-Oct-2010, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: aaflores $
     $LastChangedDate: 2015-04-27 11:26:29 -0700 (Mon, 27 Apr 2015) $
     $LastChangedRevision: 17433 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/moments/thm_read_mom_cal_file.pro $

(See projects/themis/spacecraft/particles/moments/thm_read_mom_cal_file.pro)