This page was created by the IDL library routine
mk_html_help2
.
Last modified: Tue May 7 11:36:21 2013.
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: jwl $ $LastChangedDate: 2012-11-06 14:19:11 -0800 (Tue, 06 Nov 2012) $ $LastChangedRevision: 11196 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_load_sst2.pro $
(See 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-01-14 16:18:31 -0800 (Mon, 14 Jan 2013) $ $LastChangedRevision: 11439 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_part_dist2.pro $
(See 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 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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_build_cal_files.pro $
(See 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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calibration_tests.pro $
(See 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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_calib_params2.pro $
(See 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-02-27 12:41:35 -0800 (Wed, 27 Feb 2013) $ $LastChangedRevision: 11622 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_convert_units2.pro $
(See 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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_cross_contamination_remove.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_cross_contamination_remove.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-03-07 19:17:56 -0800 (Thu, 07 Mar 2013) $ $LastChangedRevision: 11751 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2__define.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2__define.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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_16x64_2.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: 2012-11-01 16:46:42 -0700 (Thu, 01 Nov 2012) $ $LastChangedRevision: 11152 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_dist3d_def2.pro $
(See 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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_energy_cal2.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_energy_cal2.pro)
NAME: thm_sst_load_calibrate PURPOSE: Wrapper which loads SST data and performs various calibration tasks; providing a high level interface to sst data. As of 2013-03-11 this provides the most advanced SST calibrations. #1 GEANT4 modeled theoretical channel efficiencies.(provided by Drew Turner) #2 GEANT4 modeled theoretical energy boundaries.(provided by Drew Turner) #3 Empirical dead layers calculated through intercalibration with ESA.(provided by Drew Turner) #4 Empircal detector performance calculated through intercalibration with ESA. (provided by Drew Turner) #5 Interpolates energy channels to single energy grid. (So that moments & pitch angle distributions can be generated) #6 Interpolates energy channels with ESA to fill energy gap between instruments. Inputs: probe=probe: Default is "a" datatype=datatype: Default is "psif" trange=trange: Default is current(loading more than 2 hours could be very slow) energies=energies: The target energy interpolates for SST data in eV default: [26000.,28000., 31000.000, 42000.000, 55500.000, 68000.000, 95500.000, 145000.00, 206500.00, 295500.00, 420000.00, 652500.00,$ 1133500.0, 3976500.0] sun_bins=sun_bins: The SST look directions to remove due to sun contamination. default: [0,8,16,24,32,33,40,47,48,55,56,57] Set to -1 for no sun removal Outputs: dist_data=dist_data: dist_data pointer array(like the type returned by thm_part_dist_array.pro) dist_data can be used with standard particle routines like thm_part_moments.pro & thm_part_getspec.pro error=error: After completion, will be set 1 if error occured, zero otherwise NOTES: #1 As of now, this thing is extremely inefficient in processor & memory. This limits loads to only a few hours on machines with 2-4 Gb of RAM. Future iterations will window loading to reduce memory utilization at the expense of higher processing time. #2 Only intended for psif/psef, for now. Any other usages will produce unreliable results or errors. #3 Loads ESA data to perform intercalibration between instruments on the fly. #4 More detailed SST electrons calibration parameters are pending new ESA decontamination. Examples: #1 thm_sst_load_calibrate,probe='d',datatype='psif',trange=['2011-07-29/13:00:00','2011-07-29/14:00:00'],dist_data=dist_psif thm_part_moments,inst='psif',probe='d',dist_array=dist_psif thm_part_getspec,data_type='psif',probe='d',dist_array=dist_psif,angle='phi' See Also: thm_sst_interpolate_tests.pro thm_part_dist_array.pro $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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_load_calibrate.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_load_calibrate.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: pcruce $ $LastChangedDate: 2013-03-11 16:02:06 -0700 (Mon, 11 Mar 2013) $ $LastChangedRevision: 11768 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_read_calib_params.pro $
(See themis/spacecraft/particles/SST/SST_cal_workdir/thm_sst_read_calib_params.pro)