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

Last modified: Sat Aug 2 18:17:35 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles/combined

- THM_CMB_CLEAN_ESA
- THM_CMB_CLEAN_SST
- THM_CONVERT_CMB_UNITS
- THM_ESA_DETECT_OVERLAP
  Detects mode overlap that occasionally occurs in ESA data, this
- THM_PART_COMBINE
- THM_PART_ENERGY_INTERP
  Interpolate particle data by energy between sst & esa distributions using
- THM_PART_MERGE_DISTS
- THM_PART_SPHERE_INTERP
- THM_PART_TIME_INTERPOLATE

# Routine Descriptions

## THM_CMB_CLEAN_ESA

[Next Routine] [List of Routines]

    Procedure:
      thm_cmb_clean_sst

    Purpose:
      Runs standard ESA sanitation routine on data array.
        -removes excess fields in data structures
        -performs unit conversion (if UNITS specified)
        -removes retrace bin (top energy)
        -reverses energies to be in ascending order

    Calling Sequence:
      thm_cmb_clean_esa, dist_array, [,units=units]

    Input:
      dist_array:  ESA particle data array from thm_part_dist_array
      units: String specifying output units

    Output:
      none, modifies input

    Notes:
      Further unit conversions will not be possible after sanitation
      due to the loss of some support quantities.

    $LastChangedBy: jimm $
    $LastChangedDate: 2020-08-12 13:44:20 -0700 (Wed, 12 Aug 2020) $
    $LastChangedRevision: 29018 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_cmb_clean_esa.pro $

(See projects/themis/spacecraft/particles/combined/thm_cmb_clean_esa.pro)

## THM_CMB_CLEAN_SST

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

    Procedure:
      thm_cmb_clean_sst

    Purpose:
      Runs standard SST sanitation routine on data array.
        -removes excess fields in data structures
        -performs unit conversion (if UNITS specified)
        -applies contamination removal (none or default bins)

    Calling Sequence:
      thm_cmb_clean_sst, dist_array [,units] [,sst_sun_bins=sst_sun_bins]

    Input:
      dist_array:  SST particle data array from thm_part_dist_array
      units: String specifying output units
      sst_sun_bins: Numerical list of contaminated bins to be removed
      sst_data_mask:  The name of a tplot variable containing a 1-dimensional, 0-1 array indicating SST samples to exclude(0=exclude,1=include),
                      If values don't match the times of particle data, they'll be nearest neighbor interpolated to match.

    Output:
      none, modifies input

    Notes:
      Further unit conversions will not be possible after sanitation
      due to the loss of some support quantities.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-07-18 12:21:54 -0700 (Mon, 18 Jul 2016) $
    $LastChangedRevision: 21480 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_cmb_clean_sst.pro $

(See projects/themis/spacecraft/particles/combined/thm_cmb_clean_sst.pro)

## THM_CONVERT_CMB_UNITS

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

    Procedure:
      thm_convert_cmb_units.pro

    Purpose:
      Unit conversion routine for combined (ESA+SST) particle distributions.

    Calling Sequence:
      This procedure is called implicitly by conv_units.pro

    Inputs:
      data: single combined distribution structure
      units: string specifying the target units (flux, eflux, or df)
      scale: set to named variable to pass out conversion factor

    Outputs:
      none, modifies input structure

    Notes:

    $LastChangedBy: jimmpc1 $
    $LastChangedDate: 2017-10-09 11:19:52 -0700 (Mon, 09 Oct 2017) $
    $LastChangedRevision: 24129 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_convert_cmb_units.pro $

(See projects/themis/spacecraft/particles/combined/thm_convert_cmb_units.pro)

## THM_ESA_DETECT_OVERLAP

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

    NAME:
    thm_esa_detect_overlap
    PURPOSE:
    Detects mode overlap that occasionally occurs in ESA data, this
    function compares the times for different ESA modes, if there is
    overlap, as indicated by a mode end time greater than or equal to the
    start time of the following mode, then an overlap is flagged. This
    should be used for reprocessing gmom data files that had entire modes
    removed due to overlaps.
    CALLING SEQUENCE:
    overlap_flag = thm_esa_detect_overlap(date = date, probe = probe)
    INPUT:
     via keyword
    OUTPUT:
    overlap_flag = 1, if overlap is detected, = 0 otherwise
    KEYWORDS:
    date = the date, the default is to let thm_load_esa_pkt prompt for
    one
    probe = the probe, the default is 'a'

    $LastChangedBy: jimm $
    $LastChangedDate: 2020-08-18 10:11:19 -0700 (Tue, 18 Aug 2020) $
    $LastChangedRevision: 29044 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_esa_detect_overlap.pro $

