This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Sep 19 14:20:01 2014.
This is an experimental routine. It will most likely disappear. Davin Larson
(See projects/themis/spacecraft/particles/data_cache.pro)
Deprecated, 8-feb-2010,jmm
(See projects/themis/spacecraft/particles/thm_cal_mom.pro)
Procedure:
thm_cmb_clean_sst
Purpose:
Runs standard ESA sanitation routine on data array.
-removes excess fields in data structures
-performs unit conversion (if UNITS specified)
-removes retrace bin (top energy)
-reverses energies to be in ascending order
Calling Sequence:
thm_cmb_clean_esa, dist_array, [,units=units]
Input:
dist_array: ESA particle data array from thm_part_dist_array
units: String specifying output units
Output:
none, modifies input
Notes:
Further unit conversions will not be possible after sanitation
due to the loss of some support quantities.
$LastChangedBy: aaflores $
$LastChangedDate: 2014-01-10 18:02:25 -0800 (Fri, 10 Jan 2014) $
$LastChangedRevision: 13850 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_cmb_clean_esa.pro $
(See projects/themis/spacecraft/particles/thm_cmb_clean_esa.pro)
Procedure:
thm_cmb_clean_sst
Purpose:
Runs standard SST sanitation routine on data array.
-removes excess fields in data structures
-performs unit conversion (if UNITS specified)
-applies contamination removal (none or default bins)
Calling Sequence:
thm_cmb_clean_sst, dist_array [,units] [,sst_sun_bins=sst_sun_bins]
Input:
dist_array: SST particle data array from thm_part_dist_array
units: String specifying output units
sst_sun_bins: Numerical list of contaminated bins to be removed
Output:
none, modifies input
Notes:
Further unit conversions will not be possible after sanitation
due to the loss of some support quantities.
$LastChangedBy: aaflores $
$LastChangedDate: 2014-01-10 18:02:25 -0800 (Fri, 10 Jan 2014) $
$LastChangedRevision: 13850 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_cmb_clean_sst.pro $
(See projects/themis/spacecraft/particles/thm_cmb_clean_sst.pro)
Procedure: thm_convert_cmb_units.pro Purpose: Unit conversion routine for combined (ESA+SST) particle distributions. Calling Sequence: This procedure is called implicitly by conv_units.pro Inputs: data: single combined distribution structure units: string specifying the target units (flux, eflux, or df) scale: set to named variable to pass out conversion factor Outputs: none, modifies input structure Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2013-10-17 18:50:45 -0700 (Thu, 17 Oct 2013) $ $LastChangedRevision: 13330 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_convert_cmb_units.pro $
(See projects/themis/spacecraft/particles/thm_convert_cmb_units.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 projects/themis/spacecraft/particles/thm_load_esa.pro)
PURPOSE:
Apply eclipse corrections (when present) to 3D data structures.
ARGUMENTS:
data: Valid 3D data structure
KEYWORDS:
eclipse: Flag used by this routine to determine when an ecplise
starts or ends (assists output messages). Will be set
to 1 at the start of an eclipse and 0 at the end.
NOTES:
$LastChangedBy: aaflores $
$LastChangedDate: 2013-09-10 12:11:07 -0700 (Tue, 10 Sep 2013) $
$LastChangedRevision: 13011 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_apply_eclipse.pro $
(See projects/themis/spacecraft/particles/thm_part_apply_eclipse.pro)
Procedure: thm_part_checkbins Purpose: Checks for changes compatability between distributions and returns boolean. Input: dist1: 3D particle data structure dist2: 3D particle data structure Output: return value: (bool) 1 if all fields match, 0 otherwise msg: string describing which fields differed Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2014-03-04 17:05:29 -0800 (Tue, 04 Mar 2014) $ $LastChangedRevision: 14492 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_checkbins.pro $
(See projects/themis/spacecraft/particles/thm_part_checkbins.pro)
NAME:
thm_part_check_trange
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_part_check_trange(probe, datatype, trange [,sst_cal=sst_cal] [,fail=fail])
KEYWORDS:
probe: String or string array specifying the probe
datatype: String or string array specifying the type of
particle data requested (e.g. 'peif', 'pseb')
trange: Two element array specifying the numeric time range
sst_cal: Flag to check data from new SST calibrations
fail: Set to named variable to pass out error messages (string)
OUTPUT:
1 if current data covers what is requested, 0 otherwise
NOTES:
$LastChangedBy: aaflores $
$LastChangedDate: 2014-05-05 18:12:35 -0700 (Mon, 05 May 2014) $
$LastChangedRevision: 15053 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_check_trange.pro $
(See projects/themis/spacecraft/particles/thm_part_check_trange.pro)
*** WARNING: This routine is still in testing ***
Procedure:
thm_part_combine.pro
Purpose:
Create combined particle distribution from ESA and SST data.
This distributions acts as a new data type and can be passed
to all particle product code to create combined ESA/SST plots.
Calling Sequence:
combined_dist = thm_part_combine(probe=probe, trange=trange,
esa_datatype=esa_datatype, sst_datatype=sst_datatype
[,units=units] [,regrid=regrid] [,energies=energies]
[,orig_esa=orig_esa] [,orig_sst=orig_sst])
Inputs:
probe: Probe designation (string).
trange: Two element array specifying time range (string or double).
esa_datatype: ESA datatype designation (string).
sst_datatype: SST datatype designation (string).
units: String specifying output units ('flux', 'eflux', or 'df')
regrid: Two element array specifying the number of points used to regrid
the data in phi and theta respectively (int or float).
energies: Array specifying the energies used to replace the default SST energies
and cover the ESA-SST energy gap (in ascending order) (float).
sst_sun_bins: Array list of SST bins to mask (bin indices) (int).
only_sst: Interpolates ESA to match SST and returns SST(only) with interpolated bins.(Backwards compatibility: functionality of thm_sst_load_calibrate)
interp_to_esa: Combined product but data interpolated to match ESA(instead of always interpolating to higher resolution)
interp_to_sst: Combined product but data interpolated to match SST(instead of always interpolating to higher resolution)
Outputs:
combined_dist: Pointer array to combined distribution data. This is analagous
to the arrays returned by thm_part_dist_array with each element
referencing a distinct mode, or in this case combination of modes.
orig_esa: Pointer array to original ESA distribution data.
orig_sst: Pointer array to original SST distribution data.
General Notes:
Combined distributions can be used with the following routines in the same
way as output from thm_part_dist_array:
thm_part_products
thm_part_slice2d
thm_part_conv_units (unit conversion)
thm_part_moments (wrapper/deprecated)
thm_part_getspec (wrapper/deprecated)
Processing more than 1-2 hours of data (full) at once may cause older systems to
run out of memory. Typical run times 30-60+ sec.
SST: This routine automatically uses the /sst_cal option when loading sst full
or burst data and sets default contamination removal options. Reduced data
will no calibrations or contamination removal applied. Other contamination
options may be passed through to override the defaults, see SST contamination
removal crib for options.
Developer Notes:
In general this code makes the following assumptions about the particle data:
-(ESA & SST) The dimensions of all fields will remain constant within a mode.
-(ESA & SST) A single distribution's energy bins are constant across all look angles.
-(ESA & SST) Energy bins may change within a mode (they probably never will but
this is assumed for safety).
-(ESA & SST) Look directions, while general constant within a mode, may change at
any point due to eclipse corrections to phi values.
All E/phi/theta items above are assumed for the bin widths as well. Greater
uniformity will be assumed as data is replaced with interpolated versions.
$LastChangedBy: pcruce $
$LastChangedDate: 2014-03-05 17:20:40 -0800 (Wed, 05 Mar 2014) $
$LastChangedRevision: 14508 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_combine.pro $
(See projects/themis/spacecraft/particles/thm_part_combine.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 projects/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/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_copy.pro $
(See projects/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: aaflores $
$LastChangedDate: 2014-05-09 14:11:06 -0700 (Fri, 09 May 2014) $
$LastChangedRevision: 15085 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_dist.pro $
(See projects/themis/spacecraft/particles/thm_part_dist.pro)
Purpose: Find the sun direcion vector if requested
(See projects/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.
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
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:
SST_CAL: Flag to use newest SST calibrations
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')
See Also: thm_crib_part_product, thm_part_products
thm_crib_part_slice2d, thm_part_slice2d
thm_crib_esa_bgnd_remove, thm_esa_bgnd_remove,
Created by Bryan Kerr
Modified by A. Flores
$LastChangedBy: aaflores $
$LastChangedDate: 2014-02-24 18:05:51 -0800 (Mon, 24 Feb 2014) $
$LastChangedRevision: 14423 $
$URL $
(See projects/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_interp.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_interp.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2013-09-26 16:32:05 -0700 (Thu, 26 Sep 2013) $
$LastChangedRevision: 13156 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_energy_interpolate.pro $
(See projects/themis/spacecraft/particles/thm_part_energy_interp.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-09-26 16:32:05 -0700 (Thu, 26 Sep 2013) $
$LastChangedRevision: 13156 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_energy_interpolate.pro $
(See projects/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/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_getanbins.pro $
(See projects/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 projects/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 projects/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 projects/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 projects/themis/spacecraft/particles/thm_part_getmodechange.pro)
PROCEDURE: thm_part_getspec PURPOSE: Generate spectra from particle data Provides different angular view and angle restriction options in spacecraft and fac coords Inputs: Argument descriptions inline below. Outputs: Argument descriptions inline below Keywords: Argument description inline below Notes: Old version in particles/deprecated $LastChangedBy: aaflores $ $LastChangedDate: 2014-05-09 14:03:20 -0700 (Fri, 09 May 2014) $ $LastChangedRevision: 15083 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_getspec.pro $
(See projects/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
is_esa: Flag denoting esa data
is_sst: Flag denoting sst data
valid: 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 ESA sweep mode index (thm_read_esa_sweep_*)
angle_mode: Integer denoting ESA angle mode index (thm_read_esa_angle_*)
esa_solar_wind: Solar wind flag for ESA
}
NOTES
(See projects/themis/spacecraft/particles/thm_part_get_config.pro)
*** This routine is in development, do not use! *** Procedure: thm_part_merge_dists.pro Purpose: Merge ESA/SST particle distributions once they have been altered to match in time, energy, angle, and mode transition. Calling Sequence: Inputs: Outputs: Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2013-09-26 18:59:57 -0700 (Thu, 26 Sep 2013) $ $LastChangedRevision: 13157 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_combine.pro $
(See projects/themis/spacecraft/particles/thm_part_merge_dists.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/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_omni_convert.pro $
(See projects/themis/spacecraft/particles/thm_part_omni_convert.pro)
NAME:
thm_part_remove.pro
PURPOSE:
Remove bins that fall below a specified # of counts from any 3D particle data structure.
CALLING SEQUENCE:
thm_part_remove, dist, threshold=threshold, [/zero], [/remove]
INPUT ARGUMENTS:
dist: Particle distribution(s).
Can be single or array of structure(s) or pointer(s) to structure(s).
threshold: The value below wich data points will be removed or zeroed.
Must be in the same units as the input data.
KEYWORDS:
zero: (default) Data below the threshold will be set to zero.
remove: Data below the threshold will be removed. Specifically,
the data will be set to NaN and the bin flag set to off.
NOTES:
(See projects/themis/spacecraft/particles/thm_part_remove.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 projects/themis/spacecraft/particles/thm_part_smooth.pro)
PROCEDURE: thm_part_sphere_interp
PURPOSE: Temporary generalized copy of thm_part_sphere_interpolate
(Interpolate particle data to match the look direcitons of another distribution)
INPUTS:
source: The particle distribution to be modified by spherical interpolation.
target: The particle distribution to which the sources times have been matched.
This distribution will only be used to merge times between modes.
OUTPUTS:
Replaces source with a spherically interpolated version
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 ton 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: aaflores $
$LastChangedDate: 2013-10-02 10:31:06 -0700 (Wed, 02 Oct 2013) $
$LastChangedRevision: 13173 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_sphere_interpolate.pro $
(See projects/themis/spacecraft/particles/thm_part_sphere_interp.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 ton 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: aaflores $ $LastChangedDate: 2013-10-02 10:31:06 -0700 (Wed, 02 Oct 2013) $ $LastChangedRevision: 13173 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_sphere_interpolate.pro $
(See projects/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/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_subtract.pro $
(See projects/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: aaflores $ $LastChangedDate: 2014-01-10 18:02:25 -0800 (Fri, 10 Jan 2014) $ $LastChangedRevision: 13850 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_time_interpolate.pro $
(See projects/themis/spacecraft/particles/thm_part_time_interpolate.pro)
Procedure:
thm_part_trange
Purpose:
Store/retrive the last requested time range for a particle data type.
This routine should only be called internally by the particle load routines.
Calling Sequence:
thm_part_set_trange, probe, datatype, trange [,sst_cal=sst_cal]
Input:
probe: (string) scalar containing probe designation
datatype: (string) scalar containing particle data type
set: (double) two element array specifying a time range
sst_cal: (bool/int) flag to use time range for data loaded with thm_load_sst2
Output:
get: (double) two element array containing the last loaded time range
for the specified data, [0,0] if no data has been loaded
See Also:
thm_part_check_trange
thm_load_esa_pkt
thm_load_sst
thm_load_sst2
Notes:
Get operation performed before set.
$LastChangedBy: aaflores $
$LastChangedDate: 2014-05-05 18:12:35 -0700 (Mon, 05 May 2014) $
$LastChangedRevision: 15053 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_1_00/projects/themis/spacecraft/particles/thm_part_trange.pro $
(See projects/themis/spacecraft/particles/thm_part_trange.pro)