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/SST/SST_cal_workdir

- THM_LOAD_SST2
- THM_PART_DIST2
  wrapper function around the different routines called 'get_p???'
- THM_SANITIZE_L2_SST
- THM_SST_ADD_SPINDATA2
- THM_SST_ATT_CORRECT
  tests for attenuator transition, calculates background level and
- THM_SST_BUILD_CAL_FILES
- THM_SST_CALIB_PARAMS2
  This populates the correct fields of the dist struct so that data can be correctly calibrated.
- THM_SST_CALIBRATION_TESTS
- THM_SST_CONVERT_UNITS2
- THM_SST_CROSS_CONTAMINATION_REMOVE,DATA_A,DATA_B
- THM_SST_DIST3D_16X64[2]
  This routine returns the appropriate distribution representation struct for
- THM_SST_DIST3D_16X64[1]
  This routine defines the appropriate distribution representation struct for
- THM_SST_DIST3D_DEF
  This routine returns the appropriate distribution representation struct for
- THM_SST_ENERGY_CAL2
  This routine performs bin energy boundary calibrations. Transforming DAP values into eV
- THM_SST_READ_CALIBRATION_PARAMS
  This routine reads calibration parameters from a file.

# Routine Descriptions

## THM_LOAD_SST2

[Next Routine] [List of Routines]

    Procedure: thm_load_sst2

    Purpose:  Loads THEMIS SST data

    WARNING: This routine is under development as part of the SST calibration process. Use at your own risk!

    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 'sst', 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 '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.
      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
    Example:
       thg_load_sst,/get_suppport_data,probe=['a', 'b']

    Notes:

      Many of the standard keywords only work with L2 data.

      When L1 data is loaded it is merged into a data structures stored
      in tplot variables named: th?_ps??_data.

      These structures have the form:
       X               DOUBLE    Array[27797]
       Y               INT       Array[27797]
       MDISTDAT        STRUCT    -> <Anonymous> Array[1]

       X is the time array for the data
       Y is the index to the distribution type that is valid at each time.
       D.Y will index MDISTDAT.DISTPTRS, although not all distptrs are guaranteed to be valid.(ie Not all distributions will be used in a given data set)

      This modification replaces use of data_cache and common blocks for passing sst data between routines.

    Major Revisions:
     Written by Davin Larson, Dec 2006
     Updated to use thm_load_xxx by KRB, 2007-2-5
     Update removed to not use thm_load_xxx by DEL
     Updated to use new code from Davin by pcruce Jun 2010

     $LastChangedBy: jimm $
     $LastChangedDate: 2021-04-19 11:52:51 -0700 (Mon, 19 Apr 2021) $
     $LastChangedRevision: 29890 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_load_sst2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_load_sst2.pro)

## THM_PART_DIST2

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

    NAME:
     thm_part_dist2
    PURPOSE:
     wrapper function around the different routines called 'get_p???'
     used for ESA particle data and 'thm_sst_p???' routines that extract
     SST data.

     This is a working version for development of SST calibrations.
    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
     skip_sst_att_correct = if set skip correction for effective
                            attenuation, which is done by default if the
                            variables 'th?_ps?f_ratio_var' exist for the
                            given probe and species.
    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
       ;Following fields added for ESA compatibility purposes
       DEAD            FLOAT          0.0
       ;Following fields added for calibration purposes, values are read from a file
       EFF             FLOAT     Array[16, 64] ;Detector Efficiency only 16x4 unique values
       ENERGY_SCALE    FLOAT     Array[16, 64] ;Energy Scale Factors only 4 unique values
       ENERGY_OFFSET   FLOAT     Array[16, 64] ;Energy Offsets only 4 unique values
       GF              FLOAT     Array[16, 64] ;Gfactor corrections, only 4 unique values

       Note: True Geometric factor = GEOM_FACTOR*GF,  GF are corrections for aperture variations

     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

    $LastChangedBy: jimm $
    $LastChangedDate: 2021-06-21 11:42:40 -0700 (Mon, 21 Jun 2021) $
    $LastChangedRevision: 30074 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_part_dist2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_part_dist2.pro)

