Command line functions

From SPEDAS Wiki
Revision as of 02:11, 6 December 2023 by Jwl (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Command line vs GUI

SPEDAS can be used in two ways:

  • The IDL command line
  • The SPEDAS GUI

Comparing the two, the command line is more powerful, it offers more options, and there are functions that have only command line representation without any equivalent GUI element. On the other hand, new users may find the GUI easier to work with.

To use the IDL command line, an IDL software license from NV5 (the vendor of IDL) is required.

When working with SPEDAS, the workflow is usually the following:

  1. Load some data.
  2. Perform some transformations on the data.
  3. Make some plots.


Load data

SPEDAS can download data from several space missions. Each mission provides its own functions to load data. Each mission has its own directory in the "projects" folder and this directory contains the functions needed to load data. The files contain detailed information on the command line functions needed to load particular data and the parameters and keywords that the user can provide. Most of the time the user has to provide as parameters the dates and the instruments for which data should be loaded.

For example, to load FGM data for the probe 1 of the MMS mission, the command is:

mms_load_fgm, probe=1, trange=['2015-09-01/21:15', '2015-09-01/21:25'], level='l2'

This command line function will download the proper CDF files from a remote directory (usually using HTTP), read the downloaded files and load the data into an IDL object that is called tplot. This object is the heart of SPEDAS, it will hold all the data and it can be used to manipulate and plot the data.

To find the proper load function, the user can open the projects directory of the SPEDAS source code, find the proper source code file and read the comments at the beginning of the file. Another option, is to examine some of the detailed crib sheets in the examples directory of the particular mission.


Data analysis

After the data is loaded, it resides inside the tplot object and can be transformed and manipulated using the SPEDAS functions for data analysis or the functions provided by IDL itself. The results can again be saved inside the tplot object and can later be used for plotting data.


Plots

Data sets can be plotted, either as a single panel plots, or as multipanel plots. The tplot function can plot any number of data sets it contains.

For example, to plot the FGM data for the MMS mission loaded above, the command is:

tplot, 'mms1_fgm_b_gsm_srvy_l2'

The tplot function contains several options that can change the appearance of the plot. We suggest that the user goes through the crib_tplot.pro file which contains a lot of examples on how to specify tplot options. This crib sheet can be found in the following directory:

general/examples/crib_tplot.pro


How to find which command line function to use

There are several options in order to find the relevant command line functions and their parameters and keywords:

  • Find the SPEDAS source code file and read the source code comments at the beginning of the file.
  • Open the examples directory and find a crib sheet to use as an example. Note that each mission under projects has its own example directory, while general and spedas_gui also contain their own example directories.
  • Browse or search the SPEDAS HTML documentation.