This page was created by the IDL library routine `mk_html_help2`.

Last modified: Wed Oct 1 18:17:54 2025.

# Directory Listing of Routines

# projects/mms/eis

- EIS_PABIN_INFO
  Prints EIS PA bin information - for debugging
- MMS_EIS_ANG_ANG
- MMS_EIS_COMBINE_PROTON_SPEC
  Combine ExTOF and PHxTOF proton energy spectra into a single combined tplot variable
- MMS_EIS_OMNI
  Calculates the omni-directional flux for all 6 telescopes
- MMS_EIS_PAD
  Calculate pitch angle distributions using data from the MMS Energetic Ion Spectrometer (EIS)
- MMS_EIS_PAD_COMBINE_SC
- MMS_EIS_PAD_SPINAVG
  Calculates spin-averaged PADs for the EIS instrument
- MMS_EIS_SET_METADATA
  This procedure sets some metadata for EIS data products
- MMS_EIS_SPEC_COMBINE_SC
  Combines omni-directional energy spectrogram variable from EIS on multiple MMS spacecraft
- MMS_EIS_SPIN_AVG
  Calculates spin-averaged fluxes for the EIS instrument
- MMS_LOAD_EIS
  Load data from the MMS Energetic Ion Spectrometer (EIS)

# Routine Descriptions

## EIS_PABIN_INFO

[Next Routine] [List of Routines]

     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/trunk/projects/mms/eis/eis_pabin_info.pro $

(See projects/mms/eis/eis_pabin_info.pro)

## MMS_EIS_ANG_ANG

[Previous Routine] [Next Routine] [List of Routines]

     mms_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', 'helium' (formerly 'alpha')
                                   - PHxTOF: 'proton'
                                   - 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
             no_plot:            set =1 to not plot data (default = 0)
             cdf_version:        (optional) desired CDF version of EIS data to load
             n_azbins:           number of azimuthal bins (if not set, will be automatically defined by data_rate)

     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
           + 2020-07-02, S. Bingham    : added no_plot, cdf_version, and n_azbins keywords; added output of ang-ang data to tplot variable; changed procedure name to 'mms_eis_ang_ang.pro'
           + 2020-12-11, I. Cohen      : changed "undefined" to "undefined" in initialization of some keywords
           + 2021-02-09, I. Cohen      : added helium to species in header under KEYWORD section and removed PHxTOF oxygen; added loadct call for species='helium'
           + 2021-04-08, I. Cohen      : updated prefix definition to handle new L2 variable names

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-08-06 09:27:09 -0700 (Fri, 06 Aug 2021) $
    $LastChangedRevision: 30179 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_eis_ang_ang.pro $

(See projects/mms/eis/mms_eis_ang_ang.pro)

## MMS_EIS_COMBINE_PROTON_SPEC

[Previous Routine] [Next Routine] [List of Routines]

     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']
             level:              data level ['l1a','l1b','l2pre','l2' (default)]

     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
           + 2020-11-19, I. Cohen          : fixed issue with overlap energies - average between all shared energies
           + 2020-12-11, I. Cohen          : changed "not KEYWORD_SET" to "undefined" in initialization of some keywords
           + 2021-01-21, I. Cohen          : removed lowest ExTOF energy channel because of noise near detector threshold
           + 2021-01-27, I. Cohen          ; fixed error from previous change that duplicated uppermost energy channel
           + 2021-06-17, I. Cohen          : added level keyword; updated eis_prefix definition to handle new L2 variable names;
                                             added level to mms_eis_spin_avg and mms_eis_omni calls

(See projects/mms/eis/mms_eis_combine_proton_spec.pro)

## MMS_EIS_OMNI

