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

Last modified: Sat Jul 26 18:17:38 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles

- DATA_CACHE
- THM_CAL_MOM
- THM_LOAD_ESA
- THM_PART_ADDSUN
- THM_PART_APPLY_ECLIPSE
  Apply eclipse corrections (when present) to 3D data structures.
- THM_PART_CHECK_TRANGE
  This routine checks the time ranges of the current ESA and SST
- THM_PART_CHECKBINS
- THM_PART_CONV_UNITS
- THM_PART_COPY
- THM_PART_DIST
  wrapper function around the different routines called 'get_p???'
- THM_PART_DIST_ARRAY
- THM_PART_GET_CONFIG.PRO
  Returns structure containing particle distribution
- THM_PART_GETANBINS
  Create 3 arrays used by THM_PART_MOMENTS2 to turn on/off energy/angle bins
- THM_PART_GETMODECHANGE[1]
- THM_PART_GETMODECHANGE[2]
- THM_PART_GETMODECHANGE[2]
- THM_PART_GETMODECHANGE[3]
- THM_PART_GETSPEC
  Generate spectra from particle data
- THM_PART_OMNI_CONVERT
- THM_PART_PROCESS
- THM_PART_REMOVE.PRO
  Remove bins that fall below a specified # of counts from any 3D particle data structure.
- THM_PART_SET_COUNTS
- THM_PART_SMOOTH
- THM_PART_SUBTRACT
- THM_PART_TIME_ITERATOR
- THM_PART_TRANGE

# Routine Descriptions

## DATA_CACHE

[Next Routine] [List of Routines]

      This is an experimental routine.  It will most likely disappear.
      Davin Larson

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

## THM_CAL_MOM

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

    Deprecated, 8-feb-2010,jmm

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

## THM_LOAD_ESA

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

    Procedure: THM_LOAD_ESA

    Purpose:  Loads THEMIS ESA 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 'mom', 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
      level = the level of the data, the default is 'l2', or level-2
              data. A string (e.g., 'l2') or an integer can be used. 'all'
              can be passed in also, to get all levels.
      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 varible 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:
       thg_load_esa,/get_suppport_data,probe=['a', 'b']
    Notes:
     Written by Davin Larson, Dec 2006
     Updated to use thm_load_xxx by KRB, 2007-2-5
     Fixed bug in valid_names block, removed references to sst in coments
     jmm, 21-feb-2007
     Fixed bugs, added ylim, zlim calls for spec data, as in thm_load_sst
     Handles new version of Level2 data files, jmm, 12-oct-2007
     adds units and coordinates to all new variables, jmm, 24-feb-2008
     $LastChangedBy: kenb-mac $
     $LastChangedDate: 2007-02-08 09:48:04 -0800 (Thu, 08 Feb 2007) $
     $LastChangedRevision: 328 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_load_esa.pro $

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

## THM_PART_ADDSUN

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

    Procedure:
      thm_part_addsun

    Purpose:
      Populate sun direction vector field in 3D particle structures.
      This is meant as a modular solution to the need to add this
      vector in multiple places/conditions.

    Input:
      ds:  pointer array to particle structures
      probe:  scalar probe designation
      trange:  two element time range

    Output:
      none

    Notes:
      The SUN_VECTOR field must already be present in the target structures!

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 17:47:13 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20329 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_addsun.pro $

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

## THM_PART_APPLY_ECLIPSE

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

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

    ARGUMENTS:
      data: Valid 3D data structure

    KEYWORDS:
      eclipse: Flag used by this routine to determine when an ecplise
               starts or ends (assists output messages). Will be set
               to 1 at the start of an eclipse and 0 at the end.

    NOTES:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2013-09-10 12:11:07 -0700 (Tue, 10 Sep 2013) $
    $LastChangedRevision: 13011 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_apply_eclipse.pro $

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

## THM_PART_CHECKBINS

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

    Procedure:
      thm_part_checkbins

    Purpose:
      Checks if two particle distribution structures have identical
      energy, phi, theta, and mass values.

    Input:
      dist1: 3D particle data structure
      dist2: 3D particle data structure

    Output:
      return value: (bool) 1 if all fields match, 0 otherwise

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2014-11-07 18:26:20 -0800 (Fri, 07 Nov 2014) $
    $LastChangedRevision: 16155 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_checkbins.pro $

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