## THM_SANITIZE_L2_SST

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

    Procedure: thm_santize_l2_sst

    Purpose:
      Basic santization for L2 CDFs.
      Right now, only removes attenuator spikes
      Only tested for psif/psef.  Not sure how it would work on other data

    Arguments:
      probe: the probe ('a','b,', etc...)
      datatype: the sst data type( e.g. psif etc..)
      tvarnames: the tvarnames to be sanitized
      suffix=suffix:Set to add a suffix for comparison testing

     $LastChangedBy: jimm $
     $LastChangedDate: 2021-06-21 13:40:03 -0700 (Mon, 21 Jun 2021) $
     $LastChangedRevision: 30075 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sanitize_l2_sst.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sanitize_l2_sst.pro)

## THM_SST_ADD_SPINDATA2

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

    Procedure: THM_SST_ADD_SPINDATA2.PRO

    Purpose: Add appropriate spin model data to L1 SST data
             loaded via thm_load_sst2.pro.

    Arguments:
        dts: Structure from thm_load_sst2.pro (thm_load_sst2_cdfivars)
            containing pointers to time varying quatities for a single
            data type.

    Keywords:
        use_eclipse_corrections:  Flag to specify which spin model will be used:
          0 - No corrections (default)
          1 - Use partial corrections
          2 - Use full eclipse corrections

    Notes:  To be called within thm_load_sst2.
            Assumes STATE data has already been loaded.

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_add_spindata2.pro)

## THM_SST_ATT_CORRECT

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

    NAME:
     thm_sst_att_correct
    PURPOSE:
     tests for attenuator transition, calculates background level and
     correction factor, and corrects the attenuation level in the saved
     data structures. Ideally the correction is interpolated between two
     attenuator transistions.
    CALLING SEQUENCE:
     thm_sst_att_correct, probe, date, dur = dur
    INPUT:
     probe = 'a', 'b', 'c', 'd', or 'e'
     date = start date
    KEYWORDS:
     dur = duration in days, note that some attenuator intervals are more
           than a day, if there is no attenuator transition during the
           date input, no correction will be calculated. If there is only
           one transition in the data, then the correction will not be
           interpolated over the full interval.
     auto_extend = If duration is 1 day, the auto_extend option will
                   extend the calculation to previous and later days if
                   the attenuators are in at the start and end of the
                   day. This will extend at least 7 days in either
                   direction.
    NOTES:
    Uses thm_part_dist2, and not thx_sst_psi?f
    HISTORY:
     2021-03-29, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2021-07-13 13:06:43 -0700 (Tue, 13 Jul 2021) $
     $LastChangedRevision: 30125 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_att_correct.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_att_correct.pro)

## THM_SST_BUILD_CAL_FILES

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

    NAME:
     thm_sst_build_cal_files
    PURPOSE:

      Automated routine to ease the creation of text-based cal-files

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-03-11 16:02:06 -0700 (Mon, 11 Mar 2013) $
    $LastChangedRevision: 11768 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_build_cal_files.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_build_cal_files.pro)

## THM_SST_CALIBRATION_TESTS

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

    NAME:
     thm_sst_calibration_tests
    PURPOSE:

      This routine is for testing new calibrations(will eventually be moved to QA directory)

    $LastChangedBy: pcruce $
    $LastChangedDate: 2011-10-10 13:06:53 -0700 (Mon, 10 Oct 2011) $
    $LastChangedRevision: 9100 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calibration_tests.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calibration_tests.pro)

## THM_SST_CALIB_PARAMS2

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

    NAME:
     thm_sst_calib_params2
    PURPOSE:
      This populates the correct fields of the dist struct so that data can be correctly calibrated.

    Inputs:
      dist: The dist struct that will have its fields populated
      param_structs: An array of parameter structs that contains the calibration parameters for each time

    Outputs:
      error: Set to 1 if error occurred and 0 otherwise.  If error occurs calling routine should halt.

    Keywords:
      no_energy_efficiency: Set to disable energy efficiency calibrations
      no_geom_efficiency: Set to disable the relative efficiencies of different anodes
      no_dead_layer_offsets: Set to disable dead layer energy offsets
    NOTES:
      #1 dist.time should be set by the time this is called
      #2 uses the calibration parameters for full distribution on all types.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-03-11 17:32:36 -0700 (Mon, 11 Mar 2013) $
    $LastChangedRevision: 11772 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calib_params2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calib_params2.pro)