[Previous Routine] [Next Routine] [List of Routines]

     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

    ; KEYWORDS:
             probe:        Probe # to calculate the spin average for
                           if no probe is specified the default is probe '1'
             species:      species (should be: proton, oxygen, helium (formerly alpha) or electron)
             datatype:     eis data types include ['electronenergy', 'extof', 'phxtof'].
                           If no value is given the default is 'extof'.
             level:        data level ['l1a','l1b','l2pre','l2' (default)]
             tplotnames:   specific tplot variables to spin-average
             suffix:       appends a suffix to the end of the tplot variable name. this is useful for
                           preserving original tplot variable.
             data_units:   desired units for data. for eis units are ['flux', 'cps', 'counts'].
                           The default is 'flux'.
             data_rate:    instrument data rates for eis include 'brst' 'srvy'. The
                           default is 'srvy'.
             spin:         set =1 to use spin-averaged variables

     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
           + 2021-02-09, I. Cohen      : added KEYWORDS section to header
           + 2021-04-08, I. Cohen      : added level keyword; updated prefix definition to handle new L2 variable names

    $LastChangedBy: egrimes $
    $LastChangedDate: 2023-05-19 13:57:02 -0700 (Fri, 19 May 2023) $
    $LastChangedRevision: 31867 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_eis_omni.pro $

(See projects/mms/eis/mms_eis_omni.pro)

## MMS_EIS_PAD

[Previous Routine] [Next Routine] [List of Routines]

     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), helium (formerly 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
             level:                data level ['l1a','l1b','l2pre','l2' (default)]
             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: 2021-08-03 09:08:16 -0700 (Tue, 03 Aug 2021) $
    $LastChangedRevision: 30167 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_eis_pad.pro $

(See projects/mms/eis/mms_eis_pad.pro)

## MMS_EIS_PAD_COMBINE_SC

[Previous Routine] [Next Routine] [List of Routines]

     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), helium (formerly 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
           + 2020-10-26, I. Cohen    : added/edited lines from mms_eis_spec_combine_sc.pro to create spin-averaged variables
           + 2020-11-02, R. Nikoukar : changed 'mmsx' to 'mms#-#' for consistency with mms_eis_spec_combine_sc.pro; corrected time indexing for spin-averaged variables
           + 2020-12-14, I. Cohen    : changed "not KEYWORD_SET" to "undefined" in initialization of some keywords;
                                       added "datarate_str" to handle issue with probes definition if both burst and survey data are loaded
           + 2021-01-06, I. Cohen    : added wildcard into string in definition of eis_sc_check for phxtof data
           + 2021-02-09, I. Cohen    : added helium to species in header under KEYWORD section and added default datatype if species=helium
           + 2021-04-08, I. Cohen    : updated allmms_prefix definition to handle new L2 variable names
           + 2021-06-16, I. Cohen    : fixed error in definition of allmms_pad_vars and thissc_pad_vars
           + 2021-06-17, I. Cohen    : fixed error in definition of prefix
           + 2021-07-09, I. Cohen    : fupdated definition of prefix to handle 'combined' datatype

(See projects/mms/eis/mms_eis_pad_combine_sc.pro)

## MMS_EIS_PAD_SPINAVG

[Previous Routine] [Next Routine] [List of Routines]

     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'].
             level:        data level ['l1a','l1b','l2pre','l2' (default)]
             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, helium (formerly alpha), or electron)
             scopes:       string array of telescopes to be included in PAD ('0'-'5')

     OUTPUT:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-08-03 09:08:16 -0700 (Tue, 03 Aug 2021) $
    $LastChangedRevision: 30167 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/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
           + 2020-12-11, I. Cohen      : changed "not KEYWORD_SET" to "undefined" in initialization of some keywords
           + 2021-02-09, I. Cohen      : added helium to species in header under KEYWORD section
           + 2021-04-08, I. Cohen      : added level keyword; updated prefix definition to handle new L2 variable names

(See projects/mms/eis/mms_eis_pad_spinavg.pro)

## MMS_EIS_SET_METADATA

