This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
Name:
thm_part_load
Purpose:
Load ESA or SST particle data.
Calling Sequence:
thm_part_load, probe=probe, datatype=datatype
[,trange=trange] [,sst_cal=sst_cal]
[,forceload=forceload]
Keywords:
probe: String or string array containing spacecraft designation (e.g. 'a')
datatype: String or string array containing data type specification (e.g. 'peif')
trange: Two element array specifying the desired time range
sst_cal: Flag to use improved SST calibrations
forceload: Flag to ignore check for existing data
Notes:
-If all requested data is already present the load will be
skipped unless the forceload keyword is 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_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_part_load.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_part_load.pro)
PROCEDURE:
thm_part_products
PURPOSE:
Generate spectra and moments from THEMIS particle data.
Provides different angular view and angle restriction options
in spacecraft and field alligned coordinates.
Data Products:
'energy' - energy spectrogram
'phi' - azimuthal spectrogram
'theta' - elevation spectrogram
'gyro' - gyrophase spectrogram
'pa' - pitch angle spectrogram
'moments' - distribution moments (density, velocity, etc.)
Calling Sequence:
thm_part_products, probe=probe, datatype=datatype, trange=trange [,outputs=outputs] ...
Example Usage:
See crib sheets in .../themis/examples/
Input Keywords:
probe: Spacecraft designation, e.g. 'a','b'
datatype: Particle datatype, e.g. 'psif, 'peib'
trange: Two element time range [start,end]
outputs: List of requested outputs, array or space separated list, default='energy'
dist_array: Data loaded manually with thm_part_dist_array or thm_part_combine.
If specified then probe and dataytpe are not needed; trange is optional.
Outputs will be in the data's units (probably counts, or eflux for combined)
unless specified with UNITS keyword.
energy: Two element energy range [min,max], in eV
phi: Two element phi range [min,max], in degrees, spacecraft spin plane
theta: Two element theta range [min,max], in degrees, latitude from spacecraft spin plane
pitch: Two element pitch angle range [min,max], in degrees, magnetic field pitch angle
gyro: Two element gyrophase range [min,max], in degrees, gyrophase
mag_name: Tplot variable containing magnetic field data for moments and FAC transformations
pos_name: Tplot variable containing spacecraft position for FAC transformations
sc_pot_name: Tplot variable containing spacecraft potential data for moments corrections
units: Specify units of output variables. Must be 'eflux' to calculate moments.
'counts' - #
'rate' - # / s
'flux' - # / (cm^2 * s * sr * eV)
'eflux' - eV / (cm^2 * s * sr * eV) <default>
'df' - s^3 /(cm^3 * km^3)
regrid: Two element array specifying the resolution [azimuth,elevation]
used to regrid the data; default is [16,8]. Field aligned data
is always regridded while phi and theta spectra are regridded if
this keyword is specified.
fac_type: Select the field aligned coordinate system variant.
Existing options: 'phigeo', 'mphigeo', 'xgse'
sst_sun_bins: Array of which sst bins to decontaminate (list of bins numbers, not the old mask array)
Set to -1 to disable.
esa_bgnd_remove: Set to 0 to disable ESA background removal,
otherwise default anode-based background will be subtracted.
See thm_crib_esa_bgnd_remove for more keyword options.
esa_bgnd_advanced: Apply advanced ESA background subtraction.
Must call thm_load_esa_bkg first to calculate background.
Disables default background removal.
suffix: Suffix to append to output tplot variable names
start_angle: Set a start angle for azimuthal spectrogram y axis
get_error: Flag to return error estimates (*_sigma variables)
datagap: Setting for tplot variables, controls how long a gap must be before it is drawn.
(can also manually degap)
display_object: Object allowing dprint to export output messages
coord: if set, then velocity and flux variables are created for the
input coordinate system, in addition to the DSL variables
Output Keywords:
tplotnames: List of tplot variables that were created
get_data_structures: Set to named variable to return data structures when generating
field aligned outputs. This may considerably slow the process!
error: Error status flag for calling routine, 1=error 0=success
Notes:
$LastChangedBy: jimm $
$LastChangedDate: 2019-01-08 14:14:59 -0800 (Tue, 08 Jan 2019) $
$LastChangedRevision: 26441 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_part_products.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_part_products.pro)
Procedure:
thm_pgs_clean_cmb
Purpose:
Sanitize combined particle data structures for use with
thm_part_products. Excess fields will be removed and
field names conformed to standard.
Input:
data: Single combined particle data structure.
units: String specifying a units type ('flux', 'eflux', or 'df')
Output:
output: Sanitized output structure for use within thm_part_products.
Notes:
-not much should be happening here since the combined structures
are already fairly pruned
$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_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_cmb.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_cmb.pro)
PROCEDURE: thm_pgs_clean_esa
PURPOSE:
Helper routine for thm_part_products
Maps ESA data into simplified format for high-level processing.
Creates consistency for downstream routines and throws out extra fields to save memory
Inputs(required):
data: ESA particle data structure from thm_part_dist, get_th?_pe??, thm_part_dist_array, etc...
units: string specifying the units (e.g. 'eflux')
Outputs:
output structure elements:
data - particle data 2-d array, energy by angle. (Float or double)
scaling - scaling coefficient corresponding to 1 count/bin, used for error calculation (float or double)
time - sample start time(1-element double precision scalar)
end_time - sample end time(1-element double precision scalar)
phi - Measurment angle in plane parallel to spacecraft spin.(2-d array matching data array.) (Float or double)
dphi - Width of measurement angle in plane parallel to spacecraft spin.(2-d array matching data array.) (Float or double)
theta - Measurment angle in plane perpendicular to spacecraft spin.(2-d array matching data array.) (Float or double)
dtheta - Width of measurement angle in plane perpendicular to spacecraft spin. (2-d array matching data array.) (Float or double)
energy - Contains measurment energy for each component of data array. (2-d array matching data array.) (Float or double)
denergy - Width of measurment energy for each component of data array. (2-d array matching data array.)
bins - 0-1 array, indicating which bins are enabled for subsequent calculations. (2-d array matching data array.) (Integer type.)
charge - expected particle charge (1-element float scalar)
mass - expected particle mass (1-element float scalar)
magf - placeholder for magnetic field vector (3-element float array)
scpot - placeholder for spacecraft potential (1-element float scalar)
Keywords:
esa_max_energy: Set to maximum energy to toss bins that are having problems from instrument contamination.
esa_bgnd_advanced: Flag to apply advanced background subtraction
Background must be pre-calculated with thm_load_esa_bkg
$LastChangedBy: jimm $
$LastChangedDate: 2019-02-19 11:17:18 -0800 (Tue, 19 Feb 2019) $
$LastChangedRevision: 26643 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_esa.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_esa.pro)
PROCEDURE: thm_pgs_clean_sst
PURPOSE:
Helper routine for thm_part_products
Maps SST data into simplified format for high-level processing. Converts into physical untis
Creates consistency for downstream routines and throws out extra fields to save memory
Inputs(required):
data: An SST particle data structure, produced by thm_part_dist or thm_sst_ps?? etc...
units: The requested units for the data.
Outputs:
output: A sanitized SST data structure. Any instrument specific corrections should be applied.
Extraneous fields are discarded. All dimensions should be in ascending order.
Structure definition:
** Structure <afc6c05c>, 10 tags, length=30736, data length=30736, refs=1:
DATA FLOAT Array[16, 64]
TIME DOUBLE 1.1746086e+09
END_TIME DOUBLE 1.1746086e+09
PHI FLOAT Array[16, 64]
DPHI FLOAT Array[16, 64]
THETA FLOAT Array[16, 64]
DTHETA FLOAT Array[16, 64]
ENERGY FLOAT Array[16, 64]
DENERGY FLOAT Array[16, 64]
BINS INT Array[16, 64]
CHARGE FLOAT 0.000000
MASS FLOAT 0.0104390
MAGF FLOAT Array[3]
SC_POT FLOAT 0.000000
Keywords:
sst_sun_bins: The bin numbers that should be flagged as contaminated by sun and interpolated
sst_method_clean: how to decontaminate the sst data. Right now the only option is 'manual', but selects a good set of default sst_sun_bins, if not user specified.
sst_min_energy: Set to minimum energy to toss bins that are having problems from instrument degradation.
$LastChangedBy: aaflores $
$LastChangedDate: 2016-08-24 18:29:05 -0700 (Wed, 24 Aug 2016) $
$LastChangedRevision: 21724 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_sst.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_sst.pro)
Procedure:
thm_pgs_clean_support
Purpose:
Transform and/or interpolate support data to match the particle data.
Arguments:
times: Array of sample times for particledata
probe: String specifying the spacecraft
mag_tvar_in: String specifying a tplot variable containing magnetic field data
sc_pot_tvar_in: String specifying a tplot variable containing spacecraft potential data
Output Keywords:
mag_out: Array of magnetic field vectors corresponding to TIMES
sc_pot_out: Array of spacecraft potential data corresponding to TIMES
Notes:
If no valid tplot variables are specified for:
magnetic field - vector will be [0,0,0] at all times
spacecraft potential - will be 0
$LastChangedBy: jimm $
$LastChangedDate: 2019-02-19 11:17:18 -0800 (Tue, 19 Feb 2019) $
$LastChangedRevision: 26643 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_support.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_clean_support.pro)
Procedure: thm_pgs_dist_array_data Purpose: Returns the selected data structure, increments the dist_array indexes Input: dist_array: A dist-array data structure dist_ptr_index=dist_ptr_index: dist_ptr_index for the dist_array(modifed by this routine) dist_seg_index=dist_seg_index: dist_seg_index for the dist_array(modified by this routine) Output: data=data: The data structure idenfitied by the indexes Notes: $LastChangedBy: pcruce $ $LastChangedDate: 2013-07-12 13:17:02 -0700 (Fri, 12 Jul 2013) $ $LastChangedRevision: 12674 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_data.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_data.pro)
Procedure: thm_pgs_dist_array_start Purpose: Identifies the start indexes for the dist_array data structure Input: dist_array: A dist-array data structure time_idx: A 1-d array of indexes into a time array Output: dist_ptr_idx: The index to the starting mode for the requested time range dist_seg_idx: The index to the first sample of the mode for the requested time range Notes: $LastChangedBy: pcruce $ $LastChangedDate: 2013-07-12 11:09:50 -0700 (Fri, 12 Jul 2013) $ $LastChangedRevision: 12671 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_start.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_start.pro)
Procedure: thm_pgs_dist_array_times Purpose: Concatenates a 1-d array of times from a thm_part_dist_array structure Input: dist_array: A dist-array data structure Output: times: An array of times Notes: $LastChangedBy: pcruce $ $LastChangedDate: 2013-07-12 11:09:50 -0700 (Fri, 12 Jul 2013) $ $LastChangedRevision: 12671 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_times.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_dist_array_times.pro)
Procedure:
thm_pgs_expand_yaxis
Purpose:
Convert single-dimension y axes from new spectrogram code
to two dimensions to match the output from the old code.
Calling Sequence
thm_pgs_expand_axis, tplotnames
Inputs:
tplotnames: list of tplot variables whose y axes may need
expansion to two dimensions
Outputs:
none
Keywords:
none
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2013-09-11 16:40:34 -0700 (Wed, 11 Sep 2013) $
$LastChangedRevision: 13023 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_expand_yaxis.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_expand_yaxis.pro)
Procedure:
thm_pgs_get_datatype
Purpose:
Returns probe and datatype designations from standard particle distribution pointer array.
Arguments:
dist_array: pointer(s) to particle structure arrays
Output Keywords:
probe: String denoting probe
datatype: String denoting particle data type (e.g. peif, pseb)
instrument: String denoting instrument ('esa', 'sst', 'combined')
History:
2015-08-24 - Allow to work on non-THEMIS data for testing with MMS
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2015-08-24 11:31:21 -0700 (Mon, 24 Aug 2015) $
$LastChangedRevision: 18591 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_get_datatype.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_get_datatype.pro)
PROCEDURE: thm_pgs_make_fac PURPOSE: Generate the field aligned coordinate transformation matrix Specifically #1 guarantee mag_data is in dsl and pos data is in gei #2 guarantee that time grid matches particle data Inputs(required): Outputs: Keywords: Notes: Needs to be vectorized because thm_cotrans is waaaay too slow if fed single vectors at a time If an error occurs fac_output will be undfined on return $LastChangedBy: aaflores $ $LastChangedDate: 2016-02-10 19:03:17 -0800 (Wed, 10 Feb 2016) $ $LastChangedRevision: 19949 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_fac.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_fac.pro)
Procedure:
thm_pgs_make_tplot
Purpose:
Create tplot variable with standard spectrogram settings.
Input:
name: name of new tplot variable to create
x: x axis (time)
y: y axis
z: z axis (data)
_extra: Any other keywords used will be passed to tplot and
set in the dlimits of the new variable.
(e.g. ylog=1 to set logarithmic y axis)
Output:
Creates a tplot variable.
tplotnames=tplotnames : Concatenates the name of the new variable onto tnames argument
Notes:
$LastChangedBy: egrimes $
$LastChangedDate: 2017-04-05 13:48:59 -0700 (Wed, 05 Apr 2017) $
$LastChangedRevision: 23120 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_tplot.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_make_tplot.pro)
Procedure: thm_pgs_moments Purpose: Calculates moments from a simplified particle data structure. Arguments: data: single sanitized data structure Input Keywords: get_error: Flag indicating that error esitmates (sigma) should be returned mag_data: Optional array containing magnetic field vectors for all time samples scpot_data: Optional array containing spacecraft potential data for all time samples index: Index into mag_data/scpot_data specifying which sample to use Output Keywords: moments: Structure output from moments_3d containing the data. sigma: Structure output from moments_3d containing error estimates. Notes: $LastChangedBy: jimm $ $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $ $LastChangedRevision: 24078 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments.pro)
Procedure:
thm_pgs_moments_tplot
Purpose:
Creates tplot variables from moments structures
Arguments:
moments: Array of moments structures returned from moments_3d
Keywords:
get_error: Flag indicating that the current moment structure
contains error estimates.
prefix: Tplot variable name prefix (e.g. 'tha_peif_')
suffix: Tplot variable name suffix
tplotnames: Array of tplot variable names created by the parent
routine. Any tplot variables created in this routine
should have their names appended to this array.
coord: if set, then velocity, flux, pressure tensor and momentum
flux tensor variables are created for the
input coordinate system, in addition to the DSL variables
Notes:
Much of this code was copied from thm_part_moments.pro
$LastChangedBy: jimm $
$LastChangedDate: 2019-02-19 11:17:18 -0800 (Tue, 19 Feb 2019) $
$LastChangedRevision: 26643 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments_tplot.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_moments_tplot.pro)
PROCEDURE: thm_pgs_set_spec_zlimits PURPOSE: Helper routine for thm_part_products Sets zlimits to good default minimums for spectrograms Inputs(required): in_name: name or names of the tplot variable to be modified units: of in_name(s) lower-case string Outputs: None, just mutates in_name Notes: Uses a fixed formula for limits. They vary a little bit for different possible unit selections $LastChangedBy: pcruce $ $LastChangedDate: 2013-09-16 10:56:21 -0700 (Mon, 16 Sep 2013) $ $LastChangedRevision: 13039 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/thm_part_products/thm_pgs_set_spec_zlimits.pro $
(See projects/themis/spacecraft/particles/thm_part_products/thm_pgs_set_spec_zlimits.pro)