This page was created by the IDL library routine
mk_html_help2.
Last modified: Tue Apr 3 11:50:06 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_00/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' 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: 2017-10-12 09:09:00 -0700 (Thu, 12 Oct 2017) $
$LastChangedRevision: 24145 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/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)
PROCEDURE:
mms_part_getpad
PURPOSE:
Quickly generate pitch angle spectrograms from multipad output from mms_part_getspec/mms_part_products_new
NOTES:
still a work in progress
$LastChangedBy: egrimes $
$LastChangedDate: 2018-03-20 13:51:47 -0700 (Tue, 20 Mar 2018) $
$LastChangedRevision: 24919 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/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.) - see warning at the top of mms_part_products before using this!
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)
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
$LastChangedBy: egrimes $
$LastChangedDate: 2018-03-20 10:14:29 -0700 (Tue, 20 Mar 2018) $
$LastChangedRevision: 24914 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/projects/mms/particles/mms_part_getspec.pro $
(See projects/mms/particles/mms_part_getspec.pro)
Procedure:
mms_part_products
Purpose:
Generate spectra and moments from 3D MMS particle data.
-----------------------------------------------------------------------------------------
| !!!!!! words of caution <------ by egrimes, 4/7/2016: |
| While you can use mms_part_products to generate particle moments for FPI from |
| the distributions, these calculations are currently missing several important |
| components, including photoelectron removal and S/C potential corrections. |
| The official moments released by the team include these, and are the scientific |
| products you should use in your analysis; see mms_load_fpi_crib to see how to load |
| the FPI moments released by the team (des-moms, dis-moms datatypes) |
-----------------------------------------------------------------------------------------
Data Products:
'energy' - energy spectrogram
'phi' - azimuthal spectrogram
'theta' - latitudinal spectrogram
'gyro' - gyrophase spectrogram
'pa' - pitch angle spectrogram
'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: Secify 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 velocity vector from distribution before
calculation of field aligned angular spectra.
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!
$LastChangedBy: egrimes $
$LastChangedDate: 2018-04-03 11:20:00 -0700 (Tue, 03 Apr 2018) $
$LastChangedRevision: 24980 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/projects/mms/particles/mms_part_products.pro $
(See projects/mms/particles/mms_part_products.pro)
Procedure:
mms_part_products
Purpose:
Generate spectra and moments from 3D MMS particle data.
-----------------------------------------------------------------------------------------
| !!!!!! words of caution <------ by egrimes, 4/7/2016: |
| While you can use mms_part_products to generate particle moments for FPI from |
| the distributions, these calculations are currently missing several important |
| components, including photoelectron removal and S/C potential corrections. |
| The official moments released by the team include these, and are the scientific |
| products you should use in your analysis; see mms_load_fpi_crib to see how to load |
| the FPI moments released by the team (des-moms, dis-moms datatypes) |
-----------------------------------------------------------------------------------------
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: Secify 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!
$LastChangedBy: egrimes $
$LastChangedDate: 2018-04-03 11:20:00 -0700 (Tue, 03 Apr 2018) $
$LastChangedRevision: 24980 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/projects/mms/particles/mms_part_products_new.pro $
(See projects/mms/particles/mms_part_products_new.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_00/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: 2016-11-03 09:51:41 -0700 (Thu, 03 Nov 2016) $
$LastChangedRevision: 22268 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/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: 2017-06-23 08:24:47 -0700 (Fri, 23 Jun 2017) $ $LastChangedRevision: 23503 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/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: 2017-03-10 08:58:08 -0800 (Fri, 10 Mar 2017) $ $LastChangedRevision: 22935 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/projects/mms/particles/mms_pgs_make_fac.pro $
(See projects/mms/particles/mms_pgs_make_fac.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_00/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_00/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_00/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_00/projects/mms/particles/mms_pgs_split_hpca.pro $
(See projects/mms/particles/mms_pgs_split_hpca.pro)
Procedure: moka_eg_pgs_make_pad Purpose: Creates a multi-dimensional tplot variable (pitch angle distribution at each energy) called from mms_part_products_new History: Created on 2017-01-01 by moka Forked on 2018-03-14 by egrimes, with a few big changes: - removed bulk velocity subtraction (now occurs in mms_part_products_new, before getting to this routine) - updated energy/angle bin search to use value_locate - commented out angle padding $LastChangedBy: egrimes $ $LastChangedDate: 2018-03-20 10:06:44 -0700 (Tue, 20 Mar 2018) $ $LastChangedRevision: 24911 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_3_00/projects/mms/particles/moka_eg_pgs_make_pad.pro $
(See projects/mms/particles/moka_eg_pgs_make_pad.pro)