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

Last modified: Mon Nov 3 18:16:57 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles/deprecated

- THM_PART_ENERGY_INTERPOLATE
- THM_PART_GETSPEC_OLD[1]
  Generates tplot variables containing energy-time angular particle spectra
- THM_PART_GETSPEC_OLD[2]
- THM_PART_MOMENTS2[1]
- THM_PART_MOMENTS2[2]
- THM_PART_MOMENTS_OLD
- THM_PART_SPHERE_INTERPOLATE
- THM_PART_WRITE_ASCII

# Routine Descriptions

## THM_PART_ENERGY_INTERPOLATE

[Next Routine] [List of Routines]

    PROCEDURE: thm_part_energy_interpolate
    PURPOSE:  Interpolate particle data by energy between sst & esa distributions using a weighted curve fitting routine

    INPUTS:
      dist_sst: SST particle distribution structure in flux
      dist_esa: ESA particle distribution structure in flux
      energies: The set of target energies to interpolated the SST to.

    OUTPUTS:
       Replaces dist_sst with the interpolated data set

    KEYWORDS:
      error: Set to 1 on error, zero otherwise

     NOTES:
       #1 The number of time samples and the times of those samples must be the same for dist_sst & dist_esa (use thm_part_time_interpolate.pro)
       #2 The number of angles and the angles of each sample must be the same for dist_sst & dist_esa (use thm_part_sphere_interpolate.pro)
     SEE ALSO:
       thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert,thm_part_time_interpolate.pro,thm_part_sphere_interpolate.pro

      $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/deprecated/thm_part_energy_interpolate.pro $

(See projects/themis/spacecraft/particles/deprecated/thm_part_energy_interpolate.pro)

