This page was created by the IDL library routine
mk_html_help2.
Last modified: Tue Oct 23 09:41:31 2018.
Procedure: mms_convert_flux_unit Purpose: Perform unit conversions for MMS particle data structures Supported Units: flux - # / (cm^2 * s * sr * eV) eflux - eV / (cm^2 * s * sr * eV) df_cm - s^3 / cm^6 df_km - s^3 / km^6 'psd' is treated as 'df_km' 'df' is no longer supported by these routines due to inconsistencies with THEMIS/other missions in SPEDAS Calling Sequence: mms_convert_flux_units, dist, units=units, output=output Arguments/Keywords: dist: Single MMS 3D particle data structure units: String specifying output units output: Set to named variable that will hold converted structure $LastChangedBy: egrimes $ $LastChangedDate: 2018-04-03 11:28:25 -0700 (Tue, 03 Apr 2018) $ $LastChangedRevision: 24982 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_convert_flux_units.pro $
(See projects/mms/particles/mms_convert_flux_units.pro)
Procedure:
mms_get_dist
Purpose:
Retrieve particle distribution structures/pointers from data loaded
into tplot.
Calling Sequence:
data = mms_get_dist( input_name [,trange=trange] [/times] [/structure]
[,probe=probe] [,species=species]
[,instrument=instrument] [,units=units] )
Input:
input_name: Name of tplot variable containing particle data (must be original name)
single_time: Return a single time nearest to the time specified by single_time (supersedes trange and index)
trange: Optional two element time range
times: Flag to return array of full distribution sample times
structure: Flag to return structures instead of pointer to structures
probe: specify probe if not present or correct in input_name
species: specify particle species if not present or correct in input_name
e.g. 'hplus', 'i', 'e'
instrument: specify instrument if not present or correct in input_name
'hpca' or 'fpi'
units: (HPCA only) specify units of input data if not present or correct in input_name
e.g. 'flux', 'df_cm' (note: 'df_km' is in km, 'df_cm' is in cm)
Output:
return value: Pointer to structure array or structure array if /structure used.
Array of times if /times is used
0 for any error case
$LastChangedBy: egrimes $
$LastChangedDate: 2018-04-03 12:46:57 -0700 (Tue, 03 Apr 2018) $
$LastChangedRevision: 24987 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_get_dist.pro $
(See projects/mms/particles/mms_get_dist.pro)
Procedure: mms_part_conv_units Purpose: simple wrapper around mms_convert_flux_units that can be used as the 'units_procedure' in our 3d particle data structure $LastChangedBy: egrimes $ $LastChangedDate: 2017-03-10 08:56:27 -0800 (Fri, 10 Mar 2017) $ $LastChangedRevision: 22934 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_convert_flux_units.pro $
(See projects/mms/particles/mms_part_conv_units.pro)
FUNCTION:
mms_part_des_photoelectrons
PURPOSE:
Loads and returns the FPI/DES photoelectron model based on stepper ID
INPUT:
dist_var: DES distribution data
NOTES:
see: https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518
$LastChangedBy: egrimes $
$LastChangedDate: 2018-05-15 17:19:32 -0700 (Tue, 15 May 2018) $
$LastChangedRevision: 25225 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_des_photoelectrons.pro $
(See projects/mms/particles/mms_part_des_photoelectrons.pro)
PROCEDURE:
mms_part_getpad
PURPOSE:
Quickly generate pitch angle spectrograms from multipad output from mms_part_getspec/mms_part_products
NOTES:
still a work in progress
$LastChangedBy: egrimes $
$LastChangedDate: 2018-09-20 15:04:07 -0700 (Thu, 20 Sep 2018) $
$LastChangedRevision: 25838 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_getpad.pro $
(See projects/mms/particles/mms_part_getpad.pro)
Procedure:
mms_part_getspec
Purpose:
This is a wrapper around mms_part_products that loads required
support data (if not already loaded), and optionally creates
angular spectrograms with B-field and S/C ram directions specified
using symbols
Keywords:
probes: array of probes
instrument: fpi or hpca
species: depends on instrument:
FPI: 'e' for electrons, 'i' for ions
HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
outputs: list of requested output types,
'energy' - energy spectrogram
'phi' - azimuthal spectrogram
'theta' - latitudinal spectrogram
'gyro' - gyrophase spectrogram
'pa' - pitch angle spectrogram
'multipad' - pitch angle spectrogram at every energy
(multi-dimensional PAD variable, to be used by mms_part_getpad)
'moments' - distribution moments (density, velocity, etc.)
add_bfield_dir: add B-field direction (+, -) to the angular spectrograms (phi, theta)
add_ram_dir: add S/C ram direction (X) to the angular spectrograms (phi, theta)
dir_interval: number of seconds between B-field and S/C ram direction symbols on angular spectrogram plots
subtract_bulk: subtract the bulk velocity prior to doing the calculations
subtract_error: subtract the distribution error prior to doing the calculations (FPI only, currently)
subtract_spintone: subtract the spin-tone from the velocity vector prior to bulk velocity subtraction (FPI versions 3.2 and later only)
photoelectron_corrections: *experimental* photoelectron corrections for DES; enabled by default for DES moments; you can disable with photoelectron_corrections=0
The following are found by default for the requested instrument/probe/data_rate; use these keywords
to override the defaults:
mag_name: Use a different tplot variable containing magnetic field data for moments and FAC transformations
pos_name: Use a different tplot variable containing spacecraft position for FAC transformations
vel_name: Use a different tplot variable containing velocity data in km/s when subtracting the bulk velocity
Notes:
Updated to automatically center HPCA measurements if not specified already, 18Oct2017
Updated to automatically correct FPI-DES moments for photoelectrons, 20Sept2018
FPI-DES internal photoelectrons are corrected using Dan Gershman's photoelectron model; see the following for details:
Spacecraft and Instrument Photoelectrons Measured by the Dual Electron Spectrometers on MMS
https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518
Spacecraft photoelectrons are corrected in moments_3d
$LastChangedBy: egrimes $
$LastChangedDate: 2018-09-25 12:35:45 -0700 (Tue, 25 Sep 2018) $
$LastChangedRevision: 25862 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_getspec.pro $
(See projects/mms/particles/mms_part_getspec.pro)
Procedure:
mms_part_isee3d
Purpose:
This is a wrapper around isee_3d that loads required
support data and plots the distribution
Keywords:
probe: MMS s/c # to create the 2D slice for
instrument: fpi or hpca
species: depends on instrument:
FPI: 'e' for electrons, 'i' for ions
HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
level: level of the data you'd like to plot
data_rate: data rate of the distribution data you'd like to plot
trange: two-element time range over which data will be averaged (optional, ignored if 'time' is specified)
spdf: load the data from the SPDF instead of the LASP SDC
Notes:
This routine always centers the distribution/moments data
$LastChangedBy: egrimes $
$LastChangedDate: 2018-06-29 10:38:01 -0700 (Fri, 29 Jun 2018) $
$LastChangedRevision: 25421 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_isee3d.pro $
(See projects/mms/particles/mms_part_isee3d.pro)
Procedure:
mms_part_products
Purpose:
Generate spectra and moments from 3D MMS particle data.
Data Products:
'energy' - energy spectrogram
'phi' - azimuthal spectrogram
'theta' - latitudinal spectrogram
'gyro' - gyrophase spectrogram
'pa' - pitch angle spectrogram
'multipad' - pitch angle spectrogram at each energy (multi-dimensional tplot variable,
you'll need to use mms_part_getpad to generate PADs at various energies)
'moments' - distribution moments (density, velocity, etc.)
Calling Sequence:
mms_part_products, tplot_name [,trange=trange] [outputs=outputs] ...
Example Usage:
-energy, phi, and theta spectrograms
mms_part_products, 'mms2_des_dist_brst', outputs='phi theta energy'
-field aligned spectrograms, limited time range
mms_part_products, 'mms2_des_dist_brst', output='pa gyro', $
pos_name = 'mms2_defeph_pos', $
mag_name = 'mms2_fgm_bvec'
-limit range of input data (gyro and pa limits do not affect phi/theta spectra)
mms_part_products, 'mms2_des_dist_brst', output = 'energy pitch', $
energy = [15,1e5], $ ;eV
pitch = [45,135]
Arguments:
tplot_name: Name of the tplot variable containing MMS 3D particle distribution data
Input Keywords:
trange: Two element time range [start,end]
outputs: List of requested outputs, array or space separated list, default='energy'
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
vel_name: Tplot variable containing velocity data in km/s for use with /subtract_bulk
units: Specify units of output variables. Must be 'eflux' to calculate moments.
'flux' - # / (cm^2 * s * sr * eV)
'eflux' - eV / (cm^2 * s * sr * eV) <default>
'df_cm' - s^3 / cm^6
'df_km' - s^3 / km^6
fac_type: Select the field aligned coordinate system variant.
Existing options: "phigeo,mphigeo, xgse"
regrid: Two element array specifying the resolution of the field-aligned data.
[n_gyro,n_pitch], default is [32,16]
no_regrid: (experimental) Skip regrid step when converting to field aligned coordinates.
suffix: Suffix to append to output tplot variable names
probe: Specify probe designation when it cannot be parsed from tplot_name
species: Specify species when it cannot be parsed from tplot_name
instrument: Specify instrument when it cannot be parsed from tplot_name
input_units: (HPCA only) Specify units of input data when they cannot be parsed from tplot_name
start_angle: Set a start angle for azimuthal spectrogram y axis
datagap: Setting for tplot variables, controls how long a gap must be before it is drawn.
(can also manually degap)
subtract_bulk: Flag to subtract bulk velocity (experimental)
display_object: Object allowing dprint to export output messages
Output Keywords:
tplotnames: List of tplot variables that were created
get_data_structures: Set to named variable to return structures directly when
generating field aligned outputs. This may considerably
slow the process!
error: Error status flag for calling routine, 1=error 0=success
Notes:
-See warning above in purpose description!
-FPI-DES photoelectrons are corrected using Dan Gershman's photoelectron model; see the following for details:
Spacecraft and Instrument Photoelectrons Measured by the Dual Electron Spectrometers on MMS
https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2017JA024518
-Note that there may still be slight differences between the PGS moments and the official moments released by the team.
The official moments released by the team are the scientific
products you should use in your analysis.
$LastChangedBy: egrimes $
$LastChangedDate: 2018-09-21 14:26:21 -0700 (Fri, 21 Sep 2018) $
$LastChangedRevision: 25851 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_products.pro $
(See projects/mms/particles/mms_part_products.pro)
Procedure:
mms_part_slice2d
Purpose:
This is a wrapper around spd_slice2d that loads required
support data, creates the slice and plots the slice
Keywords:
probe: MMS s/c # to create the 2D slice for
instrument: fpi or hpca
species: depends on instrument:
FPI: 'e' for electrons, 'i' for ions
HPCA: 'hplus' for H+, 'oplus' for O+, 'heplus' for He+, 'heplusplus', for He++
level: level of the data you'd like to plot
data_rate: data rate of the distribution data you'd like to plot
time: time of the 2D slice
trange: two-element time range over which data will be averaged (optional, ignored if 'time' is specified)
spdf: load the data from the SPDF instead of the LASP SDC
output: returns the computed slice
units: units of the slice (default is df_cm - other options include 'df_km', 'flux', 'eflux')
Notes:
This routine always centers the distribution/moments data
$LastChangedBy: egrimes $
$LastChangedDate: 2018-08-20 15:01:59 -0700 (Mon, 20 Aug 2018) $
$LastChangedRevision: 25670 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_part_slice2d.pro $
(See projects/mms/particles/mms_part_slice2d.pro)
Procedure: mms_pgs_clean_data Purpose: Sanitize mms FPI/HPCA data structures for use with mms_part_products. Excess fields will be removed and field names conformed to standard. Reforms energy by theta by phi to energy by angle Converts units Input: data_in: Single combined particle data structure Output: output: Sanitized output structure for use within mms_part_products. Notes: -not much should be happening here since the combined structures are already fairly pruned -use for fpi and hpca for now $LastChangedBy: egrimes $ $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $ $LastChangedRevision: 23532 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_clean_data.pro $
(See projects/mms/particles/mms_pgs_clean_data.pro)
Procedure:
mms_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
Input Keywords
mag_name: String specifying a tplot variable containing magnetic field data
sc_pot_name: String specifying a tplot variable containing spacecraft potential data
vel_name: String specifying a tplot variable containing velocity data in km/s
Output Keywords:
mag_out: Array of magnetic field vectors corresponding to TIMES
sc_pot_out: Array of spacecraft potential data corresponding to TIMES
vel_out: Array of velocity vectors corresponding to TIMES
Notes:
$LastChangedBy: egrimes $
$LastChangedDate: 2018-08-07 13:36:40 -0700 (Tue, 07 Aug 2018) $
$LastChangedRevision: 25597 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_clean_support.pro $
(See projects/mms/particles/mms_pgs_clean_support.pro)
Procedure: mms_pgs_make_e_spec Purpose: Builds energy spectrogram from simplified particle data structure. Input: data: single sanitized data structure Input/Output: spec: The spectrogram (ny x ntimes) yaxis: The y axis (ny OR ny x ntimes) -Each time this procedure runs it will concatenate the sample's data to the SPEC variable. -Both variables will be initialized if not set -The y axis will remain a single dimension until a change is detected in the data, at which point it will be expanded to two dimensions. Notes: $LastChangedBy: egrimes $ $LastChangedDate: 2018-04-24 16:23:53 -0700 (Tue, 24 Apr 2018) $ $LastChangedRevision: 25106 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_make_e_spec.pro $
(See projects/mms/particles/mms_pgs_make_e_spec.pro)
PROCEDURE: mms_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 mms_cotrans is waaaay too slow if fed single vectors at a time If an error occurs fac_output will be undefined on return $LastChangedBy: egrimes $ $LastChangedDate: 2018-07-02 15:28:15 -0700 (Mon, 02 Jul 2018) $ $LastChangedRevision: 25430 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_make_fac.pro $
(See projects/mms/particles/mms_pgs_make_fac.pro)
Procedure: mms_pgs_make_multipad_spec Purpose: Builds theta (latitudinal) spectrogram from simplified particle data structure. this is like mms_pgs_make_theta_spec, except it's per energy and this routine expects 'spec' to be sent already initialized Input: data: single sanitized data structure Input/Output: spec: The spectrogram (ntimes x n_energy x ny) yaxis: The y axis (ny OR ny x ntimes) colatitude: Flag to specify that data is in colatitude -Each time this procedure runs it will concatenate the sample's data to the SPEC variable. -Both variables will be initialized if not set -The y axis will remain a single dimension until a change is detected in the data, at which point it will be expanded to two dimensions. Notes: forked from mms_pgs_make_theta_spec by egrimes on 23 April 2018 $LastChangedBy: egrimes $ $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $ $LastChangedRevision: 23532 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/particles/mms_pgs_make_theta_spec.pro $
(See projects/mms/particles/mms_pgs_make_multipad_spec.pro)
Procedure: mms_pgs_make_phi_spec Purpose: Builds phi (longitudinal) spectrogram from simplified particle data structure. Input: data: single sanitized data structure Input/Output: spec: The spectrogram (ny x ntimes) yaxis: The y axis (ny OR ny x ntimes) -Each time this procedure runs it will concatenate the sample's data to the SPEC variable. -Both variables will be initialized if not set -The y axis will remain a single dimension until a change is detected in the data, at which point it will be expanded to two dimensions. Notes: $LastChangedBy: egrimes $ $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $ $LastChangedRevision: 23532 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_make_phi_spec.pro $
(See projects/mms/particles/mms_pgs_make_phi_spec.pro)
Procedure: mms_pgs_make_theta_spec Purpose: Builds theta (latitudinal) spectrogram from simplified particle data structure. Input: data: single sanitized data structure Input/Output: spec: The spectrogram (ny x ntimes) yaxis: The y axis (ny OR ny x ntimes) colatitude: Flag to specify that data is in colatitude -Each time this procedure runs it will concatenate the sample's data to the SPEC variable. -Both variables will be initialized if not set -The y axis will remain a single dimension until a change is detected in the data, at which point it will be expanded to two dimensions. Notes: $LastChangedBy: egrimes $ $LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $ $LastChangedRevision: 23532 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_make_theta_spec.pro $
(See projects/mms/particles/mms_pgs_make_theta_spec.pro)
Procedure:
mms_pgs_make_tplot
Purpose:
Create tplot variable with standard spectrogram settings.
Input:
name: name of new tplot variable to create
x: x axis (time)
v1: first dimension
v2: second dimension
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:
Forked from spd_pgs_make_tplot, on 3/13/2018, to support creating multi-dimensional tplot variables
in mms_part_products_new
$LastChangedBy: egrimes $
$LastChangedDate: 2018-03-20 10:00:31 -0700 (Tue, 20 Mar 2018) $
$LastChangedRevision: 24910 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_make_tplot.pro $
(See projects/mms/particles/mms_pgs_make_tplot.pro)
Procedure:
mms_pgs_split_hpca
Purpose:
Split hpca elevation bins so that dphi == dtheta.
Combined with updates to spectra generation code this should allow
the regrid step for FAC spectra to be skipped in mms_part_products.
Input:
data: Sanitized hpca data structure
Output:
output: New structure with theta bins split in two
(2x data points in angle dimension)
Notes:
$LastChangedBy: egrimes $
$LastChangedDate: 2017-06-30 07:36:07 -0700 (Fri, 30 Jun 2017) $
$LastChangedRevision: 23532 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_1/projects/mms/particles/mms_pgs_split_hpca.pro $
(See projects/mms/particles/mms_pgs_split_hpca.pro)