This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Jun 12 10:49:46 2024.
Procedure:
mms_get_hpca_dist
Purpose:
Returns pseudo-3D particle data structures containing mms hpca data
for use with spd_slice2d.
Calling Sequence:
data = mms_get_hpca_dist(tname [,index] [,trange=trange] [,/times] [,/structure]
[,probe=probe] [,species=species] [,units=units] )
Input:
tname: Tplot variable containing the desired data.
single_time: Return a single time nearest to the time specified by single_time (supersedes trange and index)
index: Index of time samples to return (supersedes trange)
trange: Two element time range to constrain the requested data
times: Flag to return full array of time samples
structure: Flag to return a structure array instead of a pointer.
probe: Specify probe if not present or correct in input_name
species: Specify species if not present or correct in input_name
units: Specify units of input data if not present or correct in input_name
Output:
return value: pointer to array of pseudo 3D particle distribution structures
or 0 in case of error
Notes:
The HPCA data is required to be at the center of the measurement interval for this routine
to work properly; be sure to use the keyword: /center_measurement when calling mms_load_hpca
Still a work in progress; report bugs to egrimes@igpp.ucla.edu
$LastChangedBy: egrimes $
$LastChangedDate: 2020-11-12 13:32:47 -0800 (Thu, 12 Nov 2020) $
$LastChangedRevision: 29351 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_get_hpca_dist.pro $
(See projects/mms/hpca/mms_get_hpca_dist.pro)
Purpose: Returns structure containing hpca look directions, energies, and other info. This is primarily for testing of hpca distribution slices; it may change or disappear. Notes: Angles are in degrees. Elevations are in colatitude. Values were copied from hpca manual 20150817_0. $LastChangedBy: egrimes $ $LastChangedDate: 2016-01-29 15:22:13 -0800 (Fri, 29 Jan 2016) $ $LastChangedRevision: 19853 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_get_hpca_info.pro $
(See projects/mms/hpca/mms_get_hpca_info.pro)
PROCEDURE:
mms_hpca_ang_ang
PURPOSE:
Create angle-angle and angle-energy plots of HPCA distribution functions
INPUT:
time: time of interest
KEYWORDS:
species: HPCA species; e.g., hplus, oplus, etc (default: hplus)
probe: MMS spacecraft # (default: '1')
level: data level (default: 'l2')
data_rate: instrument data rate (default: brst)
energy_range: energy range of figures, in eV (default: full energy range)
center_measurement: center the HPCA measurements (default: enabled)
flux: plot the flux instead of the distribution function
png: save the plots as PNG files
postscript: save the plots as PS files
filename_suffix: append a suffix to the plot file names
NOTES:
warning: the data plotted by this routine are not omni-directional, i.e. spin-averaged/spin-summed,
so the azimuthal angles will be limited to those in the sample closest to
the requested time
experimental, email questions to egrimes@igpp.ucla.edu
$LastChangedBy: egrimes $
$LastChangedDate: 2019-09-17 12:04:04 -0700 (Tue, 17 Sep 2019) $
$LastChangedRevision: 27763 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_ang_ang.pro $
(See projects/mms/hpca/mms_hpca_ang_ang.pro)
PROCEDURE:
mms_hpca_calc_anodes
PURPOSE:
Sums/averages over anodes (or a given field of view) for HPCA ion data
KEYWORDS:
tplotnames: names of tplot variables to pick the HPCA
ion spectra out of; will use tnames() if this is not set
fov: field of view to sum/avg over
anodes: anodes to sum/avg over (can not be set at the same time as fov)
probe: MMS probe #
suffix: if a suffix is used in the call to mms_load_hpca, you must specify it here
EXAMPLE:
See mms_load_hpca_crib for usage examples
NOTES:
This routine sums over anodes (or FoV) for products in units of counts, e.g.,
*_count_rate, *_RF_corrected, *_bkgd_corrected, *_norm_counts
and averages products in units of flux:
*_flux
$LastChangedBy: egrimes $
$LastChangedDate: 2017-08-08 13:01:28 -0700 (Tue, 08 Aug 2017) $
$LastChangedRevision: 23767 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_calc_anodes.pro $
(See projects/mms/hpca/mms_hpca_calc_anodes.pro)
PROCEDURE:
mms_hpca_energies
PURPOSE:
Returns the hard-coded energy table; this is only used when
the energy table is missing from the CDF (either not there, or
all 0s)
$LastChangedBy: egrimes $
$LastChangedDate: 2016-04-13 15:23:28 -0700 (Wed, 13 Apr 2016) $
$LastChangedRevision: 20808 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_energies.pro $
(See projects/mms/hpca/mms_hpca_energies.pro)
Function:
mms_hpca_mode
Input:
brst_in: hpca burst data tplot variable
srvy_in: hpca survey data tplot variable
Output:
mode_out: creates a tplot variable with the name data_in + _mode
(with brst or srvy stripped off, containing flags
for each mode (e.q. data.x=brst_srvy time and
data.y:[brst_flag, srvy_flag].
Returns the name of the tplot variable it created.
NOTE: This only handles burst and survey type hpca data.
When fast data becomes available this will need
to be modified to handle that mode as well.
$LastChangedBy: egrimes $
$LastChangedDate: 2016-04-27 12:47:46 -0700 (Wed, 27 Apr 2016) $
$LastChangedRevision: 20937 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_mode.pro $
(See projects/mms/hpca/mms_hpca_mode.pro)
PROCEDURE:
mms_hpca_set_metadata
PURPOSE:
Sets metadata for HPCA tplot variables
KEYWORDS:
prefix: prefix for names of the tplot variables, typically 'mms#' where # is the S/C number
fov: field of view of the summed/averaged counts/fluxes
anodes: anodes of the summed/averaged counts/fluxes (shouldn't be used with fov keyword)
suffix: suffix of the summed/averaged counts/fluxes
$LastChangedBy: egrimes $
$LastChangedDate: 2019-01-08 12:02:58 -0800 (Tue, 08 Jan 2019) $
$LastChangedRevision: 26437 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_set_metadata.pro $
(See projects/mms/hpca/mms_hpca_set_metadata.pro)
PROCEDURE:
mms_hpca_spin_sum
PURPOSE:
Calculates spin-summed fluxes and counts for the HPCA instrument
KEYWORDS:
probe: observatory # to spin sum the spectra for (e.g., probe='1')
datatype: type of data to spin sum; potential options include:
flux, count_rate, RF_corrected, bkgd_corrected, norm_counts
fov: field of view of the spectra created with mms_hpca_calc_anodes;
default is [0, 360]
tplotnames: list of tplot variable names already loaded; should
include the HPCA spectra variables you would like to spin-sum;
if not provided, uses tnames() by default.
avg: average instead of sum
suffix: suffix that was used when the data were loaded; if you provide a suffix
to mms_load_hpca and mms_hpca_calc_anodes, you'll need to apply a suffix
here as well
OUTPUT:
Creates tplot variables containing the spin summed fluxes and counts;
the new variables have the suffix "_spin" appended to their names
NOTES:
Must have HPCA data loaded and summed/averaged over the FoV (or anodes); i.e.,
you must have already called mms_load_hpca and mms_hpca_calc_anodes prior to
calling this routine.
$LastChangedBy: egrimes $
$LastChangedDate: 2021-03-02 09:40:53 -0800 (Tue, 02 Mar 2021) $
$LastChangedRevision: 29721 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_hpca_spin_sum.pro $
(See projects/mms/hpca/mms_hpca_spin_sum.pro)
PROCEDURE:
mms_load_hpca
PURPOSE:
Load data from the MMS Hot Plasma Composition Analyzer (HPCA)
KEYWORDS:
trange: time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
probes: list of probes, valid values for MMS probes are ['1','2','3','4'].
If no probe is specified the default is '1'
level: indicates level of data processing. levels include 'l2', 'l1b', 'sitl'.
the default if no level is specified is 'L2'.
datatype: data types include (note that not all levels have all datatypes):
L2: ['ion', 'moments']
sitl, l1b: ['combined', 'bkgd_corr', 'count_rate', 'flux', 'moments', 'rf_corr', 'vel_dist'].
if no value is given the default is 'moments'.
data_rate: instrument data rates include 'brst' and 'srvy'; the default is 'srvy'.
local_data_dir: local directory to store the CDF files
varformat: format of the variable names in the CDF to load
source: specifies a different system variable. By default the MMS system
variable is !mms
get_support_data: load support data (defined by VAR_TYPE="support_data" in the CDF)
tplotnames: returns a list of the names of the tplot variables loaded by the load routine
no_color_setup: don't setup graphics configuration; this keyword is required when you're using this
load routine from a terminal without an X server running
time_clip: clip the data to the requested time range; note that if you do not use this
keyword you may load a longer time range than requested
no_update: set this flag to preserve the original data. if not set and newer data is
found, the existing data will be overwritten
suffix: appends a suffix to the end of the tplot variable names
cdf_filenames: this keyword returns the names of the CDF files used when loading the data
cdf_version: specify a specific CDF version # to load (e.g., cdf_version='4.3.0')
latest_version: only grab the latest CDF version in the requested time interval
(e.g., /latest_version)
major_version: only open the latest major CDF version (e.g., X in vX.Y.Z) in the requested time interval
min_version: specify a minimum CDF version # to load
spdf: grab the data from the SPDF instead of the LASP SDC (only works for public data)
center_measurement: set this keyword to shift the data to the center of the measurement interval
using the DELTA_PLUS_VAR/DELTA_MINUS_VAR attributes
available: returns a list of files available at the SDC for the requested parameters
this is useful for finding which files would be downloaded (along with their sizes) if
you didn't specify this keyword (also outputs total download size)
versions: this keyword returns the version #s of the CDF files used when loading the data
always_prompt: set this keyword to always prompt for the user's username and password;
useful if you accidently save an incorrect password, or if your SDC password has changed
tt2000: flag for preserving TT2000 timestamps found in CDF files (note that many routines in
SPEDAS (e.g., tplot.pro) do not currently support these timestamps)
disable_mem_usage: disable memory usage checks and warnings
EXAMPLE:
Simple HPCA example:
MMS> mms_load_hpca, probes='1', trange=['2015-12-15', '2015-12-16'], datatype='ion'
MMS> mms_hpca_calc_anodes, fov=[0, 360] ; sum over the full field of view (FoV)
MMS> tplot, 'mms1_hpca_hplus_flux_elev_0-360' ; plot the H+ spectra (full FoV)
MMS> mms_hpca_spin_sum, probe='1'
MMS> tplot, ['mms1_hpca_hplus_flux_elev_0-360_spin', 'mms1_hpca_hplus_flux_elev_0-360']
See crib sheets: mms_load_hpca_crib, mms_load_hpca_burst_crib, and mms_load_hpca_crib_qlplots
for more usage examples
NOTES:
The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC
The HPCA Data Products Guide can be found at:
https://lasp.colorado.edu/galaxy/display/mms/HPCA+Data+Products+Guide
Have questions regarding this load routine, or its usage?
https://groups.google.com/forum/#!forum/spedas
When loading HPCA energy spectra with this routine, all of the data are loaded in
initially. To plot a meaningful spectra, the user must call mms_hpca_calc_anodes
to sum/average the data over the look directions for the instrument. This will append
the field of view (or anodes) used in the calculation to the name of the tplot variable.
$LastChangedBy: egrimes $
$LastChangedDate: 2019-07-10 14:19:15 -0700 (Wed, 10 Jul 2019) $
$LastChangedRevision: 27435 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_load_hpca.pro $
(See projects/mms/hpca/mms_load_hpca.pro)
PROCEDURE:
mms_load_hpca_fix_dist
PURPOSE:
Replace supplementary fields in 3D distribution variables with actual
values from supplementary tplot variables (theta).
NOTE:
Expect this routine to be made obsolete after the CDFs are updated
$LastChangedBy: egrimes $
$LastChangedDate: 2018-01-16 09:13:41 -0800 (Tue, 16 Jan 2018) $
$LastChangedRevision: 24519 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/mms/hpca/mms_load_hpca_fix_dist.pro $
(See projects/mms/hpca/mms_load_hpca_fix_dist.pro)