## THM_PART_CHECK_TRANGE

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

    NAME:
      thm_part_check_trange

    PURPOSE:
      This routine checks the time ranges of the current ESA and SST
      data stored in the common blocks to determine if it covers a
      particular time range.

    CALLING SEQUENCE:
      bool = thm_part_check_trange(probe, datatype, trange [,sst_cal=sst_cal] [,fail=fail])

    KEYWORDS:
      probe: String or string array specifying the probe
      datatype: String or string array specifying the type of
            particle data requested (e.g. 'peif', 'pseb')
      trange: Two element array specifying the numeric time range
      sst_cal: Flag to check data from new SST calibrations
      fail: Set to named variable to pass out error messages (string)

    OUTPUT:
      1 if current data covers what is requested, 0 otherwise

    NOTES:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-04-05 14:14:33 -0700 (Tue, 05 Apr 2016) $
    $LastChangedRevision: 20726 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_check_trange.pro $

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

## THM_PART_CONV_UNITS

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

    Procedure: thm_part_conv_units

    Purpose: Takes the distribution data structure from a call to thm_part_dist_array and calibrates it.
    Uses the ssl_general routine conv_units to perform the operation.  At this time, the operation is not
    vectorized.

    Inputs:
      dist_data: An array of pointers to arrays of structures.  One pointer for each mode in the time series, structure for each sample within the mode array.
         Note: this routine modifes the contents of dist_data in place.(ie mutates dist_data) It has no return value.

    Keywords:
      units: String specifying units requested for the output data.  If unspecified, units will be "eflux".
        If data is already in requested units, identify transform applied.
        Possible selections(not case sensitive): COUNTS,RATE,EFLUX,FLUX,DF
      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).

       error: Used to report presence of an error to calling routine.
          error==0 means no error
          error!=0 means error

       remove_negative_values: If set set negative values for the data
                               tag of the input structures to zero

    Notes:

      This routine is part of an ongoing process to sanitize, modularize, and simplify the THEMIS particle routines.

    See also: thm_part_dist_array.pro,thm_crib_part_extrapolate.pro

     $LastChangedBy: jimm $
     $LastChangedDate: 2017-10-02 11:24:39 -0700 (Mon, 02 Oct 2017) $
     $LastChangedRevision: 24079 $
     $URL $

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

## THM_PART_COPY

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

    Procedure: thm_part_copy

    Purpose: Performs deep copy on particle data that is returned by thm_part_dist_array

    Arguments:  Old: A particle data structure to be copied
                New: A variable name to which the particle data should be copied

    Keywords: error=error:  Set to named variable. Returns 0 if no error, nonzero otherwise.

    Usage: thm_part_copy,old,new

    History:  2016-02-09 - Moved to spd_part_copy, kept as wrapper

      $LastChangedBy: aaflores $
      $LastChangedDate: 2016-02-09 16:31:11 -0800 (Tue, 09 Feb 2016) $
      $LastChangedRevision: 19920 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_copy.pro $

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

