This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
NAME:
mms_autoload_support
PURPOSE:
given a MMS tplot variable name, check to see if attitude and/or ephemeris are available, if they do not, load
the state data for the appropriate time period
CALLING SEQUENCE:
mms_autoload_support, vname=vname, attdata=attdata, ephdata=ephdata, probe_in=probe,
trange=[tmin, tmax], history_out=hist_string
INPUT:
OUTPUT:
KEYWORDS:
vname = a tplot variable name
trange: Specify a time range for which support data should be loaded
(required if vname is not supplied)
attdata: If set to 1, ensure attitude data is loaded and covers the
requested time interval
ephdata: If set to 1, ensure ephemeris data is loaded and covers the
requested time interval
probe_in: Specifies the probe name to load support data for
history_out = a history string, if data needs loading
HISTORY:
2013-12-19: Adapted from thm_autoload_support by clr
NOTES:
Either
$LastChangedBy: egrimes $
$LastChangedDate: 2017-03-01 13:09:14 -0800 (Wed, 01 Mar 2017) $
$LastChangedRevision: 22883 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_autoload_support.pro $
(See projects/mms/common/load_data/mms_autoload_support.pro)
PROCEDURE:
mms_check_file_exists
PURPOSE:
Checks if a remote MMS data file exists locally. If it does, checks the file size
of the remote file to ensure they're the same.
INPUT:
remote_file_info: structure containing the following tags:
filename: name of the remote file
filesize: size of the remote file
KEYWORDS:
file_dir:
OUTPUT:
returns 1 for the file exists and has the same filesize as the remote file
returns 0 otherwise
$LastChangedBy: egrimes $
$LastChangedDate: 2015-12-10 14:33:38 -0800 (Thu, 10 Dec 2015) $
$LastChangedRevision: 19596 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_check_file_exists.pro $
(See projects/mms/common/load_data/mms_check_file_exists.pro)
FUNCTION:
mms_estimate_mem_usage
PURPOSE:
Estimate memory usage by HPCA ion data
$LastChangedBy: egrimes $
$LastChangedDate: 2018-08-09 14:45:46 -0700 (Thu, 09 Aug 2018) $
$LastChangedRevision: 25617 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_estimate_mem_usage.pro $
(See projects/mms/common/load_data/mms_estimate_mem_usage.pro)
FUNCTION:
mms_files_in_interval
PURPOSE:
filters file list returned by the SDC to the trange. This filter is purposefully
liberal, it regularly grabs an extra file due to special cases
$LastChangedBy: egrimes $
$LastChangedDate: 2016-08-11 11:36:41 -0700 (Thu, 11 Aug 2016) $
$LastChangedRevision: 21630 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_files_in_interval.pro $
(See projects/mms/common/load_data/mms_files_in_interval.pro)
PROCEDURE:
mms_get_filename_size
PURPOSE:
Parse the json object returned by the SDC for file name and size information
OUTPUT:
returns an array of structs with the names and sizes
Written by:
Eric Grimes / egrimes@igpp.ucla.edu
Modifed by:
LMI / Laurent Mirioni (LPP) / laurent.mirioni@lpp.polytechnique.fr)
History:
11 Aug 2015 (LMI) New parse of json_object
11 Aug 2015 (LMI) Imporove parsing of json_object
11 Aug 2015 (LMI) Bugfix for multiple files
$LastChangedBy: egrimes $
$LastChangedDate: 2015-12-10 14:33:38 -0800 (Thu, 10 Dec 2015) $
$LastChangedRevision: 19596 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_get_filename_size.pro $
(See projects/mms/common/load_data/mms_get_filename_size.pro)
Procedure:
mms_get_local_files
Purpose:
Search for local MMS files in case a list cannot be retrieved from the
remote server. Returns a sorted list of file paths.
Calling Sequence:
files = mms_get_local_file_info( probe=probe, instrument=instrument, $
data_rate=data_rate, level=level, datatype=datatype, trange=trange)
Input:
probe: (string) Full spacecraft designation, e.g. 'mms1'
instrument: (string) Instrument designation, e.g. 'hpca'
data_rate: (string) Data collection mode? e.g. 'srvy'
level: (string) Data processing level, e.g. 'l1b'
trange: (string/double) Two element time range, e.g. ['2015-06-22','2015-06-23']
datatype: (string) Optional datatype specification, e.g. 'moments'
Output:
return value: Sorted string array of file paths, if successful; 0 otherwise
Notes:
-Input strings should not contain wildcards (datatype may be '*')
$LastChangedBy: egrimes $
$LastChangedDate: 2019-02-12 11:20:23 -0800 (Tue, 12 Feb 2019) $
$LastChangedRevision: 26613 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_get_local_files.pro $
(See projects/mms/common/load_data/mms_get_local_files.pro)
PROCEDURE:
mms_load_brst_segments_sdc
PURPOSE:
Loads the burst segment intervals into a bar that can be plotted
NOTE:
This is the old version of this file, use:
mms_load_brst_segments
instead.
$LastChangedBy: egrimes $
$LastChangedDate: 2016-07-01 07:52:56 -0700 (Fri, 01 Jul 2016) $
$LastChangedRevision: 21414 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_brst_segments_sdc.pro $
(See projects/mms/common/load_data/mms_load_brst_segments_sdc.pro)
PROCEDURE:
mms_load_data
PURPOSE:
Generic MMS load data routine; typically called from instrument specific
load routines - mms_load_???, i.e., mms_load_fgm, mms_load_fpi, etc.
KEYWORDS:
trange: time range of interest
probes: list of probes - values for MMS SC #
instrument: instrument, 'fpi', 'hpca', 'fgm', etc.
datatypes: depends on instrument; see header of the instrument's load routine
levels: level of data processing
data_rates: instrument data rate
local_data_dir: local directory to store the CDF files
source: sets a different system variable. By default the MMS mission system variable
is !mms
login_info: string containing name of a sav file containing a structure named "auth_info",
with "username" and "password" tags with your API login information
tplotnames: returns a list of the loaded tplot variables
get_support_data: when set this routine will load any support data
(support data is specified in the CDF file)
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: use local data only, don't query the SDC for updated files.
suffix: append a suffix to tplot variables names
varformat: should be a string (wildcards accepted) that will match the CDF variables
that should be loaded into tplot variables
cdf_filenames: 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
cdf_records: specify the # of records to load from the CDF files; this is useful
for grabbing one record from a CDF file
spdf: grab the data from the SPDF instead of the LASP SDC (only works for public access)
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 your 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)
download_only: download the data files, but do not read them
EXAMPLE:
See the instrument specific crib sheets in the examples/ folder for usage examples
NOTES:
The MMS plug-in in SPEDAS requires IDL 8.4 to access data at the LASP SDC
1) See the following regarding rules for the use of MMS data:
https://lasp.colorado.edu/mms/sdc/public/about/
2) CDF version 3.6.3+ is required to correctly handle leap seconds.
3) The local paths will mirror the SDC/SPDF directory structures
4) Warning about datatypes and paths:
-- many of the MMS instruments contain datatype details in their path names; for these CDFs
to be stored in the correct location locally (i.e., mirroring the SDC directory structure)
these datatypes must be passed to this routine by a higher level routine via the "datatype"
keyword. If the datatype keyword isn't passed, or datatype "*" is passed, the directory names
won't currently match the SDC. We can fix this by defining what "*" is for datatypes
(by a list of all datatypes) in the instrument specific load routine, and passing those to this one.
Example for HPCA: mms1/hpca/srvy/l1b/moments/2015/07/
"moments" is the datatype. without passing datatype=["moments", ..], the data are stored locally in:
mms1/hpca/srvy/l1b/2015/07/
5) For data availability:
https://lasp.colorado.edu/mms/sdc/
6) Logging into the SDC:
- If you have an internet connection, you'll be prompted for a username and password the
first time you use the MMS plugin. There's an option in the widget that allows you
to save your password in a save file on the local machine; if you select this option,
the login prompt will never come up again and your saved password will be used to
login to the SDC. This is insecure and should not be used if you use a common
password with other services.
- Use an empty username and password for public access to the data
- If you don't have an internet connection or you can't login remotely, the plugin will
look for the files on the local machine using a directory structure that matches
the directory structure at the SDC.
$LastChangedBy: egrimes $
$LastChangedDate: 2020-05-15 09:31:22 -0700 (Fri, 15 May 2020) $
$LastChangedRevision: 28694 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_data.pro $
(See projects/mms/common/load_data/mms_load_data.pro)
PROCEDURE:
mms_load_data_spdf
PURPOSE:
Load MMS data from NASA/SPDF (backup to loading from SDC)
This routine is not meant to be called directly - please use
mms_load_xxx with the /spdf keyword set.
KEYWORDS:
See mms_load_data for keyword definitions
EXAMPLE:
mms_load_fgm, /spdf, probe=1, level='l2', trange=['2016-01-10', '2016-01-11']
NOTES:
*** IMPORTANT NOTE ON BURST DATA ***
Burst data files downloaded with this routine will not be in the same
directory structure as the burst files downloaded with mms_load_data using
the SDC. This is because the SDC puts burst files in daily folders, while
SPDF doesn't.
*** Did you download the data using FTP? ***
If you download burst data from SPDF using FTP, be sure to use
the /spdf keyword when calling the mms_load_xxx routines. This
is due to the different directory structures mentioned above.
$LastChangedBy: egrimes $
$LastChangedDate: 2020-08-06 11:36:15 -0700 (Thu, 06 Aug 2020) $
$LastChangedRevision: 28999 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_data_spdf.pro $
(See projects/mms/common/load_data/mms_load_data_spdf.pro)
Purpose: Helper function to return structure describing the available data types for HPCA
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for SCM
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose:
Extracts valid rate/level/datatype based on input.
If an input is specified then only subsets of that input are checked.
If an input is not specified then all possible matches are used.
e.g. -If rate is specified then only levels and datatypes for
that rate are retuned.
-If nothing is specified then all rates/levels/datatypes
are returned.
-If all three are specified then then the output will
be identical to the input (if the input is valid).
(See projects/mms/common/load_data/mms_load_options.pro)
Procedure:
mms_load_options
Purpose:
Provides information on valid data rates, levels, and datatypes
for MMS science instruments.
Valid load options for a specified instrument will be returned
via a corresponding keyword.
Each output keyword may be used as an input to narrow the results
the the contingent options.
Calling Sequence:
mms_load_options, instrument=instrument
[,rate=rate] [,level=level], [,datatype=datatype]
[valid=valid]
Example Usage:
Input:
instrument: (string) Instrument designation, e.g. 'afg'
rate: (string)(array) Data rate e.g. 'fast', 'srvy'
level: (string)(array) Data processing level e.g. 'l1b', 'ql'
datatype: (string)(array) Data type, e.g. 'moments'
Output:
rate: If not used as an input this will contain all valid
rates for the instrument.
level: If not used as an input this will contain all valid
levels, given any specified rate.
datatype: If not used as an input this will contain all valid
datatypes, given any specified rate and level.
valid: 1 if valid outputs were found, 0 otherwise
Notes:
$LastChangedBy: egrimes $
$LastChangedDate: 2016-09-22 12:22:45 -0700 (Thu, 22 Sep 2016) $
$LastChangedRevision: 21901 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_options.pro $
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for MEC files
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for ASPOC
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for EDP
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for DSP
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for EDI
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for AFG or DFG
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for EIS
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for FEEPS
(See projects/mms/common/load_data/mms_load_options.pro)
Purpose: Helper function to return structure describing the available data types for FPI
(See projects/mms/common/load_data/mms_load_options.pro)
PROCEDURE:
mms_load_tetrahedron_qf
PURPOSE:
Loads the tetrahedron quality factor from the LASP SDC
$LastChangedBy: egrimes $
$LastChangedDate: 2017-07-20 16:20:12 -0700 (Thu, 20 Jul 2017) $
$LastChangedRevision: 23686 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_tetrahedron_qf.pro $
(See projects/mms/common/load_data/mms_load_tetrahedron_qf.pro)
PROCEDURE:
mms_load_tqf
PURPOSE:
Loads the tetrahedron quality factor from the LASP SDC
(this is a simple wrapper around mms_load_tetrahedron_qf)
$LastChangedBy: egrimes $
$LastChangedDate: 2017-07-20 16:22:57 -0700 (Thu, 20 Jul 2017) $
$LastChangedRevision: 23687 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_load_tqf.pro $
(See projects/mms/common/load_data/mms_load_tqf.pro)
PROCEDURE:
mms_login_lasp
PURPOSE:
Authenticates the user with the SDC at LASP; if no keywords are provided,
the user is prompted for their MMS user/password, and that is saved
locally in a sav file
KEYWORDS:
login_info: string containing name of a sav file containing a structure named "auth_info",
with "username" and "password" tags with your API login information
save_login_info: set this keyword to save the login information in a local sav file named
by the keyword login_info - or "mms_auth_info.sav" if the login_info keyword isn't set
username: this keyword returns the name of the logged in user, or 'public' for public users
widget_note: text of note to add to the bottom of the login widget
always_prompt: do not use the saved login information
$LastChangedBy: egrimes $
$LastChangedDate: 2016-10-04 15:49:46 -0700 (Tue, 04 Oct 2016) $
$LastChangedRevision: 22025 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_login_lasp.pro $
(See projects/mms/common/load_data/mms_login_lasp.pro)
PROCEDURE:
mms_parse_json
PURPOSE:
Parse the json object returned by the SDC for file name and size information
OUTPUT:
returns an array of structs with the names and sizes
Written by:
Eric Grimes / egrimes@igpp.ucla.edu
Modifed by:
LMI / Laurent Mirioni (LPP) / laurent.mirioni@lpp.polytechnique.fr)
Cindy Russell / clrussell@igpp.ucla.edu
History:
11 Aug 2015 (LMI) New parse of json_object
11 Aug 2015 (LMI) Imporove parsing of json_object
11 Aug 2015 (LMI) Bugfix for multiple files
26 Aug 2015 (IGPP) added support for the 'start_date' and 'end_date' tags
$LastChangedBy: egrimes $
$LastChangedDate: 2015-12-10 14:33:38 -0800 (Thu, 10 Dec 2015) $
$LastChangedRevision: 19596 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_parse_json.pro $
(See projects/mms/common/load_data/mms_parse_json.pro)
Function:
mms_quality_bar
Input:
data_in: tplot variable containing bit flags for quality of data
Output:
Creates a tplot variable with the name data_in + _bar, containing
quality bars. Returns the name of the tplot variable it created.
$LastChangedBy: egrimes $
$LastChangedDate: 2015-12-10 14:33:38 -0800 (Thu, 10 Dec 2015) $
$LastChangedRevision: 19596 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/mms_quality_bar.pro $
(See projects/mms/common/load_data/mms_quality_bar.pro)
FUNCTION:
spd_check_internet_connection
PURPOSE:
check the local internet connection by connecting to Google's homepage; this
is so we don't prompt the user for a password if they're sitting in
the airport without an internet connection...
$LastChangedBy: egrimes $
$LastChangedDate: 2015-12-10 14:33:38 -0800 (Thu, 10 Dec 2015) $
$LastChangedRevision: 19596 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/load_data/spd_check_internet_connection.pro $
(See projects/mms/common/load_data/spd_check_internet_connection.pro)