## THM_PART_GETSPEC_OLD[1]

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

    PROCEDURE: thm_part_getspec
    PURPOSE:
    	Generates tplot variables containing energy-time angular particle spectra
    	for any angle range and/or any energy range.

    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'
     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.
     phi    = Angle range of interest (2 element array) in degrees relative to
              probe-sun direction in the probe's spin plane. Specify angles in
              ascending order (e.g. [90, 180]) to specify the 'daylight'
              hemisphere in DSL coordinates. Default is all 360 degrees (e.g.
              [0, 360]). If the phi range is greater than 360 degrees, then the phi
              bins at the beginning of the phi range are added and wrapped around
              the end of phi range. For example, if phi=[-90,360], the phi bins
              corresponding to 270-360 degrees are appended to the bottom of the plot.
              Also controls which bins are selected for
              pitch/gyrovelocity spectra. Phi is limited to be between -360
              and 720 degrees. Note that, if the ENERGY keyword is set (as
              is true in the default case). This is also true for 'pa'
              and 'gyro' cases.
     theta  = Angle range of interest (2 element array) in degrees relative to
              spin plane, e.g. [-90, 0] or [-45, 45] in the probe's spin plane.
              Specify in acending order. Default is all (e.g. [-90, 90]). Also
              controls which bins are selected for pitch/gyrovelocity spectra.
     pitch  = Angle range of interest (2 element array) in degrees relative to
              the magnetic field. Default is all (e.g. [0, 180]). Has no effect
              on phi/theta spectra plots.
     gyro   = Gyrovelocity angle range of interest (2 element array) in degrees.
              Same rules as specifying phi apply to gyrophse. Default is all
              (e.g. [0, 360]). Has no effect on phi/theta spectra plots.
     erange = Energy range (in eV) of interest (2 element array). Default is all.
     data_type = The type of data to be loaded (e.g. ['peif', 'peef'])
     start_angle = Angle at which to begin plotting the data the bottom of the
                   plot along the y-axis. At this time this works for phi only. If
                   not set, keyword defaults to first element of phi input.
     suffix = Suffix to add to tplot variable names.
     /AUTOPLOT: Set to activiate a simple plotting routine to display tplot
                variables created by this routine.
     /ENERGY: Set to output tplot variables containing the energy spectrum of the
              energy/angle ranges input above.
     angle  = Type of angular spectrum tplot variable created and plotted using the
              energy/angle ranges input above e.g. 'phi'. Default is 'phi'. The
              type of angular spectra is appended to its corresponding tplot
              variable name. All possible options are:
              phi   = phi angular spectrum
              theta = theta angular spectrum
              pa    = pitch angular spectrum (only works with full angle ranges)
              gyro  = gyrovelocity angular spectrum  (only works with full angle
                      ranges)
              NOTE: If neither of ENERGY and ANGLE keywords are specified, then
                    then both are turned on with ANGLE defaulting to 'phi'.
     /GET_SUPPORT_DATA: load support_data variables as well as data variables into
                        tplot variables.
     regrid = [m,n]  Number of angle bins, used to re-grid (2-element array) along
              phi (gyrovelocity) and theta (pitch), respectively, when calculating
              pitch/gyrovelocity angle spectrum. For example, e.g. [32,16] creates
              a regularly-spaced array of 32 phi angles by 16 theta angles that
              resample the probe(s) native angle bin array. Default is [16,8].
              Keyword has no effect on phi and theta spectragrams. Accuracy of the
              spectragrams increases when more angle bins are used to re-grid.
              Suitable numbers for m and n are numbers like 2^k. So far, k=2-6 has
              been tested and work. Other numbers will work provided 180/n and
              360/m are rational.
     other_dim = Keyword passed to THM_FAC_MATRIX_MAKE for conversion to field
                 aligned coordinates to create pitch angle and gyrovelocity
                 spectra. See THM_FAC_MATRIX_MAKE for valid input. Default is
                 'mphigeo'.
     /NORMALIZE: Set to normalize the flux for each time sample to 0-1.
     badbins2mask = A 0-1 array that indicates which SST bins will be masked with
                    NaN to eliminate things like sun contamination. The array
                    should have the same number of elements as the number of angle
                    bins for a given data type. A 0 indicates that will be masked
                    with a NaN. This is basically the output from the bins argument
                    of EDIT3DBINS.
     datagap = Maximum time gap in seconds over which to interpolate the plot.
               Sets the DATAGAP flag in the dlimits which SPECPLOT uses to
               interpolate pixels in time gaps less than DATAGAP.  Use this keyword
               when overlaying spectra plots, allowing the underlying spectra to be
               shown in the data gaps of the overlying spectra.  Default is zero.
     fractional_counts = Flag to keep the ESA unit conversion routine from rounding
                         to an even number of counts when removing the dead time
                         correction (no effect if input data already in counts,
                         no effect on SST data).

      dist_array:  Provide an array of data instead of having thm_part_getspec/thm_part_moments2 load the data directly.
        This allows preprocessing/sanitization operations to be performed prior to moment generation.
        See thm_part_dist_array.pro, thm_part_conv_units.pro

    ESA PEER/PEIR/PEIF Background Removal Keywords:

    /bdnd_remove:  Turn on ESA background removal.

    bgnd_type(Default 'anode'): Set to string naming background removal type:
    'angle','omni', or 'anode'.

    bgnd_npoints(Default = 3): Set to the number of lowest values points to average over when determining background.

    bgnd_scale(Default=1): Set to a scaling factor that the background will be multiplied by before it is subtracted

    GUI-RELATED KEYWORDS:
     /GUI_FLAG: Flag tells code to recognize status bar and history window objects.
     gui_statusBar = Object reference to status bar object in GUI.
     gui_historyWin = Object reference to history window object in GUI.

    EXAMPLE: thm_part_getspec, probe='d', trange=['07-06-17','07-06-19']

    SEE ALSO:
    	THM_CRIB_PART_GETSPEC, THM_PART_MOMENTS2, THM_PART_GETANBINS, THM_LOAD_SST,
       THM_LOAD_ESA_PKT, THM_FAC_MATRIX_MAKE,THM_REMOVE_SUNPULSE,THM_CRIB_SST_CONTAMINATION

    NOTES:  For documentation on sun contamination correction keywords that
      may be passed in through the _extra keyword please see:
      thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro

    BACKGROUND REMOVAL(BGND) Description, Warnings and Caveats(from Vassilis Angelopoulos):
     This code allows for keywords that permit omni-directional or anode-dependent
     background removal from penetrating electrons in the ESA ion and electron
     detectors. Anode-dependent subtraction is used when possible by default,
     i.e., when angle information is available; but user has full control by
     keyword specification. Default bgnd estimates use 3 lowest counts/s values.
     Scaling of the background (artificial scaling) can also allow playing with
     background estimates to account for noise statistics in the background itself.
     The parameters that have worked well for me during high bgnd levels are:
     ,/bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.5

     The same keywords when used in thm_part_getspec, and thm_part_moments
     are understood and passed to the data extraction routines, such that
     they will do the removal before computing moments or spectra.

     This background subtraction to be used at the inner magnetosphere,
     or when SST electron fluxes indicate presence of significant electron
     fluxes at the satellite (injections). At quiet times the code tends to remove
     real fluxes, so beware.

    CREATED BY:	Bryan Kerr

      $LastChangedBy: bckerr $
      $LastChangedDate: 2008-06-13 13:29:12 -0700 (Fri, 13 Jun 2008) $
      $LastChangedRevision: 3204 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_getspec.pro $

