This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 6 12:50:16 2017.
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_2_1/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_2_1/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
$LastChangedBy: egrimes $
$LastChangedDate: 2017-11-21 14:31:32 -0800 (Tue, 21 Nov 2017) $
$LastChangedRevision: 24335 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/projects/mms/eis/mms_eis_combine_proton_pad.pro $
CREATED BY: I. Cohen, 2017-11-17
REVISION HISTORY:
+ 2017-11-17, I. Cohen : changed probes keyword to probes
(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
(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
$LastChangedBy: egrimes $
$LastChangedDate: 2016-11-03 08:11:22 -0700 (Thu, 03 Nov 2016) $
$LastChangedRevision: 22263 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/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
EXAMPLES:
OUTPUT:
NOTES:
This was written by Brian Walsh; minor modifications by egrimes@igpp and Ian Cohen (APL)
$LastChangedBy: egrimes $
$LastChangedDate: 2017-11-21 14:31:32 -0800 (Tue, 21 Nov 2017) $
$LastChangedRevision: 24335 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/projects/mms/eis/mms_eis_pad.pro $
(See projects/mms/eis/mms_eis_pad.pro)
mms_eis_pad_combine_sc.pro
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
$LastChangedBy: egrimes $
$LastChangedDate: 2017-11-21 14:31:32 -0800 (Tue, 21 Nov 2017) $
$LastChangedRevision: 24335 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/projects/mms/eis/mms_eis_pad_combine_sc.pro $
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
+ 2017-11-20, E. Grimes : implemented suffix keyword, fixed issues with data_rate != brst,
updated to allow different data_units values
(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: 2017-11-20 09:33:17 -0800 (Mon, 20 Nov 2017) $
$LastChangedRevision: 24314 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/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-11-20, E. Grimes : a few minor bug fixes caught by the test suite
(See projects/mms/eis/mms_eis_pad_spinavg.pro)
PROCEDURE:
mms_eis_set_metadata
PURPOSE:
This procedure sets some metadata for EIS data products
$LastChangedBy: egrimes $
$LastChangedDate: 2016-10-21 08:30:55 -0700 (Fri, 21 Oct 2016) $
$LastChangedRevision: 22184 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/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
$LastChangedBy: egrimes $
$LastChangedDate: 2017-11-20 09:38:39 -0800 (Mon, 20 Nov 2017) $
$LastChangedRevision: 24316 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/projects/mms/eis/mms_eis_spec_combine_sc.pro $
CREATED BY: I. Cohen, 2017-11-17
REVISION HISTORY:
(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', 'partenergy', '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)
OUTPUT:
$LastChangedBy: egrimes $
$LastChangedDate: 2016-11-02 13:32:57 -0700 (Wed, 02 Nov 2016) $
$LastChangedRevision: 22258 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/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
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='ion', datatype='phxtof', ion_type='proton', 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
$LastChangedBy: egrimes $
$LastChangedDate: 2017-10-19 12:54:21 -0700 (Thu, 19 Oct 2017) $
$LastChangedRevision: 24188 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/projects/mms/eis/mms_load_eis.pro $
(See projects/mms/eis/mms_load_eis.pro)