(See projects/themis/spacecraft/particles/combined/thm_esa_detect_overlap.pro)

## THM_PART_COMBINE

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

    Procedure:
      thm_part_combine.pro

    Purpose:
      Create combined particle distributions from ESA and SST data.
      This distributions acts as a new data type and can be passed
      to most THEMIS/SPEDAS particle product routines to create
      combined ESA/SST plots.

      Combined distributions are created in three steps:
        a) Linear time interpolation
             -time samples are matched by linearly interpolating the
              data set with lower time resolution to match the other
        b) Linear spherical interpolation
             -both data sets are interpolated onto the same angular grid
        c) Energy gap interpolation
             -once all times/angles match the gap between the
              ESA and SST energy ranges is filled in with a logarithmic
              linear interpolation (log(flux) vs log(energy))

    Calling Sequence:
      combined_dist = thm_part_combine( probe=probe, trange=trange,
                         esa_datatype=esa_datatype, sst_datatype=sst_datatype
                         [,units=units] [,regrid=regrid] [,energies=energies]
                         [,orig_esa=orig_esa] [,orig_sst=orig_sst] ... )

    Inputs:
      probe:  Probe designation (string).
      trange:  Two element array specifying time range (string or double).
      esa_datatype:  ESA datatype designation (string).
      sst_datatype:  SST datatype designation (string).
      units:  String specifying output units ('flux', 'eflux', or 'df')
      esa_dist:  Pass in manually loaded ESA particle data (see thm_part_dist_array)
                 Must be used with SST_DIST
      sst_dist:  Pass in manually loaded SST particle data (see thm_part_dist_array)
                 Must be used with ESA_DIST
      regrid:  Two element array specifying the number of points used to regrid
               the data in phi and theta respectively (int or float).
      energies:  Array specifying the energy interpolation mid-point targets for all output bins above the ESA.(gap & SST)
                 If unspecified, a hardcoded set of defaults is used.
      sst_sun_bins:  Array list of SST bins to mask (bin indices) (int).
      sst_min_energy: Set to minimum energy to toss bins that are having problems from instrument degradation. (float)
      esa_max_energy: Set to maximum energy to toss bins that are having problems from instrument contamination.(float)
      set_counts:  Set all data to this # of counts before interpolation (for comparison).
      only_sst: Interpolates ESA to match SST and returns SST(only) with interpolated bins.(Backwards compatibility: functionality of thm_sst_load_calibrate)
      interp_to_esa: Combined product but data interpolated to match ESA(instead of always interpolating to higher resolution)
      interp_to_sst: Combined product but data interpolated to match SST(instead of always interpolating to higher resolution)
      get_sun_direction: Load sun direction with particle data (for 2D slices)
      esa_bgnd_advanced: Apply advanced ESA background subtraction
                         Must call thm_load_esa_bkg first to calculate background
                         Disables default anode-based background removal
      extrapolate_esa: Flag to extrapolate from ESA data where no valid SST data exists
                       instead of throwing error.  Not recommended - use with caution!
      remove_one_count: removes all bins that are less than one count, suggestion from heli hietala(heli@igpp.ucla.edu)
      sst_data_mask:  The name of a tplot variable containing a 1-dimensional, 0-1 array indicating SST samples to exclude(0=exclude,1=include),
                      If values don't match the times of particle data, they'll be nearest neighbor interpolated to match.
      get_error:  if set, interpolates scaling factor needed for error propagation

    Outputs:
      combined_dist: Pointer array to combined distribution data.  This is analagous
                     to the arrays returned by thm_part_dist_array with each element
                     referencing a distinct mode, or in this case combination of modes.
      orig_esa: Pointer array to original ESA distribution data.
      orig_sst: Pointer array to original SST distribution data.

    General Notes:
      Combined distributions can be used with the following routines in the same
      way as output from thm_part_dist_array:

                thm_part_products
                thm_part_slice2d
                thm_part_conv_units (unit conversion)

                thm_part_moments (wrapper/deprecated)
                thm_part_getspec (wrapper/deprecated)

      Processing more than 1-2 hours of data (full) at once may cause older systems to
      run out of memory.  Typical run times 30-60+ sec.

      SST:  This routine automatically uses the /sst_cal option when loading sst full
            or burst data and sets default contamination removal options.  No calibrations or contamination
            removal are applied for reduced data.  Other contamination
            options may be passed through to override the defaults, see SST contamination
            removal crib for options.

     Note that the GET_ERROR keyword must be set if the user wants to
     propagate errors through to the thm_part_moments routine. This is
     not done automatically, because it doubles the interpolation time

    Developer Notes:
      In general this code makes the following assumptions about the particle data:

        -(ESA & SST) The dimensions of all fields will remain constant within a mode.
        -(ESA & SST) A single distribution's energy bins are constant across all look angles.
        -(ESA & SST) Energy bins may change within a mode (they probably never will but
                     this is assumed for safety).
        -(ESA & SST) Look directions, while general constant within a mode, may change at
                     any point due to eclipse corrections to phi values.

      All E/phi/theta items above are assumed for the bin widths as well.  Greater
      uniformity is assumed as the data is replaced with interpolated versions.

    $LastChangedBy: jimmpc1 $
    $LastChangedDate: 2017-10-05 10:26:24 -0700 (Thu, 05 Oct 2017) $
    $LastChangedRevision: 24117 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_part_combine.pro $