## THM_PART_DIST

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

    NAME:
     thm_part_dist
    PURPOSE:
     wrapper function around the different routines called 'get_p???'
     used for ESA particle data and 'thm_sst_p???' routines that extract
     SST data.
    INPUT:
     format = a string denoting the data that is desired: options are:
              'tha_peif': Full Esa mode data, ions, probe A
              'tha_peef': Full Esa mode data, electrons, probe A
              'tha_peir': Reduced Esa mode data, ions, probe A
              'tha_peer': Reduced Esa mode data, electrons, probe A
              'tha_peir': Burst Esa mode data, ions, probe A
              'tha_peer': Reduced Esa mode data, electrons, probe A
              'tha_psif': Full Sst mode data, ions, probe A
              'tha_psef': Full Sst mode data, electrons, probe A
              'tha_psir': Reduced Sst mode data, ions, probe A
              'tha_pser': Reduced Sst mode data, electrons, probe A
             For other probes, just replace 'tha' with the appropriate
             string, 'thb', 'thc', 'thd', 'the'
              If this is not set, then the string is constructed from the
              type and probe keywords
     time = an input time, if not passed in, then this routine will
            attempt to get the time from plotted data, via ctime, unless
            the index keyword is passed in (for SST) or
            when start, en, advance, retreat, or index are passed in.
    KEYWORDS:
     type = 4 character string denoting the type of data that you need,
            e.g., 'peif' for full mode esa data
     probe = the THEMIS probe, 'a','b','c','d','e'
     cursor = if set, then choose a time from the plot, using
              ctime.pro. This overrides any input -- that is, the
              variable that was used becomes the input variable and the
              time obtained becomes the time of the data.
     index = an index for the data point that is to be returned
     start (ESA only) = if set, then get the first saved data point
     en (ESA only) = if set, get the last saved data point
     advance (ESA only) = if set, get the data point after the one that
                          was gotten last
     retreat (ESA only) = if set, get the data point before the one that
                          was gotten last
     times = if set, returns the time array for all the saved data points
    OUTPUT:
     dat = the '3d data structure' for the given data type: In general
           this will be different for different data types, but there are
           elements that are common to all, Here is a sample for tha_psif
           data:
       PROJECT_NAME    STRING    'THEMIS'
       DATA_NAME       STRING    'SST Ion Full distribution'
       UNITS_NAME      STRING    'Counts'
       UNITS_PROCEDURE STRING    'thm_sst_convert_units'
       TPLOTNAME       STRING    ''
       TIME            DOUBLE       1.1837675e+09
       END_TIME        DOUBLE       1.1837676e+09
       TRANGE          DOUBLE    Array[2] ;;not always present
       INDEX           LONG                 4
       NBINS           LONG                64
       NENERGY         LONG                16
       MAGF            FLOAT     Array[3]
       SC_POT          FLOAT           0.00000
       MASS            FLOAT         0.0104390
       CHARGE          FLOAT           0.00000
       VALID           INT              1
       MODE            INT              0
       CNFG            INT            577
       NSPINS          INT             64
       DATA            FLOAT     Array[16, 64]
       ENERGY          FLOAT     Array[16, 64]
       THETA           FLOAT     Array[16, 64]
       PHI             FLOAT     Array[16, 64]
       DENERGY         FLOAT     Array[16, 64]
       DTHETA          FLOAT     Array[16, 64]
       DPHI            FLOAT     Array[16, 64]
       BINS            INT       Array[16, 64]
       GF              FLOAT     Array[16, 64]
       INTEG_T         FLOAT     Array[16, 64]
       DEADTIME        FLOAT     Array[16, 64]
       GEOM_FACTOR     FLOAT          0.100000
       ATTEN           INT             10

     NOTE: 1.  that the .time tag refers to the interval start time. The
     .trange tag gives the time range, and is not always present.
           2.  For documentation on sun contamination correction keywords that
           may be passed in through the _extra keyword please see:
           thm_remove_sunpulse.pro or thm_crib_sst_contamination.pro

    HISTORY:
      2016-08-23  background removal moved to thm_pgs_clean_esa

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-09-26 10:16:49 -0700 (Mon, 26 Sep 2016) $
    $LastChangedRevision: 21940 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_dist.pro $

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