## THM_SST_CONVERT_UNITS2

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

    NAME:
     thm_sst_convert_units2
    PURPOSE:

      This routine converts input data into the desired physical units
      It is used as a callback function by ssl_general routines like moments_3d/conv_units
      It will mutate the contents of the struct that is passed as an argument.

    Inputs:
      data: data struct that is being converted, this structure will have its data mutated
      units: string identifying the desired output units
      other_data: Proper calibration of the SST requires removal of ion & electron cross-contamination at high energies.  If this argument contains the associated struct from
      the opposite species, cross contamination will be removed.

    Outputs:
      scale: scale factor that was used to convert the data into the desired format, should have dimensions that match the data

    SEE ALSO:
      thm_sst_energy_cal2
      moments_3d
      conv_units
      thm_convert_esa_units

    NOTES:
      This code is based heavily on thm_convert_esa_units.  Looking there should be helpful in understanding this code.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-09-06 18:19:42 -0700 (Fri, 06 Sep 2013) $
    $LastChangedRevision: 12970 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_convert_units2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_convert_units2.pro)

## THM_SST_CROSS_CONTAMINATION_REMOVE,DATA_A,DATA_B

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

    NAME:
     thm_sst_cross_contamination_remove,data_a,data_b

    PURPOSE:

      At higher energies electrons will be present in SST ion data and ions will be present in SST electron data.
      This uses a matrix approach based on modeled channel efficiencies to remove cross contamination.

    SEE ALSO:
      thm_sst_energy_cal2
      moments_3d
      conv_units
      thm_sst_convert_units2

    NOTES:

      $LastChangedBy: aaflores $
      $LastChangedDate: 2012-01-10 10:57:33 -0800 (Tue, 10 Jan 2012) $
      $LastChangedRevision: 9527 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_cross_contamination_remove.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_cross_contamination_remove.pro)

## THM_SST_DIST3D_16X64[1]

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

    NAME:
     thm_sst_dist3d_16x64
    PURPOSE:
      This routine defines the appropriate distribution representation struct for
      16 Energy and 64 angle SST data.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-09-10 16:17:02 -0700 (Tue, 10 Sep 2013) $
    $LastChangedRevision: 13014 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2__define.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2__define.pro)

## THM_SST_DIST3D_16X64[2]

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

    NAME:
     thm_sst_dist3d_16x64
    PURPOSE:
      This routine returns the appropriate distribution representation struct for
      16 Energy and 64 angle SST data.(16 energy by 4 theta by 16 phi)
      Default and/or constant values will be populated.  At this point,
      the structure should be considered incomplete.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2012-11-01 16:46:42 -0700 (Thu, 01 Nov 2012) $
    $LastChangedRevision: 11152 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2.pro)

## THM_SST_DIST3D_DEF

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

    NAME:
     thm_sst_dist3d_def
    PURPOSE:
      This routine returns the appropriate distribution representation struct for
      a particular number of SST angles in the data type.
      Default and/or constant values will be populated.  At this point,
      the structure should be considered incomplete.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-02-05 14:02:49 -0800 (Fri, 05 Feb 2016) $
    $LastChangedRevision: 19904 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_def2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_def2.pro)

## THM_SST_ENERGY_CAL2

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

    NAME:
     thm_sst_energy_cal2
    PURPOSE:
      This routine performs bin energy boundary calibrations.  Transforming DAP values into eV
      The routine directly modifies the dat struct according to parameters stored in the struct
      But results can be returned for reference.

    Inputs:
      dat

    Outputs:
      energy:  The midpoint of each energy bin
      denergy: The width of each energy bin

    SEE ALSO:
      thm_sst_convert_units2

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-03-07 19:17:56 -0800 (Thu, 07 Mar 2013) $
    $LastChangedRevision: 11751 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_energy_cal2.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_energy_cal2.pro)

## THM_SST_READ_CALIBRATION_PARAMS

[Previous Routine] [List of Routines]

    NAME:
     thm_sst_read_calibration_params
    PURPOSE:
      This routine reads calibration parameters from a file.

    Inputs:
      thx:  probe identifier string (e.g. 'tha','thb'...)
      species: 'e' or 'i', to indicate ion or electron
      dtype: distribution type 'f','b','r'

    Returns:
      The parameter struct for the calibration file

    NOTES:
      #1 Reading and applying the calibration parameters is done separately, because reading later when
         they are applied leads to duplicated parameter reads. And because there is not enough information
         to apply parameters at load time.

    $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/SST/SST_cal_workdir/thm_sst_read_calib_params.pro $

(See projects/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_read_calib_params.pro)