[Previous Routine] [Next Routine] [List of Routines]

     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
         2021 Feb 09 -  Ian Cohen at APL: added "helium" variables
         2021 May 21 -  Ian Cohen at APL: removed obsolete "alpha" variables

     $LastChangedBy: egrimes $
     $LastChangedDate: 2021-08-03 09:08:16 -0700 (Tue, 03 Aug 2021) $
     $LastChangedRevision: 30167 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_eis_set_metadata.pro $

(See projects/mms/eis/mms_eis_set_metadata.pro)

## MMS_EIS_SPEC_COMBINE_SC

[Previous Routine] [Next Routine] [List of Routines]

     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'.
             level:        data level ['l1a','l1b','l2pre','l2' (default)]
             suffix:       appends a suffix to the end of the tplot variable name. this is useful for
                           preserving original tplot variable.
             species:      proton (default), oxygen, helium (formerly 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)
             + 2020-09-14, I. Cohen        : fixed issue with proton being hardcoded in eis_sc_check
             + 2020-09-28, I. Cohen        : fixed issue with proton being hardcoded in call for spin-averaging
             + 2020-09-29, I. Cohen        : changed "mmsx" prefix to mms#-# for consistency with other EIS procedures and
                                             removed call to mms_eis_spin_avg.pro, instead create spin-averaged variables directly here
             + 2020-09-30, I. Cohen        : removed duplicate "datatype" in name of tplot spin variable (line 105)
             + 2020-10-26, I. Cohen        : added missing "datatype" in definition of prefix for survey data
             + 2020-12-11, I. Cohen        : moved eis_sc_check definition into species loop to address issue handling multiple species from single call
             + 2021-02-09, I. Cohen        : added helium to species in header under KEYWORD section
             + 2021-02-15, R. Nikoukar     : accommodate data_units other than flux
             + 2021-02-24, I. Cohen        : changed combined s/c variable names from mms#-# to mmsx
             + 2021-03-11, I. Cohen        : updated to allow to work for electrons
             + 2021-03-16, R. Nikoukar     : use existing individual spacecraft spin parameters to make combined spacecraft spin parameters
             + 2021-04-08, I. Cohen        : added level keyword; updated allmms_prefix, omni_vars, & prefix definitions to handle new L2 variable names
             + 2021-05-12, I. Cohen        : fixed eis_sc_check definition to handle any datatype
             + 2021-07-09, I. Cohen        : fixed default level defition to 'l2'

(See projects/mms/eis/mms_eis_spec_combine_sc.pro)

## MMS_EIS_SPIN_AVG

[Previous Routine] [Next Routine] [List of Routines]

     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'.
             level:        data level ['l1a','l1b','l2pre','l2' (default)]
             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, helium (formerly 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
           + 2021-02-09, I. Cohen          : updated possible species under KEYWORDS header
           + 2021-04-08, I. Cohen          : added level keyword; updated prefix definition to handle new L2 variable names

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-08-03 09:08:16 -0700 (Tue, 03 Aug 2021) $
    $LastChangedRevision: 30167 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_eis_spin_avg.pro $

(See projects/mms/eis/mms_eis_spin_avg.pro)

## MMS_LOAD_EIS

[Previous Routine] [List of Routines]

     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
         04/20/2016 - egrimes added omni-directional spectra (without spin averaging)
         04/28/2016 - egrimes changed no_interp options to include non-spin averaged omni-directional spectra
                      changed default level to L2
         06/23/2020 - egrimes changed calls to mms_eis_omni to use /spin keyword
         02/09/2021 - icohen added 'helium' species calls
                      commented out processing of unverified 'oxygen' phxtof variables
         04/08/2021 - icohen added level to mms_eis_spin_avg & mms_eis_omni calls

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-08-06 09:26:52 -0700 (Fri, 06 Aug 2021) $
    $LastChangedRevision: 30178 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/mms/eis/mms_load_eis.pro $

(See projects/mms/eis/mms_load_eis.pro)