## THM_PART_DIST_ARRAY

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

    Procedure:
      thm_part_dist_array

    Purpose:
      Returns an array of pointers to ESA or SST particle distributions.(One pointer for new mode in the time series)  This routine
      is a wrapper for thm_part_dist, which returns single distributions.

    Required Keywords:
     PROBE: The THEMIS probe, 'a','b','c','d','e'.
     DATATYPE: Four character string denoting the type of data that you need.
              ESA Ions (full/reduced/burst)
                'peif' - Full mode
                'peir' - Reduced mode
                'peib' - Burst mode
              ESA Electrons
                'peef' - Full
                'peer' - Reduced
                'peeb' - Burst
              SST Ions
                'psif' - Full
                'psir' - Reduced
              SST Electrons
                'psef' - Full
                'pser' - Reduced
                'pseb' - Burst
     TRANGE: Time range of interest (2 element array, string or numerical).
             *This keyword may be ommitted if 'timespan is set. If neither
              TRANGE nor 'timespan' is set the user will be prompted.

    Optional Keywords:
     MAG_DATA: Tplot variable containing magnetic field data. The data will be
               interpolated to the cadence of the requested particle distribution
               and added to the returned structures under the tag 'MAGF'.
     VEL_DATA: Tplot variable containing velocity data. The data will be
               interpolated to the cadence of the requested particle distribution
               and added to the returned structures under the tag 'VELOCITY'.
               If not set V_3D_NEW.PRO will be used instead.
     GET_SUN_DIRECTION: Adds sun direction vector to the returned structures
               under the tag 'SUN_VECTOR'
     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). This will only be used by this
                        code when calculating the bulk velocity with V_3D_NEW.PRO

    ESA Keywords:
      BGND_REMOVE: Flag to turn on ESA background removal.
      BGND_TYPE: String naming removal type, e.g. 'angle','omni', or 'anode'.
      BGND_NPOINTS: Number of lowest values points to average over when determining background.
      BGND_SCALE: Scaling factor that the background will be multiplied by before it is subtracted.

    SST Keywords:
      SST_CAL: Flag to use newest SST calibrations

    Examples:
      dist_array = thm_part_dist_array(probe='b',datatype='pseb', $
                     trange='2008-2-26/04:'+['50:00','55:00'])

      timespan, '2008-2-26/04:50:00', 5, /min
      dist_array = thm_part_dist_array(probe='b',datatype='psif', $
                                       vel_data='tplot_vel', $
                                       mag_data='tplot_mag')

    See Also: thm_crib_part_product, thm_part_products
              thm_crib_part_slice2d, thm_part_slice2d
              thm_crib_esa_bgnd_remove, thm_esa_bgnd_remove,

    Created by Bryan Kerr
    Modified by A. Flores

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-10-05 08:57:54 -0700 (Thu, 05 Oct 2017) $
     $LastChangedRevision: 24116 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_dist_array.pro $

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

## THM_PART_GETANBINS

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

    PROCEDURE: thm_part_getanbins
    PURPOSE:
       Create 3 arrays used by THM_PART_MOMENTS2 to turn on/off energy/angle bins

    	Generates a [number of energy channels]x[number of angle bins] array
           (en_an_bins), an array [number of angle bins]x1 array (an_bins), and an
           array [number of energy channels]x1 array (en_bins) of 1's and 0's used
           by THM_PART_MOMENTS2 to turn on/off energy and angle bins based on the
           theta/phi/pitch angles, energy ranges, and data types requested by the
           user in THM_PART_GETSPEC. THM_PART_MOMENTS2 will also call this function
           if there's a mode change since modes have different angle maps.
           NOTE: pitch angles not yet implemented

    KEYWORDS:
      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. [270, 450]) to specify the 'daylight'
              hemisphere in DSL coordinates. Default is all (e.g. [0, 360]).
      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]).
      pitch = NOT IMPLEMENTED YET Angle range of interest (2 element array) in degrees relative to
              the magnetic field. Default is all (e.g. [0, 180]).
      erange= Energy range (in eV) of interest (2 element array). Default is all.
      data_type = The type of data to be loaded. Energy/angle bins are now derived
                  from dat structure in THM_PART_MOMENTS2.

    SEE ALSO:
    	THM_PART_MOMENTS2, THM_PART_GETSPEC, THM_CRIB_PART_GETSPEC

    CREATED BY:	Bryan Kerr
    HISTORY:
     v0.1	11/21/07: Initial release.
     v0.2	11/28/07: Added ability to handle eESA and *SST data types.
     v0.3  12/04/07: Improved ability to better handle phi input from
                     THM_PART_GETSPEC.
     v0.4  12/13/07: Added check and warning if no energy bins fall within ERANGE.
     v0.6  01/09/08: Added reduced mode (peir) capability.
     v0.6.01 01/09/08: Corrected peir phi bin map
     v0.6.3 01/15/08: All reduced modes implemented. Generalized to arbitrary angle
                      maps and energy ranges.
     v0.7  01/31/08: Added en_bins reference
     v0.8.12 02/26/08: Fixed bug that fails to properly handle cases when no phi
                       bins occur within PHI range.
     v1.0 05/09/08: Ready for Release v4.0.

    VERSION: 1.0
      $LastChangedBy: aaflores $
      $LastChangedDate: 2012-02-13 09:59:58 -0800 (Mon, 13 Feb 2012) $
      $LastChangedRevision: 9719 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_getanbins.pro $

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