(See projects/themis/spacecraft/particles/deprecated/thm_part_getspec_old.pro)

## THM_PART_GETSPEC_OLD[2]

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

    Purpose:
     Helper function to check support data's existence and time range
    (Main procedure further below)

    Input:
     tvar - string representing tplot variable
     tr - two element numerical time range

    Output:
     Returns 1 if time range is covered by the data

(See projects/themis/spacecraft/particles/deprecated/thm_part_getspec_old.pro)

## THM_PART_MOMENTS2[1]

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

    PROCEDURE: thm_part_moments2
    PURPOSE: Calculates moments and spectra for themis particle distributions.

    SEE ALSO:
    	THM_CRIB_PART_GETSPEC, THM_PART_GETSPEC, THM_PART_GETANBINS, THM_LOAD_SST,
       THM_LOAD_ESA_PKT, THM_FAC_MATRIX_MAKE,THM_CRIB_SST_CONTAMINATION,
       THM_SST_REMOVE_SUNPULSE

      dist_array:  Provide an array of data instead of having thm_part_getspec/thm_part_moments2 load the data directly.
        This allows preprocessing/sanitization operations to be performed prior to moment generation.
        See thm_part_dist_array.pro, thm_part_conv_units.pro

    NOTE:
      For documentation on sun contamination correction keywords that
      may be passed in through the _extra keyword please see:
      thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro

    MODIFIED BY:	Bryan kerr from Davin Larson's thm_part_moments

      $LastChangedBy: pcruce $
      $LastChangedDate: 2008-07-21 17:38:17 -0700 (Mon, 21 Jul 2008) $
      $LastChangedRevision: 3298 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/moments/thm_part_moments2.pro $

(See projects/themis/spacecraft/particles/deprecated/thm_part_moments2.pro)

## THM_PART_MOMENTS2[2]

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

    HELPER Function. (Main routine below)

    Purpose: Checks returnd error messages from underlying routines
             against previously returned messages. If the message
             is new it will be printed and added to the stored
             message array.

             This should allow messages generated within the loop
             over time to be printed once instead of hundreds or
             thousands of times.

    Usage: thm_part_moments2_msg, msg_ball, msg, dlevel=1

    Arguments:
           msg_ball: string array of all previously printed messages
           msg: string or string array of newly returned message(s)

    Keywords:
           dlevel: Not a formal keyword, but passed through _extra

    Notes: This routine assumes it will get correct input,
           please do not disappoint it.

