This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
PROCEDURE:
mms_fpi_ang_ang
PURPOSE:
Creates various plots directly from the
FPI distribution functions, including:
- angle-angle (azimuth vs zenith)
- angle-energy (azimuth and zenith vs energy)
- pitch angle - energy
INPUT:
time: exact time you'd like to see plotted
KEYWORDS:
all_energies: generate azimuth vs zenith plots at
all energies, one plot for each energy
probe: probe to plot
energy_range: energy range to include in the
angle-angle and angle-energy plots (default: 10-30000 eV)
data_rate: FPI data rate ('fast' or 'brst')
species: FPI species - 'e' for electrons or 'i' for ions (defaults to 'e')
subtract_bulk: subtract the bulk velocity prior to
creating the PA-energy figure
pa_en_units: units for the PA-energy figure (defaults to 'df_cm')
postscript: save the plots as postscript files (can't be set with /png)
png: save the plots as PNG files (can't be set with /postscript)
center_measurement: shift the data to the center of the
measurement interval
xsize: x-size of the figures (default: 550px)
ysize: y-size of the figures (default: 450px)
filename_suffix: suffix to append to the end of PNG/postscript file names
nocontours: disable pitch angle contours on the angle-angle plots
NOTES:
Bulk velocity subtraction (via the /subtract_bulk keyword) only
works for PA-energy figures (i.e., angle-angle and angle-energy plots
are created as the data exists in the data files)
$LastChangedBy: egrimes $
$LastChangedDate: 2019-09-17 12:04:17 -0700 (Tue, 17 Sep 2019) $
$LastChangedRevision: 27764 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_ang_ang.pro $
(See projects/mms/fpi/mms_fpi_ang_ang.pro)
PROCEDURE:
mms_fpi_burst_energies
PURPOSE:
Returns the energies for burst mode FPI spectra. This routine uses
the alternating energy tables set by the parity bit
NOTE:
Burst mode FPI data must be loaded prior to calling this function
$LastChangedBy: egrimes $
$LastChangedDate: 2016-02-24 14:52:46 -0800 (Wed, 24 Feb 2016) $
$LastChangedRevision: 20165 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_burst_energies.pro $
(See projects/mms/fpi/mms_fpi_burst_energies.pro)
Procedure:
mms_fpi_correct_photoelectrons
Purpose:
Returns 3D particle data structures containing MMS FPI
data for use with SPEDAS particle routines. This routine removes
DES photoelectrons from the distribution using Dan Gershman's model
prior to returning
Input:
tname: Tplot variable containing the desired data
Keywords:
scpot: tplot variable containing S/C potential data; loaded automatically if not otherwise specified
subtract_error: subtract the distErr (variable specified by the keyword: error)
data before returning; the error is subtracted prior to photoelectron removal
error: variable name of the disterr variable, e.g.:
'mms#_des_disterr_fast'
for fast survey electron data
$LastChangedBy: egrimes $
$LastChangedDate: 2019-03-01 10:50:14 -0800 (Fri, 01 Mar 2019) $
$LastChangedRevision: 26732 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_correct_photoelectrons.pro $
(See projects/mms/fpi/mms_fpi_correct_photoelectrons.pro)
PROCEDURE:
mms_fpi_dist_angles
PURPOSE:
Returns the azimuth/colatitude for FPI sky maps.
NOTE:
Angle values describe the instrument look directions.
This routine might be obsolete once the angles are added to the data CDFs.
$LastChangedBy: aaflores $
$LastChangedDate: 2016-09-02 17:52:09 -0700 (Fri, 02 Sep 2016) $
$LastChangedRevision: 21796 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_dist_angles.pro $
(See projects/mms/fpi/mms_fpi_dist_angles.pro)
PROCEDURE:
mms_fpi_fix_metadata
PURPOSE:
Helper routine for setting FPI metadata. Original metadata from L2 QL plots script
$LastChangedBy: egrimes $
$LastChangedDate: 2018-11-15 09:45:38 -0800 (Thu, 15 Nov 2018) $
$LastChangedRevision: 26125 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_fix_metadata.pro $
(See projects/mms/fpi/mms_fpi_fix_metadata.pro)
PROCEDURE:
mms_fpi_make_compressionlossbars
PURPOSE:
Make compressionloss flag bars
KEYWORDS:
tname: tplot variable name of dis or des compressionloss
lossy: the value for lossy compression (use this keyword only for special case)
EXAMPLES:
MMS> mms_fpi_make_compressionlossbars,'mms1_des_compressionloss_brst'
MMS> mms_fpi_make_compressionlossbars,'mms1_dis_compressionloss_brst'
FLAG:
0: Lossless compression
1: Lossy compression
In old files (v2.1.0 or older until the end of Phase 1A)
1: Lossless compression
3: Lossy compression
In cases when data had been lossy compressed, some artifacts may appear in the data due to the compression.
Since all of fast survey data are lossy compressed, it is not nesessary to make this bar for fast survey data.
Original by Naritoshi Kitamura
$LastChangedBy: egrimes $
$LastChangedDate: 2016-08-30 07:29:09 -0700 (Tue, 30 Aug 2016) $
$LastChangedRevision: 21768 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_make_compressionlossbars.pro $
(See projects/mms/fpi/mms_fpi_make_compressionlossbars.pro)
PROCEDURE:
mms_fpi_make_errorflagbars
PURPOSE:
Make error flag bars
For DES/DIS moments
tname+'_flagbars_full': Detailed flag bars (all bars)
tname+'_flagbars' : Standard flag bars (4 bars)
tname+'_flagbars_mini': Smallest flag bar (1 bars)
For DES/DIS distribution function
tname+'_flagbars_dist': Standard flag bars (2 bars)
INPUT:
tname: tplot variable name of dis or des errorflag
KEYWORDS:
level: level of the data to create the errorflags bar for
(default is l2 - this only needs to be set for QL data)
EXAMPLES:
MMS> mms_fpi_make_errorflagbars,'mms1_des_errorflags_fast'
MMS> mms_fpi_make_errorflagbars,'mms1_dis_errorflags_fast'
MMS> mms_fpi_make_errorflagbars,'mms1_des_errorflags_brst'
MMS> mms_fpi_make_errorflagbars,'mms1_dis_errorflags_brst'
For DES/DIS distribution function (Brst and Fast):
bit 0 = manually flagged interval --> contact the FPI team for direction when utilizing this data; further correction is required
bit 1 = overcounting/saturation effects likely present in skymap
For DES/DIS moments (Brst):
bit 0 = manually flagged interval --> contact the FPI team for direction when utilizing this data; further correction is required
bit 1 = overcounting/saturation effects likely present in skymap
bit 2 = reported spacecraft potential above 20V
bit 3 = invalid/unavailable spacecraft potential
bit 4 = significant (>10%) cold plasma (<10eV) component
bit 5 = significant (>25%) hot plasma (>30keV) component
bit 6 = high sonic Mach number (v/vth > 2.5)
bit 7 = low calculated density (n_DES < 0.05 cm^-3)
bit 8 = onboard magnetic field used instead of brst l2pre magnetic field
bit 9 = srvy l2pre magnetic field used instead of brst l2pre magnetic field
bit 10 = no internally generated photoelectron correction applied
bit 11 = compression pipeline error
Bit 12 = spintone calculation error (DBCS only)
Bit 13 = significant (>=20%) penetrating radiation (DIS only)
For DES/DIS moments (Fast):
bit 0 = manually flagged interval --> contact the FPI team for direction when utilizing this data; further correction is required
bit 1 = overcounting/saturation effects likely present in skymap
bit 2 = reported spacecraft potential above 20V
bit 3 = invalid/unavailable spacecraft potential
bit 4 = significant (>10%) cold plasma (<10eV) component
bit 5 = significant (>25%) hot plasma (>30keV) component
bit 6 = high sonic Mach number (v/vth > 2.5)
bit 7 = low calculated density (n_DES < 0.05 cm^-3)
bit 8 = onboard magnetic field used instead of srvy l2pre magnetic field
bit 9 = not used
bit 10 = no internally generated photoelectron correction applied
bit 11 = compression pipeline error
Bit 12 = spintone calculation error (DBCS only)
Bit 13 = significant (>=20%) penetrating radiation (DIS only)
Original by Naritoshi Kitamura
June 2016: minor updates by egrimes
$LastChangedBy: egrimes $
$LastChangedDate: 2020-07-31 13:59:46 -0700 (Fri, 31 Jul 2020) $
$LastChangedRevision: 28962 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_make_errorflagbars.pro $
(See projects/mms/fpi/mms_fpi_make_errorflagbars.pro)
FUNCTION:
mms_fpi_quality_bar
INPUT:
probe: probe #
data_rate: brst, fast
OUTPUT:
Returns the name of a combined tplot variable with the DIS/DES quality bars
$LastChangedBy: egrimes $
$LastChangedDate: 2016-02-25 17:59:46 -0800 (Thu, 25 Feb 2016) $
$LastChangedRevision: 20195 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_quality_bar.pro $
(See projects/mms/fpi/mms_fpi_quality_bar.pro)
PROCEDURE:
mms_fpi_split_tensor
PURPOSE:
Splits FPI tensor variables (pressure, temperature) into their components
$LastChangedBy: egrimes $
$LastChangedDate: 2017-01-05 18:04:40 -0800 (Thu, 05 Jan 2017) $
$LastChangedRevision: 22516 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_fpi_split_tensor.pro $
(See projects/mms/fpi/mms_fpi_split_tensor.pro)
Procedure:
mms_get_fpi_dist
Purpose:
Returns 3D particle data structures containing MMS FPI
data for use with SPEDAS particle routines.
Calling Sequence:
data = mms_get_fpi_dist(tname [,index] [,trange=trange] [,/times] [,/structure]
[,probe=probe] [,species=species] )
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
subtract_error: subtract the distErr (variable specified by the keyword: error) data before returning
error: variable name of the disterr variable, e.g.:
'mms#_des_disterr_fast'
for fast survey electron data
Output:
return value: pointer to array of 3D particle distribution structures
or 0 in case of error
Notes:
-FPI angles stored in tplot describe instrument look directions,
this converts those to presumed trajectories (swaps direction).
- Updated to accept FPI error data on 22Sept2017
$LastChangedBy: egrimes $
$LastChangedDate: 2019-04-10 08:51:06 -0700 (Wed, 10 Apr 2019) $
$LastChangedRevision: 26986 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_get_fpi_dist.pro $
(See projects/mms/fpi/mms_get_fpi_dist.pro)
Purpose:
Returns structure containing supplementary information
for analysis of FPI data.
Return value:
Info structure containing tables to be indexed by energy table
and energy/angle bin index.
{
electron_energy: 3 x 32 array of electron energy tables
ion_energy: 3 x 32 array of ion energy tables
azimuth: Azimuth of instrument look direction
elevation: Colatitude of instrument look direction
}
Notes:
These values are approximate and should only be used in the absense of official support data!
Energies are in eV from stepper tables.
The first two columns of energies correspond to stepperTableParity = 0,1 for burst data (may be indexed).
The last energy row is a geometric average of first two and is applicable to fast survey data.
$LastChangedBy: aaflores $
$LastChangedDate: 2016-09-02 17:52:09 -0700 (Fri, 02 Sep 2016) $
$LastChangedRevision: 21796 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_get_fpi_info.pro $
(See projects/mms/fpi/mms_get_fpi_info.pro)
PROCEDURE:
mms_load_fpi
PURPOSE:
Load data from the Fast Plasma Investigation (FPI) onboard MMS
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 probe '3'
level: indicates level of data processing. FPI levels currently include 'l2',
'l1b', 'sitl', 'ql'.
datatype: valid datatypes are:
Quicklook: ['des', 'dis']
SITL: '' (none; loads both electron and ion data from single CDF)
L1b/L2: ['des-dist', 'dis-dist', 'dis-moms', 'des-moms']
data_rate: instrument data rates for MMS FPI include 'fast', 'brst'.
local_data_dir: local directory to store the CDF files; should be set if
you're on *nix or OSX, the default currently assumes Windows (c:\data\mms\)
source: specifies a different system variable. By default the MMS mission system
variable is !mms
get_support_data: load support data (defined by support_data attribute 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; use this keyword 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 name. this is useful for
preserving original tplot variable.
varformat: should be a string (wildcards accepted) that will match the CDF variables
that should be loaded into tplot variables
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 access)
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)
EXAMPLE:
MMS> timespan, '2015-09-19', 1, /day
load FPI burst mode data
MMS> mms_load_fpi, probes = ['1'], level='l2', data_rate='brst', datatype='des-moms'
load FPI FS data
MMS> mms_load_fpi, probes='3', level='l2', data_rate='fast', datatype='des-moms'
See mms_load_fpi_crib, mms_load_fpi_burst_crib, and mms_load_fpi_crib_qlplots
for usage examples
NOTES:
The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC
Please see the notes at:
https://lasp.colorado.edu/galaxy/display/mms/FPI+Release+Notes
Have questions regarding this load routine, or its usage?
https://groups.google.com/forum/#!forum/spedas
$LastChangedBy: egrimes $
$LastChangedDate: 2019-09-03 12:34:11 -0700 (Tue, 03 Sep 2019) $
$LastChangedRevision: 27716 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_load_fpi.pro $
(See projects/mms/fpi/mms_load_fpi.pro)
PROCEDURE:
mms_load_fpi_calc_pad
PURPOSE:
Calculates the omni-directional pitch angle distribution (summed and averaged)
from the individual tplot variables
$LastChangedBy: egrimes $
$LastChangedDate: 2016-08-26 11:40:59 -0700 (Fri, 26 Aug 2016) $
$LastChangedRevision: 21736 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/fpi/mms_load_fpi_calc_pad.pro $
(See projects/mms/fpi/mms_load_fpi_calc_pad.pro)