## THM_PART_GETMODECHANGE[1]

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

    Purpose: Helper function to access ESA common blocks and
             return array of indices for mode changes.

    Notes:
      When editing this code:
       -make sure calls to scope_varfetch do not copy
        unnecessary data (see IDL documentation)

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

## THM_PART_GETMODECHANGE[2]

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

    Purpose: Helper function to access SST common block and
             return array of indices for mode changes.

    Notes:
      When editing this code:
       -make sure calls to scope_varfetch do not copy
        unnecessary data (see IDL documentation)
       -make sure not to free pointers copied from the
        common block

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

## THM_PART_GETMODECHANGE[2]

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

    Purpose: Helper function to access raw SST data stored in tplot
             variables and return array of indices for mode changes.
             Data loaded with thm_load_sst2 (/sst_cal keyword on higher
             level routines) is stored in tplot vars instead of the
             original common block.

    Notes:

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

## THM_PART_GETMODECHANGE[3]

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

     Purpose:
       Access particle data common blocks to determine
     where mode changes occure and how many samples are
     in each configuration.

     Input:
       probe: String specifying the spacecraft (e.g. 'a','b',...)
       datatype: String specifying the type of data (e.g. 'peif')
       tindex: Array of indices specifying which samples are
               within the time range.

     Output:
       returned value: Array of indices correspinding to the first
                       distribution for each new configuration.
                    n: The total number of samples for each
                       configuration.

     Usage:
       indices = thm_part_dist_array_getmodechange(probe='a', datatype='psif', $
                                              tindex=time_index_array, n=n)

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

## THM_PART_GETSPEC

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

    PROCEDURE: thm_part_getspec
    PURPOSE:
      Generate spectra from particle data
      Provides different angular view and angle restriction options in spacecraft and fac coords

    Inputs:
     Argument descriptions inline below.

    Outputs:
     Argument descriptions inline below

    Keywords:
     Argument description inline below

    Notes:
     Old version in particles/deprecated

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-03-15 13:39:33 -0700 (Wed, 15 Mar 2017) $
    $LastChangedRevision: 22971 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_getspec.pro $

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

