This page was created by the IDL library routine
mk_html_help2
.
Last modified: Tue May 7 11:36:21 2013.
This is an experimental routine. It will most likely disappear. Davin Larson
(See themis/spacecraft/particles/data_cache.pro)
Deprecated, 8-feb-2010,jmm
(See themis/spacecraft/particles/thm_cal_mom.pro)
NAME: thm_check_part_data 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_check_part_data(probe, type, trange) INPUT: probe: String specifying the probe type: Standart string (or array of) specifying the type of particle data requested (e.g. 'peif', 'pseb') trange: Two element array specifying the numeric time range OUTPUT: 1 if current data covers what is requested, 0 otherwise NOTES:
(See themis/spacecraft/particles/thm_check_part_data.pro)
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 themis/spacecraft/particles/thm_load_esa.pro)
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 fractional_counts: ESA does some rounding when it converts back to counts. You should probably set this keyword to stop the rounding. 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: pcruce $ $LastChangedDate: 2013-03-07 09:47:09 -0800 (Thu, 07 Mar 2013) $ $LastChangedRevision: 11743 $ $URL $
(See themis/spacecraft/particles/thm_part_conv_units.pro)
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 $LastChangedBy: pcruce $ $LastChangedDate: 2012-09-27 15:21:54 -0700 (Thu, 27 Sep 2012) $ $LastChangedRevision: 10956 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_copy.pro $
(See themis/spacecraft/particles/thm_part_copy.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. 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 $LastChangedBy: pcruce $ $LastChangedDate: 2013-01-10 18:10:18 -0800 (Thu, 10 Jan 2013) $ $LastChangedRevision: 11424 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_dist.pro $
(See themis/spacecraft/particles/thm_part_dist.pro)
Purpose: Find the sun direcion vector if requested
(See themis/spacecraft/particles/thm_part_dist_array.pro)
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. SST_CAL: Flag to use new SST calibrations (BETA) 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 Other Keywords: FORMAT: (old) Single string that can be used instead of PROBE and DATATYPE (e.g. 'thb_psif' or 'tha_peeb') 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') Contamination Removal: BACKGROUND REMOVAL(BGND) Description, Warnings and Caveats(from Vassilis Angelopoulos): This code allows for keywords that permit omni-directional or anode-dependent background removal from penetrating electrons in the ESA ion and electron detectors. Anode-dependent subtraction is used when possible by default, i.e., when angle information is available; but user has full control by keyword specification. Default bgnd estimates use 3 lowest counts/s values. Scaling of the background (artificial scaling) can also allow playing with background estimates to account for noise statistics in the background itself. The parameters that have worked well for me during high bgnd levels are: ,/bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.5 This background subtraction to be used at the inner magnetosphere, or when SST electron fluxes indicate presence of significant electron fluxes at the satellite (injections). At quiet times the code tends to remove real fluxes, so beware. Crib sheets for contamination removal with thm_part_getspec and thm_part_moments are listed below in 'See Also'. The same keywords are valid for this code; a few are documented below. Contamination/Background Keywords: The following keywords are passed to the appropriate data retrieval routines. The resulting distributions will have the specified contamination removal applied. 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: Check the list of keywords in THM_SST_REMOVE_SUNPULSE for more. MASK_REMOVE: Set this keyword to the proportion of values that must be 0 at all energies to determine that a mask is present. Generally .99 or 1.0 is a good value. The mask is a set of points that are set to 0 on-board the spacecraft. By default they will be filled by linear interpolation across phi. METHOD_SUNPULSE_CLEAN: set this to a string: Either 'median' or 'spin_fit' or 'z_score_mod' 'median': This will remove all points that are greater than 2.0 standard deviations from the median.By default they will be filled by a linear interpolation across the phi angle by default. 'spin_fit': This will remove all points that are greater than 2.0 standard deviations from a spin fit across phi angle. The equation used to fit is A+B*sin(phi)+C*cos(phi). By default these points will be filled by a linear interpolation across the phi angle. The fitting is done using the svdfit routine from the idl distribution. 'z_score_mod': This will remove all points that have a modified z-score(calculated across phi) greater than 3.5 The modified z-score is a normalized outlier detection test defined as follows: #1 X_Bar = median(X+1) #2 Sigma = MAD = Median Absolute Deviation = median(abs(X-X_Bar)) #3 Z_Score_Mod = .6745*(X - X_Bar)/Sigma This test can often get excellent results because it is insensitive to variation in standard deviation and skew in the distributions. FILLIN_METHOD: Set this keyword to a string that specifies the method used to fill the points that are removed via the method_sunpulse_clean or the mask_remove keywords. If 'interpolation' is set, this routine will interpolate across the phi angle. This is the default behavior. Interpolation is done using the interp_gap routine. If 'spin_fit' is set this routine will perform a spin fit to the data after the points have been removed using the equation A+B*sin(phi)+C*cos(phi). It will then generate expected values for each removed phi using the equation of fit. The fitting is done using the svdfit routine from the idl distribution. Note that if 'spin_fit' is selected for the clean method and the fill method, this routine will perform two spin fits. LIMIT_SUNPULSE_CLEAN: set this equal to a floating point number that will override the default of 2.0 standard deviation tolerance or 3.5 z_score_tolerance, used by the sunpulse cleaning methods by default. This keyword will only have an effect if the method_sunpulse_clean keyword is set. ENOISE_BINS: A 0-1 array that indicates which bins should be used to calculate electronic noise. A 0 indicates that the bin should be used for electronic noise calculations. This is basically the output from the bins argument of edit3dbins. It should have dimensions 16x4. ENOISE_REMOVE_METHOD: (default: 'fit_median') set the keyword to a string specifying the method you want to use to calculate the electronic noise that will be subtracted This function combines values across time. The allowable options are: 'min': Use the minimum value in the time interval for each bin/energy combination. 'average': Use the average value in the time interval for each bin/energy combination. 'median': Use the median value in the time interval for each bin/energy combination. 'fit_average': Fill in selected bins with a value that is interpolated across phi then subtracts the average of the difference between the interpolated value and the actual value from each selected bin/energy combination. 'fit_median': Fill in selected bins with a value that is interpolated across phi then subtracts the median of the difference between the interpolated value and the actual value from each selected bin/energy combination. 'fill': Fill the selected bins using the technique specified by enoise_remove_method_fit, or interpolation by default. (note that if this method is used, enoise_bgnd_time is not required) ENOISE_REMOVE_FIT_METHOD: (default:'interpolation'): Set this keyword to control the method used in 'fit_average' & 'fit_median' to fit across phi. Options are 'interpolation' & 'spin_fit' By default, missing bins are interpolated across phi. Setting enoise_remove_fit_method='spin_fit' will instead try to fill by fitting to a curve of the form A+B*sin(phi)+C*cos(phi). ENOISE_BGND_TIMES: This should be either a 2 element array or a 2xN element array(where n is the number of elements in enoise_bins). The arguments represents the start and end times over which the electronic background will be calculated for each bin. If you pass a 2 element array the same start and end times can be used for each bin. If you pass a 2xN element array, then the Ith bin in enoise_bins will use the time enoise_bgnd_time[0,I] as the start time and enoise_bgnd_time[1,I] as the end time for the calculation of the background for that bin. If this keyword is not set then electronic noise will not be subtracted. See Also: thm_part_slice2d, thm_clib_part_slice2d, thm_crib_esa_bgnd_remove, thm_esa_bgnd_remove, thm_crib_sst_contamination, thm_sst_remove_sunpulse Created by Bryan Kerr Modified by A. Flores $LastChangedBy: aaflores $ $LastChangedDate: 2013-03-13 15:10:02 -0700 (Wed, 13 Mar 2013) $ $LastChangedRevision: 11800 $ $URL $
(See themis/spacecraft/particles/thm_part_dist_array.pro)
PROCEDURE: thm_part_energy_interpolate PURPOSE: Interpolate particle data by energy between sst & esa distributions using a weighted curve fitting routine INPUTS: dist_sst: SST particle distribution structure in flux dist_esa: ESA particle distribution structure in flux energies: The set of target energies to interpolated the SST to. OUTPUTS: Replaces dist_sst with the interpolated data set KEYWORDS: error: Set to 1 on error, zero otherwise NOTES: #1 The number of time samples and the times of those samples must be the same for dist_sst & dist_esa (use thm_part_time_interpolate.pro) #2 The number of angles and the angles of each sample must be the same for dist_sst & dist_esa (use thm_part_sphere_interpolate.pro) SEE ALSO: thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert,thm_part_time_interpolate.pro,thm_part_sphere_interpolate.pro $LastChangedBy: pcruce $ $LastChangedDate: 2013-03-07 09:47:09 -0800 (Thu, 07 Mar 2013) $ $LastChangedRevision: 11743 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_energy_interpolate.pro $
(See themis/spacecraft/particles/thm_part_energy_interpolate.pro)
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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_getanbins.pro $
(See themis/spacecraft/particles/thm_part_getanbins.pro)
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 themis/spacecraft/particles/thm_part_getmodechange.pro)
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 themis/spacecraft/particles/thm_part_getmodechange.pro)
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 themis/spacecraft/particles/thm_part_getmodechange.pro)
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 themis/spacecraft/particles/thm_part_getmodechange.pro)
PROCEDURE: thm_part_getspec PURPOSE: Generates tplot variables containing energy-time angular particle spectra for any angle range and/or any energy range. 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' 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. 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. [90, 180]) to specify the 'daylight' hemisphere in DSL coordinates. Default is all 360 degrees (e.g. [0, 360]). If the phi range is greater than 360 degrees, then the phi bins at the beginning of the phi range are added and wrapped around the end of phi range. For example, if phi=[-90,360], the phi bins corresponding to 270-360 degrees are appended to the bottom of the plot. Also controls which bins are selected for pitch/gyrovelocity spectra. Phi is limited to be between -360 and 720 degrees. Note that, if the ENERGY keyword is set (as is true in the default case). This is also true for 'pa' and 'gyro' cases. 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]). Also controls which bins are selected for pitch/gyrovelocity spectra. pitch = Angle range of interest (2 element array) in degrees relative to the magnetic field. Default is all (e.g. [0, 180]). Has no effect on phi/theta spectra plots. gyro = Gyrovelocity angle range of interest (2 element array) in degrees. Same rules as specifying phi apply to gyrophse. Default is all (e.g. [0, 360]). Has no effect on phi/theta spectra plots. erange = Energy range (in eV) of interest (2 element array). Default is all. data_type = The type of data to be loaded (e.g. ['peif', 'peef']) start_angle = Angle at which to begin plotting the data the bottom of the plot along the y-axis. At this time this works for phi only. If not set, keyword defaults to first element of phi input. suffix = Suffix to add to tplot variable names. /AUTOPLOT: Set to activiate a simple plotting routine to display tplot variables created by this routine. /ENERGY: Set to output tplot variables containing the energy spectrum of the energy/angle ranges input above. angle = Type of angular spectrum tplot variable created and plotted using the energy/angle ranges input above e.g. 'phi'. Default is 'phi'. The type of angular spectra is appended to its corresponding tplot variable name. All possible options are: phi = phi angular spectrum theta = theta angular spectrum pa = pitch angular spectrum (only works with full angle ranges) gyro = gyrovelocity angular spectrum (only works with full angle ranges) NOTE: If neither of ENERGY and ANGLE keywords are specified, then then both are turned on with ANGLE defaulting to 'phi'. /GET_SUPPORT_DATA: load support_data variables as well as data variables into tplot variables. regrid = [m,n] Number of angle bins, used to re-grid (2-element array) along phi (gyrovelocity) and theta (pitch), respectively, when calculating pitch/gyrovelocity angle spectrum. For example, e.g. [32,16] creates a regularly-spaced array of 32 phi angles by 16 theta angles that resample the probe(s) native angle bin array. Default is [16,8]. Keyword has no effect on phi and theta spectragrams. Accuracy of the spectragrams increases when more angle bins are used to re-grid. Suitable numbers for m and n are numbers like 2^k. So far, k=2-6 has been tested and work. Other numbers will work provided 180/n and 360/m are rational. other_dim = Keyword passed to THM_FAC_MATRIX_MAKE for conversion to field aligned coordinates to create pitch angle and gyrovelocity spectra. See THM_FAC_MATRIX_MAKE for valid input. Default is 'mphigeo'. /NORMALIZE: Set to normalize the flux for each time sample to 0-1. badbins2mask = A 0-1 array that indicates which SST bins will be masked with NaN to eliminate things like sun contamination. The array should have the same number of elements as the number of angle bins for a given data type. A 0 indicates that will be masked with a NaN. This is basically the output from the bins argument of EDIT3DBINS. datagap = Maximum time gap in seconds over which to interpolate the plot. Sets the DATAGAP flag in the dlimits which SPECPLOT uses to interpolate pixels in time gaps less than DATAGAP. Use this keyword when overlaying spectra plots, allowing the underlying spectra to be shown in the data gaps of the overlying spectra. Default is zero. 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). dist_array: Provide an array of data instead of having thm_part_getspec/thm_part_moments2 load the data directly. This allows preprocessing/sanitization operations to be performed prior to moment generation. See thm_part_dist_array.pro, thm_part_conv_units.pro ESA PEER/PEIR/PEIF Background Removal Keywords: /bdnd_remove: Turn on ESA background removal. bgnd_type(Default 'anode'): Set to string naming background removal type: 'angle','omni', or 'anode'. bgnd_npoints(Default = 3): Set to the number of lowest values points to average over when determining background. bgnd_scale(Default=1): Set to a scaling factor that the background will be multiplied by before it is subtracted GUI-RELATED KEYWORDS: /GUI_FLAG: Flag tells code to recognize status bar and history window objects. gui_statusBar = Object reference to status bar object in GUI. gui_historyWin = Object reference to history window object in GUI. EXAMPLE: thm_part_getspec, probe='d', trange=['07-06-17','07-06-19'] SEE ALSO: THM_CRIB_PART_GETSPEC, THM_PART_MOMENTS2, THM_PART_GETANBINS, THM_LOAD_SST, THM_LOAD_ESA_PKT, THM_FAC_MATRIX_MAKE,THM_REMOVE_SUNPULSE,THM_CRIB_SST_CONTAMINATION NOTES: For documentation on sun contamination correction keywords that may be passed in through the _extra keyword please see: thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro BACKGROUND REMOVAL(BGND) Description, Warnings and Caveats(from Vassilis Angelopoulos): This code allows for keywords that permit omni-directional or anode-dependent background removal from penetrating electrons in the ESA ion and electron detectors. Anode-dependent subtraction is used when possible by default, i.e., when angle information is available; but user has full control by keyword specification. Default bgnd estimates use 3 lowest counts/s values. Scaling of the background (artificial scaling) can also allow playing with background estimates to account for noise statistics in the background itself. The parameters that have worked well for me during high bgnd levels are: ,/bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.5 The same keywords when used in thm_part_getspec, and thm_part_moments are understood and passed to the data extraction routines, such that they will do the removal before computing moments or spectra. This background subtraction to be used at the inner magnetosphere, or when SST electron fluxes indicate presence of significant electron fluxes at the satellite (injections). At quiet times the code tends to remove real fluxes, so beware. CREATED BY: Bryan Kerr $LastChangedBy: bckerr $ $LastChangedDate: 2008-06-13 13:29:12 -0700 (Fri, 13 Jun 2008) $ $LastChangedRevision: 3204 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_getspec.pro $
(See themis/spacecraft/particles/thm_part_getspec.pro)
Purpose: Helper function to check support data's existence and time range (Main procedure further below) Input: tvar - string representing tplot variable tr - two element numerical time range Output: Returns 1 if time range is covered by the data
(See themis/spacecraft/particles/thm_part_getspec.pro)
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 esa_flag: Flag denoting esa data (1b=esa) esa_solarwind_flag: ESA solar wind flag valid_flag: 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 sweep mode index (thm_read_esa_sweep_*) angle_mode: Integer denoting angle mode index (thm_read_esa_angle_*) } NOTES
(See themis/spacecraft/particles/thm_part_get_config.pro)
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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_omni_convert.pro $
(See themis/spacecraft/particles/thm_part_omni_convert.pro)
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 themis/spacecraft/particles/thm_part_smooth.pro)
PROCEDURE: thm_part_sphere_interpolate PURPOSE: Interpolate particle data to match the look direcitons of another distribution INPUTS: source: A particle dist_data structure to be modified by interpolation to match target target: A particle dist_data structure whose look directions will be matched OUTPUTS: Replaces source with a spherically interpolated target KEYWORDS: error: Set to 1 on error, zero otherwise NOTES: #1 Interpolation done using IDL library routine "griddata" #2 This code assumes that source & target have been time interpolated to match each other This has a done of TBDs, we need to come back and fix them when time is available. With TBDs this code will not have general purpose utility... SEE ALSO: thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert,thm_part_time_interpolate.pro $LastChangedBy: pcruce $ $LastChangedDate: 2013-03-12 13:13:53 -0700 (Tue, 12 Mar 2013) $ $LastChangedRevision: 11781 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_sphere_interpolate.pro $
(See themis/spacecraft/particles/thm_part_sphere_interpolate.pro)
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/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_subtract.pro $
(See themis/spacecraft/particles/thm_part_subtract.pro)
PROCEDURE: thm_part_time_interpolate PURPOSE: Interpolate particle data to match the time grid of another distribution, or to an arbitary time grid INPUTS: source: A particle dist_data structure to be modified by interpolation to match target target: A particle dist_data structure whose times will be matched, or an array of target times for interpolatuion. OUTPUTS: Replaces source with a time interpolated dist_data structure KEYWORDS: error: Set to 1 on error, zero otherwise NOTES: Any target times that occur between modes will contain samples filled with NANs. Effective interpolation is very very tricky between modes.(Read: It will probably never happen) Accepts any keywords normally accepted by IDL interpol This has a done of TBDs, we need to come back and fix them when time is available. SEE ALSO: thm_part_dist_array, thm_part_smooth, thm_part_subtract,thm_part_omni_convert $LastChangedBy: pcruce $ $LastChangedDate: 2013-03-07 09:47:09 -0800 (Thu, 07 Mar 2013) $ $LastChangedRevision: 11743 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/spacecraft/particles/thm_part_time_interpolate.pro $
(See themis/spacecraft/particles/thm_part_time_interpolate.pro)