This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
eis_ang_ang.pro
PURPOSE: Generate angle-angle (polar versus azimuthal) plots for EIS data with overlaid pitch angle contours
KEYWORDS:
probe: value for MMS SC #
trange: time range of interest (string, ex. ['yyyy-mm-dd','yyyy-mm-dd'])
datatype: 'extof', 'phxtof', or 'electronenergy'
species: depends on datatype:
- ExTOF: 'proton', 'oxygen', 'alpha'
- PHxTOF: 'proton', 'oxygen'
- electronenergy: 'electron' (this will be set automatically if you specify 'electronenergy' as the datatype)
level: data level ['l1a','l1b','l2pre','l2' (default)]
data_units: 'flux' or 'cps'
data_rate: instrument data rates ['brst', 'srvy' (default)]
energy_chan: array of four energy channels (numeric, ex. [1,2,3,4])
avgdata: set to 1 to average values between the images when time range forces the resolution to greater than 1 (default = 0)
i_print: set to 1 to print to PS file (default = 0)
p_filename: string array defining filename for output .ps file
png: string defining filename for output of .png file
CREATED BY: J. Westlake, 2015-09-18
REVISION HISTORY:
+ 2015-09-21, I. Cohen : changed name from mms_ang_ang_crib to eis_ang_ang; added trange to keywords; added documentation; set plot window size;
: moved loadct out of for loop; added flat field array for each probe; added trange to get_data calls
+ 2015-09-22, I. Cohen : added /time_clip to mms_load_eis call to make trange work correctly; added res keyword for plotting time resolution;
: replaced i with correct index for timedata when plotting; change y positions in cgimage position to lower first row from top of window
: replaced color keyword in cgcontour with c_color to get white contours; added datatype keyword; added energy_chan keyword
+ 2015-09-23, I. Cohen : changed colortable for plot from 33 to 1; changed "default" color table at the end from 13 to 39; commented out get_data for sector and midtai
: added capability for electrons by using datatype in get_data calls
+ 2015-09-30, J. Westlake : changed polar binning from [-90,90] to [–80,80]; fixed issue with PA contours, replaced non-data 0's with NaN
+ 2015-10-15, J. Westlake : changed azimuth range from [0,360] to [-180,180] (0 sunward, GSE)
+ 2015-10-23, I. Cohen : added i_print switch for printing to PS
+ 2015-11-02, J. Westlake : changed definition of polar angle from !RADEG*acos(d.y[*,2])-90 to 90-!RADEG*acos(d.y[*,2]) to correct sign of polar angle
+ 2016-01-11, I. Cohen : added data_rate and data_units keywords
+ 2016-01-12, J. Westlake ; removed res keyword; fixed scaling issue in plotting; fixed timing (nspins & spininds) to force start and stop at first & last complete spins
; changed charsize to 1.5; changed number of rows to n_elements in energy_chan instead of forcing 4
+ 2016-01-20, J. Westlake ; fixed some bugs related to the number of plots on the screen and the automatic resolution selection. Cleaned up a bit around the edges
; Also implemented selectable number of energy bins - as in if you only put in two energy bins in the call then you only get two in the plots
; Also they don't have to be energy bins that are next to each other. And I put in some stuff to make the plots a bit more informative, made the axes
; go to values that we care about and added titles for the lines. Updated the flat fielding. I added the keyword avgdata to allow for averaging between
; data points or decimating the data. Also added colorbars.
+ 2016-03-02, I. Cohen : added level keyword and defined pvalue to handle L2 data
+ 2016-03-15, I. Cohen : added p_filename keyword for general printing; added prefix definition to enable handling of burst data; removed flat fielding
+ 2016-03-23, E. Grimes : removed dependencies on cgtext, cgimage, cgconlevels, cgcontour, cgcolorbar
: updated the date/time format to prevent overlap with the next plot
: added png keyword, for saving output to a PNG file
+ 2016-03-24, E. Grimes : fixed issues with postscript output caused by my changes yesterday
: set the default data_rate to 'srvy' (if not specified); request the time range (if not specified)
: commented out !p.multi call in postscript output, so that all energy channels are included in the PS file
+ 2016-03-31, E. Grimes : removed flat fielding
+ 2016-09-19, E. Grimes : updated to support v3 L1b files, as well as integer probes
+ 2016-10-26 E. Grimes : fixed bug for burst mode data; n_azi=32 (burst), n_azi=8 (srvy)
+ 2016-11-08 E. Grimes : now programmatically getting number of azimuths from the sector variable; setting species='electron' when datatype='electronenergy';
: also now checking that data exists before trying to access the data
+ 2017-05-05 I. Cohen : added ability to use "helium" as species; altered EIS varformat to include look direction and magnetic field;
: added print command to inform if data is unavailable
$LastChangedBy: egrimes $
$LastChangedDate: 2017-06-06 10:59:40 -0700 (Tue, 06 Jun 2017) $
$LastChangedRevision: 23419 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/eis_ang_ang.pro $
(See projects/mms/eis/eis_ang_ang.pro)
PROCEDURE:
eis_pabin_info
PURPOSE:
Prints EIS PA bin information - for debugging
KEYWORDS:
OUTPUT:
$LastChangedBy: egrimes $
$LastChangedDate: 2016-01-08 08:53:21 -0800 (Fri, 08 Jan 2016) $
$LastChangedRevision: 19695 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/eis_pabin_info.pro $
(See projects/mms/eis/eis_pabin_info.pro)
PROCEDURE:
mms_eis_combine_proton_pad.pro
PURPOSE:
Combine ExTOF and PHxTOF proton PADs into a single combined tplot variable
KEYWORDS:
probes: string indicating value for MMS SC #
data_rate: data rate ['srvy' (default), 'brst']
data_units: data units ['flux' (default), 'cps', 'counts']
size_pabin: size of the pitch angle bins
energy: energy range to include in the calculation
CREATED BY: I. Cohen, 2017-11-17
REVISION HISTORY:
+ 2017-11-17, I. Cohen : changed probes keyword to probes
+ 2018-02-19, I. Cohen : fixed definitions of target_phxtof_energies and target_extof_energies to account for user-defined
energy ranges that do not include all energy channels; also fixed indexing on line 95 to accommodate
+ 2018-06-12, I. Cohen : removed 12 keV energy from combined pad range; imposed new min energy limit
+ 2018-08-09, I. Cohen : introduced energy_string to keep user-defined energy range from being overwritten
(See projects/mms/eis/mms_eis_combine_proton_pad.pro)
mms_eis_combine_proton_spec.pro
PURPOSE:
Combine ExTOF and PHxTOF proton energy spectra into a single combined tplot variable
KEYWORDS:
probes: string indicating value for MMS SC #
data_rate: data rate ['srvy' (default), 'brst']
data_units: data units ['flux' (default), 'cps', 'counts']
CREATED BY: I. Cohen, 2017-05-24
REVISION HISTORY:
+ 2017-06-05, I. Cohen : added capability to handle burst data
+ 2017-06-07, I. Cohen : added capability to handle different data_units
+ 2017-08-10, I. Cohen : added warning that combination should only be done for flux data
+ 2017-08-15, I. Cohen : adjusted handling of overlapping energy range in combined spectrum
+ 2017-10-30, I. Cohen : removed "_omni" suffix
+ 2017-11-17, I. Cohen : altered how energy array is constructed; allowed for differences
in number of time steps between phxtof and extof data; changed probe
keyword to probes
+ 2017-12-04, I. Cohen : added creation of spin-averaged variable; changed to calculate combined
variables for each individual telescope, instead of just the omni variable;
added calls to mms_eis_spin_avg.pro and mms_eis_omni.pro
+ 2018-01-19, I. Cohen : added capability to handle multiple s/c at once and combine at the end
+ 2018-02-19, I. Cohen : added "total" to NAN creation on lines 77-78 to fix syntax
+ 2018-06-11, I. Cohen : added creation of new combined energy limits tplot variable
+ 2018-06-12, I. Cohen : removed 12 keV energy channel from combined proton spectrum
+ 2018-08-02, I. Cohen : fixed issue energy limits in crossover energy range
+ 2018-08-03, I. Cohen : removed "fix" from 2018-08-02; changed energy ranges to correctly
handle burst data
+ 2018-10-19, I. Cohen : fixed issue in matching phxtof/extof timing when there are more extof events
+ 2020-04-07, S. Bingham : fixed issue in mismatching phxtof/extof timing & E channel stitching
+ 2020-06-23, E. Grimes : updated call to mms_eis_omni to use the /spin keyword when calculating the spin-averages
(See projects/mms/eis/mms_eis_combine_proton_spec.pro)
PROCEDURE:
mms_eis_omni
PURPOSE:
Calculates the omni-directional flux for all 6 telescopes
NOTES:
Originally based on Brian Walsh's EIS code from 7/29/2015
REVISION HISTORY:
+ 2016-02-26, I. Cohen : changed 'cps' units_label from 'Counts/s' to '1/s' for compliance with mission standards
+ 2016-03-09, I. Cohen : altered ylabel for new omni variables
+ 2018-01-03, I. Cohen : added counts as acceptable data_units option
+ 2018-01-19, I. Cohen : simplified how p_num is pulled out
+ 2018-01-23, I. Cohen : convert zeros in data to NANs to correctly handle averaging
+ 2020-04-27, I. Cohen : added creation of single variable with energy limits of each channel
+ 2020-06-23, E. Grimes : added 'spin' keyword for properly handling suffixes on spin-averaged data
$LastChangedBy: egrimes $
$LastChangedDate: 2020-06-23 19:27:06 -0700 (Tue, 23 Jun 2020) $
$LastChangedRevision: 28799 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_eis_omni.pro $
(See projects/mms/eis/mms_eis_omni.pro)
PROCEDURE:
mms_eis_pad
PURPOSE:
Calculate pitch angle distributions using data from the MMS Energetic Ion Spectrometer (EIS)
KEYWORDS:
trange: time range of interest
probes: value for MMS SC #
species: proton (default), alpha, oxygen, electron
energy: energy range to include in the calculation
size_pabin: size of the pitch angle bins
data_units: flux or cps
datatype: extof, phxtof, electronenergy
scopes: string array of telescopes to be included in PAD ('0'-'5')
suffix: suffix used when loading the data
num_smooth: should contain number of seconds to use when smoothing
only creates a smoothed product (_pad_smth) if this keyword is specified
combine_proton_data: set equal to 1 to combine extof and phxtof data
mmsx_vars: set equal to 1 to combine SC into mms-x variables if more than 1 SC is present
(default = 0)
range_pad_only: set equal to 1 to create only an integral PAD over the user-defined energy range,
no PADs for individual energy channels (default = 0)
EXAMPLES:
OUTPUT:
NOTES:
This was written by Brian Walsh; minor modifications by egrimes@igpp and Ian Cohen (APL)
$LastChangedBy: egrimes $
$LastChangedDate: 2020-06-23 19:27:06 -0700 (Tue, 23 Jun 2020) $
$LastChangedRevision: 28799 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_eis_pad.pro $
(See projects/mms/eis/mms_eis_pad.pro)
PROCEDURE:
mms_eis_pad_combine_sc
PURPOSE: Generate composite pitch angle distributions from the EIS sensors across the MMS spacecraft
CAVEAT: This procedure does not work across HV turnoffs during periods of time when the EIS instruments
had varying HV turnoff locations/times (prior to Phase 2b)
KEYWORDS:
probes: value for MMS SC #
trange: time range of interest
species: proton (default), alpha, oxygen, electron
level: data level ['l1a','l1b','l2pre','l2' (default)]
data_rate: instrument data rates ['brst', 'srvy' (default), 'fast', 'slow']
energy: energy range to include in the calculation
datatype: extof (default), phxtof, electronenergy
suffix: suffix used when loading the data
combine_proton_data: set equal to 1 to combine extof and phxtof proton data
CREATED BY: I. Cohen, 2017-08-14
REVISION HISTORY:
+ 2017-11-14, I. Cohen : removed num_smooth keyword and calls to spd_smooth_time
+ 2017-11-15, I. Cohen : removed n_pad_spec and num_smooth keywords; added energy, data_units, datatype, and species keywords to mirror call to mms_eis_pad.pro
+ 2017-11-17, I. Cohen : removed combination of phxtof and extof data to rely on use of mms_eis_pad.pro and mms_eis_pad_combine_proton_pad.pro;
replaced species keyword definition with species and removed species
+ 2018-01-04, I. Cohen : fixed if statement for species case of 'proton'
+ 2018-02-05, I. Cohen : added suffix keyword
+ 2018-02-19, I. Cohen : added ability to handle multiple species
+ 2018-03-20, I. Cohen : added combine_proton_data keyword
+ 2018-06-14, I. Cohen : changed so that if 'combine_proton_data' is set, then only 'combined' data is handled
+ 2019-11-21, I. Cohen : changed new variable prefix to 'mmsx' instead of 'mms#-#'
+ 2020-06-16, I. Cohen : removed probes keyword, added ability to automatically define probes based on loaded EIS data like mms_eis_spec_combine_sc.pro;
change format of energy ranges in thissc_pad_vars definition
(See projects/mms/eis/mms_eis_pad_combine_sc.pro)
PROCEDURE:
mms_eis_pad_spinavg
PURPOSE:
Calculates spin-averaged PADs for the EIS instrument
KEYWORDS:
probes: Probe # to calculate the spin averaged PAD for
if no probe is specified the default is probe '1'
datatype: EIS data types include ['extof' (default), 'phxtof', 'electronenergy', 'combined'].
'combined' is only for use on combined phxtof and extof variables created by
mms_eis_combine_proton_pad.pro
data_rate: instrument data rates for EIS are: ['brst','srvy' (default)].
data_units: desired units for data. Options are ['flux' (default), 'cps', 'counts'].
suffix: appends a suffix to the end of the tplot variable name. this is useful for
preserving original tplot variable.
species: species (should be: proton (default), oxygen, alpha, or electron)
scopes: string array of telescopes to be included in PAD ('0'-'5')
OUTPUT:
$LastChangedBy: egrimes $
$LastChangedDate: 2019-09-27 12:58:38 -0700 (Fri, 27 Sep 2019) $
$LastChangedRevision: 27793 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_eis_pad_spinavg.pro $
REVISION HISTORY:
+ 2016-01-26, I. Cohen : added scopes keyword and scope_suffix definition to allow for distinction between
single telescope PADs (reflects change in mms_eis_pad.pro)
+ 2016-04-29 egrimes : fixed issues with the suffix keyword
+ 2017-05-15 egrimes : removed call to congrid, added the "extend_y_edges" option to the output;
this change makes the results produced by this routine consistent with the
non-spin averaged PAD
+ 2017-11-17, I. Cohen : updated to accept changes to mms_eis_pad.pro, introduced 'combined' datatype;
changed probe keyword to probes
+ 2017-12-04, I. Cohen : updated to create spin-averaged variables for all PAD variables, to mirror new
capabilities of mms_eis_pad.pro (changed pad_name variable to pad_vars); change
size_pabin keyword to size_pabin
(See projects/mms/eis/mms_eis_pad_spinavg.pro)
PROCEDURE:
mms_eis_set_metadata
PURPOSE:
This procedure sets some metadata for EIS data products
HISTORY:
2020 Feb 24 - Ian Cohen at APL: changed defualt yrange of electronenergy data to scale automatically to accommodate changes to electron energy
channels
$LastChangedBy: egrimes $
$LastChangedDate: 2020-02-25 10:57:51 -0800 (Tue, 25 Feb 2020) $
$LastChangedRevision: 28340 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_eis_set_metadata.pro $
(See projects/mms/eis/mms_eis_set_metadata.pro)
PROCEDURE:
mms_eis_spec_combine_sc
PURPOSE:
Combines omni-directional energy spectrogram variable from EIS on multiple MMS spacecraft
KEYWORDS:
probes: Probe # to calculate the spin average for
if no probe is specified the default is probe '1'
datatype: eis data types include ['electronenergy', 'extof', 'phxtof'].
If no value is given the default is 'extof'.
data_rate: instrument data rates for eis include 'brst' 'srvy'. The
default is 'srvy'.
data_units: desired units for data. for eis units are ['flux', 'cps', 'counts'].
The default is 'flux'.
suffix: appends a suffix to the end of the tplot variable name. this is useful for
preserving original tplot variable.
species: proton (default), oxygen, alpha or electron
CREATED BY: I. Cohen, 2017-11-17
REVISION HISTORY:
+ 2017-12-01, I. Cohen : added call to mms_eis_spin_avg.pro
+ 2018-01-04, I. Cohen : removed bad "error" message
+ 2018-02-19, I. Cohen : added ability to handle multiple species; fixed how missing spacecraft data is handled
+ 2019-11-21, I. Cohen : added ability to handle different data_units; changed new variable prefix to 'mmsx' instead of 'mms#-#'
+ 2020-03-30, I. Cohen : removed probes keyword, added ability to automatically define probes based on loaded EIS data
+ 2020-06-08, I. Cohen : fixed issue with counting MMSX data (i.e. thinking there were 5 probes)
(See projects/mms/eis/mms_eis_spec_combine_sc.pro)
PROCEDURE:
mms_eis_spin_avg
PURPOSE:
Calculates spin-averaged fluxes for the EIS instrument
KEYWORDS:
probe: Probe # to calculate the spin average for
if no probe is specified the default is probe '1'
datatype: eis data types include ['electronenergy', 'extof', 'combined', 'phxtof'].
If no value is given the default is 'extof'.
data_rate: instrument data rates for eis include 'brst' 'srvy'. The
default is 'srvy'.
data_units: desired units for data. for eis units are ['flux', 'cps', 'counts'].
The default is 'flux'.
suffix: appends a suffix to the end of the tplot variable name. this is useful for
preserving original tplot variable.
species: species (should be: proton, oxygen, alpha or electron)
multisc: set equal to 1 if trying to use data combined from multiple sc
OUTPUT:
REVISION HISTORY:
+ 2017-12-04, I. Cohen : added capability to handle 'combined' datatype
+ 2018-01-18, I. Cohen : added multisc keyword
+ 2018-02-19, I. Cohen : added 'probe_string' variable to differentiate from probe(s) and avoid
errors with overwriting in other procedures
+ 2018-06-14, I. Cohen : changed 'datatype' to 'new_datatype' in definition of p_num to stop error
when handling 'combined' data
$LastChangedBy: egrimes $
$LastChangedDate: 2018-06-14 19:25:13 -0700 (Thu, 14 Jun 2018) $
$LastChangedRevision: 25357 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_eis_spin_avg.pro $
(See projects/mms/eis/mms_eis_spin_avg.pro)
PROCEDURE:
mms_load_eis
PURPOSE:
Load data from the MMS Energetic Ion Spectrometer (EIS)
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 '1'
level: indicates level of data processing. levels include 'l2', 'l1b' and 'l1a'
The default if no level is specified is 'l1b'
datatype: EIS data types include 'extof', 'phxtof', and 'electronenergy'.
If no value is given the default is 'extof'.
data_rate: instrument data rates for EIS include 'brst' 'srvy'. The
default is 'srvy'.
data_units: desired units for data. for eis units are ['flux', 'cps', 'counts'].
The default is 'flux'.
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 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; 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
no_interp: if this flag is set no interpolation of the data will occur.
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 data)
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:
load ExTOF burst data:
MMS1> mms_load_eis, probes='1', trange=['2015-12-23', '2015-12-24'], datatype='extof', data_rate='brst', level='l2'
load PHxTOF data:
MMS1> mms_load_eis, probes='1', trange=['2015-10-31', '2015-11-01'], datatype='phxtof', level='l2'
calculate the PHxTOF PAD for protons
MMS1> mms_eis_pad, probe='1', species='proton', datatype='phxtof', data_units='flux', energy=[0, 30], level='l2'
See mms_load_eis_crib.pro, mms_load_eis_burst_crib.pro,
and mms_load_eis_crib_qlplots.pro for usage examples
NOTES:
The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC
Please see the EPD Data Products Guide for more information:
https://lasp.colorado.edu/galaxy/display/mms/EPD+Data+Products+Guide
Have questions regarding this load routine, or its usage?
https://groups.google.com/forum/#!forum/spedas
HISTORY:
09/15/2015 - Ian Cohen at APL: added modifications to omni-directional calculations to be able to handle
ExTOF and PHxTOF data
09/17/2015 - egrimes: large update, see svn log
12/15/2015 - icohen: added data_rate keyword and conditional definition of prefix in mms_eis_spin_avg and
mms_eis_omni to address burst variable name changes
4/20/2016 - egrimes added omni-directional spectra (without spin averaging)
4/28/2016 - egrimes changed no_interp options to include non-spin averaged omni-directional spectra
changed default level to L2
6/23/2020 - egrimes changed calls to mms_eis_omni to use /spin keyword
$LastChangedBy: egrimes $
$LastChangedDate: 2020-06-23 19:27:06 -0700 (Tue, 23 Jun 2020) $
$LastChangedRevision: 28799 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/eis/mms_load_eis.pro $
(See projects/mms/eis/mms_load_eis.pro)