## THM_PART_GET_CONFIG.PRO

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

    NAME:
      thm_part_get_config.pro

    PURPOSE:
      Returns structure containing particle distribution
      attributes based on APID and config word.

    INPUT:
      APID: Numerical APID (e.g. '045A'xu)
      config_word: Two-byte config word
                   Can be passed in as:
                     -single element variable (e.g. '1234'xu)
                     -two element array (e.g. ['12'xu,'34'xu])
                     -two separate arguments (e.g. '12'xu, '34'xu)
      config_word2: (optional) see above

    EXAMPLES
      struct = thm_part_get_config( '454'xu, '0101'xu)
      struct = thm_part_get_config( '454'xu, ['01'xu,01'xu])
      struct = thm_part_get_config( '454'xu, '01'xu, '01'xu)

    OUTPUT:
      Returns anonymous structure containing distribution attributes:
        {  apid:            APID from input
           config_word:     Config word from input

           is_esa:          Flag denoting esa data
           is_sst:          Flag denoting sst data

           valid:           Flag for valid data (1b=valid)

           nspins:          Number of spins per distribution
           angle_bins:      Number of angle bins
           energy_bins:     Number of energy bins

           sweep_mode:      Integer denoting ESA sweep mode index (thm_read_esa_sweep_*)
           angle_mode:      Integer denoting ESA angle mode index (thm_read_esa_angle_*)
           esa_solar_wind:  Solar wind flag for ESA
         }

    NOTES:
      2016-08 - This routine is not currently used but could be useful.

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

## THM_PART_OMNI_CONVERT

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

    PROCEDURE: thm_part_omni_convert
    PURPOSE:  Converts a particle distribution to omni directional by summing over angle.

    INPUTS:
      dist_data:
       A single particle distribution structure, or a particle distribution array from thm_part_dist_array
    OUTPUTS:
       Replaces dat with an omni summed particle distribution structure, or a particle distribution array from thm_part_dist_array

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

     NOTES:

      $LastChangedBy: pcruce $
      $LastChangedDate: 2013-02-20 15:26:03 -0800 (Wed, 20 Feb 2013) $
      $LastChangedRevision: 11594 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_omni_convert.pro $

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

## THM_PART_PROCESS

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

    Procedure:
      thm_part_process

    Purpose:
      Apply standard processing to particle distribution array
      and pass out the processed copy.  This routine will apply
      eclipse corrections, perform a unit conversion, and
      call the standard processing routines.

    Calling Sequence:
      thm_part_process, in, out [,trange=trange] [,units=units] [,sst_sun_bins=sst_sun_bins]

    Input:
      in:  Pointer array from thm_part_dist_array
      trange:  Two element time range, only overlapping data will be returned
      units:  String specifying new units
      _extra: Passed to sanitization routines

    Output:
      out:  Pointer array to processed copy of the data

    Notes:

    $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_process.pro $

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

## THM_PART_REMOVE.PRO

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

    NAME:
      thm_part_remove.pro

    PURPOSE:
      Remove bins that fall below a specified # of counts from any 3D particle data structure.

    CALLING SEQUENCE:
      thm_part_remove, dist, threshold=threshold, [/zero], [/remove]

    INPUT ARGUMENTS:
      dist:  Particle distribution(s).
             Can be single or array of structure(s) or pointer(s) to structure(s).
      threshold:  The value below wich data points will be removed or zeroed.
                  Must be in the same units as the input data.

    KEYWORDS:
      zero:  (default) Data below the threshold will be set to zero.
      remove:  Data below the threshold will be removed.  Specifically,
               the data will be set to NaN and the bin flag set to off.

    NOTES:

    $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_remove.pro $

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

## THM_PART_SET_COUNTS

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

    Procedure:
      thm_part_set_counts

    Purpose:
      Perform the somewhat common task of setting all data
      in the distribution to a particular number of counts.

    Calling Sequence:
      thm_part_set_counts, dist_array, counts [,set_units]

    Input:
      dist_array:  pointer array containing particle data (see thm_part_dist_array)
      counts:  number of counts to set the distribution to
      set_units:  flag to set the units_name field to 'counts'

    Example:
      ;set all data in the distribution to 1 count
      thm_part_set_counts, dist_array, 1.

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-24 11:08:03 -0700 (Thu, 24 Mar 2016) $
    $LastChangedRevision: 20582 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_set_counts.pro $

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

## THM_PART_SMOOTH

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

    Procedure: thm_part_smooth

    Purpose:
      This routine applies time-smoothing to particle data using a convolution method.  Default is boxcar,
        but other kernels may be supplied by the user.

    Inputs:
      dist_data:
         The data to be smoothed.  Data should have been loaded using thm_part_dist_array.pro.  This data will be modified
         during the operation of this routine.

    Keywords:
      width=width The width of a boxcar smooth.  (Default=3,just creates a boxcar kernel.)
      kernel=kernel  A 1-d array containing a kernel to be applied by CONVOL across time.  If you don't want to shift the levels of the data,
             total(kernel) should equal 1.0d.  If kernel= is set, width= is ignored.
      scale_factor=scale_factor  A scale_factor to be applied to the convol.  (See convol documentation for details)
      trange=trange: Specify a time based subset of the data for the smoothing to be applied to.  Allows different smoothing parameters to be applied at
        different times by calling this routine multiple times.
      _extra=ex:  You can provide any of the normal convol keywords when using this routine(e.g. /edge_wrap, /edge_truncate,invalid=i,missing=i,/nan,etc...)
      error=error:  After completion, will be set 1 if error occured, zero otherwise

    Notes:
      #1. The CONVOL routine is applied separately to each mode.  This is because the cadence and shape of the dist array will change across mode boundaries.
        Be aware that this can cause strange artifacts at mode boundaries in smoothed particle data.
      #2. See the CONVOL documentation in the IDL help for more info on how the smoothing is performed.

    Examples:
      ;5-point boxcar smooth
      thm_part_smooth,dist_data,width=5,/edge_truncate,/nan
      ;21-point boxcar smooth
      thm_part_smooth,dist_data,kernel=(dblarr(21)+1)/21d,/edge_wrap
      ;Manually normalized gaussian smooth
      x= dindgen(101)/10.-5.
      nonnorm_kernel=deriv(gaussint(x))
      thm_part_smooth,dist_data,kernel=nonnorm_kernel/total(nonnorm_kernel)

      ;automatically normalized gaussian smooth
      x= dindgen(101)/10.-5.
      thm_part_smooth,dist_data,kernel=deriv(gaussint(x)),/normalize

    See also: thm_part_dist_array.pro,thm_crib_part_extrapolate.pro,CONVOL(in IDL help)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2012-09-21 16:55:28 -0700 (Fri, 21 Sep 2012) $
     $LastChangedRevision: 10943 $
     $URL $

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

## THM_PART_SUBTRACT

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

    PROCEDURE: thm_part_subtract
    PURPOSE:  Subtracts from a particle distribution down to a minimum.
    (If units are in counts, you can use this to do 1 or N count subtraction)

    INPUTS:
      dist_data:
       A particle distribution array from thm_part_dist_array
    OUTPUTS:
       Replaces dat with a data structure with the requested counts subtract

    Keywords:
      error: Set to 1 on error, zero otherwise
      subtract_value: The amount to subtract(default: 1)
      minimum_value: The minimum after subtraction.(default 5e-3) Prevents asymptotes in moment calculations, negative values

    Example:
     dist_data = thm_part_dist_array(probe='a',type='peif',trange=['2012-02-08/09','2012-02-08/12']) ;load data(loaded in counts, by default)
     thm_part_subtract,dist_data ;subtract one count level
     thm_part_moments,inst='peif',probe='a',dist_array=dist_data ;calculate moments

     NOTES:
       Works with thm_part_dist_array.pro, see crib thm_crib_sst_extrapolation.pro, thm_crib_esa_extrapolation.pro for examples on new particle processing routines

      $LastChangedBy: pcruce $
      $LastChangedDate: 2013-01-18 08:57:01 -0800 (Fri, 18 Jan 2013) $
      $LastChangedRevision: 11462 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_subtract.pro $

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

## THM_PART_TIME_ITERATOR

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

    PROCEDURE: thm_part_time_iterator
    PURPOSE:  An accessor method to make it easier to iterate
      particle distributions that are regularly gridded in time
      but not in mode.(e.g. after thm_part_time_interpolate has been used to match time grids)

    INPUTS:
     dist_array: The array of particle distribution mode pointers to be interated

    OUTPUTS:
      dist_struct(optional): an individiual distribution structure being returned

    KEYWORDS:
     nelements=nelements:  Query the total number of elements and return
     index=index:  The index for the distribution that should be returned(default=0)
     set=set: If this keyword is set, then dist_struct will be stored at index instead of returned from index

     SEE ALSO:
      thm_part_time_interpolate, thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert

     EXAMPLE:

     thm_part_time_iterator,dist_psif,nelements=n
     for i = 0,n-1 do begin
       thm_part_time_iterator,dist_psif,s,index=i
       s.data*=2
       thm_part_time_iterator,dist_psif,s,index=i,/set
     endfor

     TODO:
       This is routine is primarily for simplifying user interaction with particle distribution structures,
         but I think it could be used to simplify/clarify other routines in the SEE ALSO section.

      $LastChangedBy: pcruce $
      $LastChangedDate: 2015-03-11 13:34:12 -0700 (Wed, 11 Mar 2015) $
      $LastChangedRevision: 17117 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_time_iterator.pro $

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

## THM_PART_TRANGE

[Previous Routine] [List of Routines]

    Procedure:
      thm_part_trange

    Purpose:
      Store/retrive the last requested time range for a particle data type.
      This routine should only be called internally by the particle load routines.

    Calling Sequence:
      thm_part_set_trange, probe, datatype, trange [,sst_cal=sst_cal]

    Input:
      probe: (string) scalar containing probe designation
      datatype: (string) scalar containing particle data type
      set: (double) two element array specifying a time range
      sst_cal: (bool/int) flag to use time range for data loaded with thm_load_sst2

    Output:
      get: (double) two element array containing the last loaded time range
           for the specified data, [0,0] if no data has been loaded

    See Also:
      thm_part_check_trange
      thm_load_esa_pkt
      thm_load_sst
      thm_load_sst2

    Notes:
      Get operation performed before set.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2014-10-13 10:38:28 -0700 (Mon, 13 Oct 2014) $
    $LastChangedRevision: 15979 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/thm_part_trange.pro $

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