This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
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: pcruce $
$LastChangedDate: 2016-05-12 18:31:01 -0700 (Thu, 12 May 2016) $
$LastChangedRevision: 21074 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/combined/thm_cmb_clean_esa.pro $
(See projects/themis/spacecraft/particles/combined/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
sst_data_mask: The name of a tplot variable containing a 1-dimensional, 0-1 array indicating SST samples to exclude(0=exclude,1=include),
If values don't match the times of particle data, they'll be nearest neighbor interpolated to match.
Output:
none, modifies input
Notes:
Further unit conversions will not be possible after sanitation
due to the loss of some support quantities.
$LastChangedBy: pcruce $
$LastChangedDate: 2016-07-18 12:21:54 -0700 (Mon, 18 Jul 2016) $
$LastChangedRevision: 21480 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/combined/thm_cmb_clean_sst.pro $
(See projects/themis/spacecraft/particles/combined/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: jimmpc1 $ $LastChangedDate: 2017-10-09 11:19:52 -0700 (Mon, 09 Oct 2017) $ $LastChangedRevision: 24129 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/combined/thm_convert_cmb_units.pro $
(See projects/themis/spacecraft/particles/combined/thm_convert_cmb_units.pro)
Procedure:
thm_part_combine.pro
Purpose:
Create combined particle distributions from ESA and SST data.
This distributions acts as a new data type and can be passed
to most THEMIS/SPEDAS particle product routines to create
combined ESA/SST plots.
Combined distributions are created in three steps:
a) Linear time interpolation
-time samples are matched by linearly interpolating the
data set with lower time resolution to match the other
b) Linear spherical interpolation
-both data sets are interpolated onto the same angular grid
c) Energy gap interpolation
-once all times/angles match the gap between the
ESA and SST energy ranges is filled in with a logarithmic
linear interpolation (log(flux) vs log(energy))
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')
esa_dist: Pass in manually loaded ESA particle data (see thm_part_dist_array)
Must be used with SST_DIST
sst_dist: Pass in manually loaded SST particle data (see thm_part_dist_array)
Must be used with ESA_DIST
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 energy interpolation mid-point targets for all output bins above the ESA.(gap & SST)
If unspecified, a hardcoded set of defaults is used.
sst_sun_bins: Array list of SST bins to mask (bin indices) (int).
sst_min_energy: Set to minimum energy to toss bins that are having problems from instrument degradation. (float)
esa_max_energy: Set to maximum energy to toss bins that are having problems from instrument contamination.(float)
set_counts: Set all data to this # of counts before interpolation (for comparison).
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)
get_sun_direction: Load sun direction with particle data (for 2D slices)
esa_bgnd_advanced: Apply advanced ESA background subtraction
Must call thm_load_esa_bkg first to calculate background
Disables default anode-based background removal
extrapolate_esa: Flag to extrapolate from ESA data where no valid SST data exists
instead of throwing error. Not recommended - use with caution!
remove_one_count: removes all bins that are less than one count, suggestion from heli hietala(heli@igpp.ucla.edu)
sst_data_mask: The name of a tplot variable containing a 1-dimensional, 0-1 array indicating SST samples to exclude(0=exclude,1=include),
If values don't match the times of particle data, they'll be nearest neighbor interpolated to match.
get_error: if set, interpolates scaling factor needed for error propagation
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. No calibrations or contamination
removal are applied for reduced data. Other contamination
options may be passed through to override the defaults, see SST contamination
removal crib for options.
Note that the GET_ERROR keyword must be set if the user wants to
propagate errors through to the thm_part_moments routine. This is
not done automatically, because it doubles the interpolation time
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 is assumed as the data is replaced with interpolated versions.
$LastChangedBy: jimmpc1 $
$LastChangedDate: 2017-10-05 10:26:24 -0700 (Thu, 05 Oct 2017) $
$LastChangedRevision: 24117 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/combined/thm_part_combine.pro $
(See projects/themis/spacecraft/particles/combined/thm_part_combine.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
get_error: if set, interpolates scaling factor needed for error propagation
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/combined/thm_part_energy_interp.pro)
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. Inputs: esa_dist: esa distribution array sst_dist: sst distribution array sst_only: flag to only return SST + new energies probe: probe designation esa_datatype: esa data type, e.g. 'peif' sst_datatype: sst data type, e.g. 'psif' Outputs: out_dist: combined distributions, fresh and ready for unit conversion 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/combined/thm_part_merge_dists.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
get_error: if set, interpolates scaling factor needed for error propagation
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/combined/thm_part_sphere_interp.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: jimmpc1 $ $LastChangedDate: 2017-10-23 14:17:30 -0700 (Mon, 23 Oct 2017) $ $LastChangedRevision: 24204 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/combined/thm_part_time_interpolate.pro $
(See projects/themis/spacecraft/particles/combined/thm_part_time_interpolate.pro)