This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Nov 2 11:01:31 2012.
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)
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: 2012-03-12 17:33:39 -0700 (Mon, 12 Mar 2012) $
$LastChangedRevision: 10068 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/particles/thm_part_dist.pro $
(See themis/spacecraft/particles/thm_part_dist.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_7_01/idl/themis/spacecraft/particles/thm_part_getanbins.pro $
(See themis/spacecraft/particles/thm_part_getanbins.pro)
Purpose: Helper function to check support data's existence and time range 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)
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.
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)