Load Routines

This section describes the load routines for data sets that have direct support in PySPEDAS (as opposed to data sets available via HAPI, CDAWeb, or other APIs).

Some key points that apply to most or all of these load routines:

PySPEDAS maintains a cache of previously downloaded data. The cache location to use is controlled by the SPEDAS_DATA_DIR environment variable. Many missions allow the user to set a data directory specific to that mission, overriding the global SPEDAS_DATA_DIR setting. For example, THM_DATA_DIR can be used to specify the local directory to use for the THEMIS mission. The cache location can be a local file directory or a URI location (e.g., an S3 repository).
By default, PySPEDAS contacts the data server to get a list of filenames to fulfill the request, and compares the modification times on the server and locally cached files to determine whether the files need to be downloaded.
- Specify no_update=True in the parameter list to bypass the data server, and only use locally cached files. This is useful when internet services is slow or unavailable.
The time range for data to be loaded is specified via the trange parameter, which should be a list [start_time end_time] The start and end times can be specified as:
- Strings, with somewhat flexible formatting:
  “2007-03-23” (corresponds to time 00:00:00 on that date)
  
  “2021-01-01/01:23:45.678”
- Python or Numpy datetime objects
- Numeric values corresponding to Unix timestamps (seconds since 1970-01-01/00:00:00)
The start and end times should be supplied in the same format.
For data sets supplied in CDF format, the following parameters may be supported:
- get_support_data: If True, CDF variables with attributes identifying them as ‘support data’ will be loaded. By default, only variables marked as ‘data’ would be loaded.
- varformat: If supported by the load routine, the varformat parameter can be used to specify a wildcard pattern describing the CDF variable names to be loaded.
- varnames: If supported by the load routine, varnames specifies a list of CDF variable names to be loaded.
prefix and suffix parameters: By default, tplot variable names of loaded data correspond to the variable names used in the data files. If supported by the load routine, these parameters can be used to modify the tplot variable names. This is useful when the data files use generic names, like “Temperature” or “Pressure”, which could conflict with similar variables from other data sets.
Some data sets (e.g. MAVEN, MMS, THEMIS, etc) can be downloaded via their own servers, and are also archived at NASA’s Space Physics Data Facility (SPDF). If supported by the load routine, setting spdf=True will retrieve data from SPDF rather than the mission’s default data server. This is useful for cases where the mission’s data server is offline or otherwise unavailable.
notplot: Some load routines support setting notplot=True to return the data structures directly, rather than converting them to tplot variables and returning a variable list.
time_clip: Some load routines support setting time_clip=True to ensure that only data in the specified trange will be returned. By default, if the data is supplied in 1-day chunks, the entire file contents will be returned, even if the trange specifies less than a day.
downloadonly: If supported, setting downloadonly=True downloads the data files, without converting them to tplot variables and loading them into Python. This is useful if you intend to process the data files with some other tool, but PySPEDAS provides convenient access to the data.
probe, probes, site and sites parameters: Some missions (for example, MMS, THEMIS, GOES, etc) provide data sets for multiple observatories. The probes and sites parameters allow the user to select the observatories for which data should be loaded. probes is generally used for space missions, while sites is used for ground-based data. (Check the documentation for the specific load routine to see if it uses the singular or plural forms.)