(See projects/themis/spacecraft/particles/combined/thm_part_combine.pro)

## THM_PART_ENERGY_INTERP

[Previous Routine] [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
      get_error:  if set, interpolates scaling factor needed for error propagation

    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_interp.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_interp.pro

      $LastChangedBy: pcruce $
      $LastChangedDate: 2013-09-26 16:32:05 -0700 (Thu, 26 Sep 2013) $
      $LastChangedRevision: 13156 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_energy_interpolate.pro $

(See projects/themis/spacecraft/particles/combined/thm_part_energy_interp.pro)

## THM_PART_MERGE_DISTS

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

    Procedure:
      thm_part_merge_dists.pro

    Purpose:
      Merge ESA/SST particle distributions once they have been
      altered to match in time, energy, angle, and mode transition.

    Inputs:
      esa_dist:  esa distribution array
      sst_dist:  sst distribution array
      sst_only:  flag to only return SST + new energies
      probe:  probe designation
      esa_datatype:  esa data type, e.g. 'peif'
      sst_datatype:  sst data type, e.g. 'psif'

    Outputs:
      out_dist:  combined distributions, fresh and ready for unit conversion

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2013-09-26 18:59:57 -0700 (Thu, 26 Sep 2013) $
    $LastChangedRevision: 13157 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_combine.pro $

(See projects/themis/spacecraft/particles/combined/thm_part_merge_dists.pro)

## THM_PART_SPHERE_INTERP

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

    PROCEDURE: thm_part_sphere_interp

    PURPOSE: Temporary generalized copy of thm_part_sphere_interpolate
      (Interpolate particle data to match the look direcitons of another distribution)

    INPUTS:
      source: The particle distribution to be modified by spherical interpolation.
      target: The particle distribution to which the sources times have been matched.
              This distribution will only be used to merge times between modes.

    OUTPUTS:
       Replaces source with a spherically interpolated version

    KEYWORDS:
      error: Set to 1 on error, zero otherwise
      get_error: if set, interpolates scaling factor needed for error propagation

     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: aaflores $
      $LastChangedDate: 2013-10-02 10:31:06 -0700 (Wed, 02 Oct 2013) $
      $LastChangedRevision: 13173 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_sphere_interpolate.pro $

(See projects/themis/spacecraft/particles/combined/thm_part_sphere_interp.pro)

## THM_PART_TIME_INTERPOLATE

[Previous Routine] [List of Routines]

    PROCEDURE: thm_part_time_interpolate
    PURPOSE:  Interpolate particle data to match the time grid of another distribution, or to an arbitary time grid

    INPUTS:
      source: A particle dist_data structure to be modified by interpolation to match target
      target: A particle dist_data structure whose times will be matched, or an array of target times for interpolatuion.

    OUTPUTS:
       Replaces source with a time interpolated dist_data structure

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

     NOTES:
       Any target times that occur between modes will contain samples filled with NANs.  Effective interpolation is very very tricky between modes.(Read: It will probably never happen)
       Accepts any keywords normally accepted by IDL interpol

       This has a done of TBDs, we need to come back and fix them when time is available.
     SEE ALSO:
       thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert

      $LastChangedBy: jimmpc1 $
      $LastChangedDate: 2017-10-23 14:17:30 -0700 (Mon, 23 Oct 2017) $
      $LastChangedRevision: 24204 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/combined/thm_part_time_interpolate.pro $

(See projects/themis/spacecraft/particles/combined/thm_part_time_interpolate.pro)