This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
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: 2020-07-14 10:56:48 -0700 (Tue, 14 Jul 2020) $
$LastChangedRevision: 28887 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/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)
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.
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
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: 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/tags/spedas_4_0/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)
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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)
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/tags/spedas_4_0/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)