(See projects/themis/spacecraft/particles/deprecated/thm_part_moments2.pro)

## THM_PART_MOMENTS_OLD

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

     procedure: thm_part_moments_old

     Purpose: Calculates moments and spectra for themis particle distributions.

      For documentation on sun contamination correction keywords that
      may be passed in through the _extra keyword please see:
      thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro

    Keywords:
      dist_array:  Provide an array of data instead of having thm_part_moments load the data directly.
        This allows preprocessing/sanitization operations to be performed prior to moment generation.
        See thm_part_dist_array.pro, thm_part_conv_units.pro
      fractional_counts:  Flag to keep the ESA unit conversion routine from rounding to an even
                          number of counts when removing the dead time correction.
                          (no effect if input data already in counts, no effect on SST data)

    ESA PEER/PEIR/PEIF Background Removal Keywords:

    /bdnd_remove:  Turn on ESA background removal.

    bgnd_type(Default 'anode'): Set to string naming background removal type:
    'angle','omni', or 'anode'.

    bgnd_npoints(Default = 3): Set to the number of lowest values points to average over when determining background.

    bgnd_scale(Default=1): Set to a scaling factor that the background will be multiplied by before it is subtracted

    BACKGROUND REMOVAL(BGND) Description, Warnings and Caveats(from Vassilis Angelopoulos):
     This code allows for keywords that permit omni-directional or anode-dependent
     background removal from penetrating electrons in the ESA ion and electron
     detectors. Anode-dependent subtraction is used when possible by default,
     i.e., when angle information is available; but user has full control by
     keyword specification. Default bgnd estimates use 3 lowest counts/s values.
     Scaling of the background (artificial scaling) can also allow playing with
     background estimates to account for noise statistics in the background itself.
     The parameters that have worked well for me during high bgnd levels are:
     ,/bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.5

     The same keywords when used in thm_part_getspec, and thm_part_moments
     are understood and passed to the data extraction routines, such that
     they will do the removal before computing moments or spectra.

     This background subtraction to be used at the inner magnetosphere,
     or when SST electron fluxes indicate presence of significant electron
     fluxes at the satellite (injections). At quiet times the code tends to remove
     real fluxes, so beware.

     Author: Davin Larson 2007
     $Id: $

(See projects/themis/spacecraft/particles/deprecated/thm_part_moments_old.pro)

## THM_PART_SPHERE_INTERPOLATE

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

    PROCEDURE: thm_part_sphere_interpolate
    PURPOSE:  Interpolate particle data to match the look direcitons of another distribution

    INPUTS:
      source: A particle dist_data structure to be modified by interpolation to match target
      target: A particle dist_data structure whose look directions will be matched

    OUTPUTS:
       Replaces source with a spherically interpolated target

    KEYWORDS:
      error: Set to 1 on error, zero otherwise

     NOTES:
       #1 Interpolation done using IDL library routine "griddata"

       #2 This code assumes that source & target have been time interpolated to match each other

       This has a ton of TBDs, we need to come back and fix them when time is available.  With TBDs this code will not have general purpose utility...
     SEE ALSO:
       thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert,thm_part_time_interpolate.pro

      $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/deprecated/thm_part_sphere_interpolate.pro $

(See projects/themis/spacecraft/particles/deprecated/thm_part_sphere_interpolate.pro)

## THM_PART_WRITE_ASCII

[Previous Routine] [List of Routines]

    Procedure:
      thm_part_write_ascii

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

    Calling Sequence:
      thm_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 themis
      data with stel3d

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-23 18:52:50 -0700 (Mon, 23 May 2016) $
    $LastChangedRevision: 21180 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/deprecated/thm_part_write_ascii.pro $

(See projects/themis/spacecraft/particles/deprecated/thm_part_write_ascii.pro)