THEMIS User’s Guide:
THEMIS Science Data Analysis Software (TDAS)
THM-SOC-120
August 2014

Jim McTiernan, THEMIS Science Software Engineer
Pat Cruce, THEMIS Science Software Engineer
Aaron Flores, THEMIS Science Software Engineer
Cindy Russell, THEMIS Science Software Engineer
Eric Grimes, THEMIS Science Software Engineer
Nick Hatzigeorgiu, THEMIS Science Software Engineer
Jim Lewis, THEMIS Science Software Manager
Vassilis Angelopoulos, THEMIS Principal Investigator

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Document Revision Record
Rev.
01
02

Date
08/06/2007
11/06/2007

Description of Change
v2.01 Incremental Changes
v3.00 Release Changes

03

11/19/2007

Replace Data Variable Description Tables

04
05
06
07
08
09
10

05/2008
04/200906/2009
02/201003/201103/201204/2013v4.00 Release Changes
V5.00 Release Changes
V5.1 Release Changes
V5.20 Release Changes
V6.00 Release Changes
V7.00 Release Changes
V8.00 Release Changes

Distribution List
See: http://themis.ssl.berkeley.edu/team.shtml

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Revised By
D. King
D. King /J.
McTiernan /Andreas Keiling
D. King /Andreas Keiling
Software Team
Software Team
Software Team
Software Team
Software Team
Software Team
Software TeamTable of Contents
DOCUMENT REVISION RECORD...........................................................................................................................................2
DISTRIBUTION LIST.................................................................................................................................................................2
1. THEMIS DATA.........................................................................................................................................................................4
1. THEMIS DATA ANALYSIS SOFTWARE..............................................................................................................................5
2. GRAPHICAL USER INTERFACE.......................................................................................................................................36

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

1. THEMIS Data
This section describes the THEMIS data, as seen by the THEMIS Data Analysis Software.

0 .0 THEMIS Data Overview
THEMIS data is available in 3 levels
Level 0telemetry packet format, overlaps removed and formatted into daily files
Level 1
CDF data files, contain raw telemetry data
Level 2
CDF data files, calibrated data, in physically meaningful units

0 .0 THEMIS Data Variable Descriptions
THEMIS Data variable Descriptions can be found at
http://themis.ssl.berkeley.edu/downloads/Data_Variable_Descriptions.pdf.
This document summarizes the data types recognized by TDAS. It includes the variable names as they appear on an
Instrument's GUI Widget as well as in the GUI Main widget's Active Data window (GUI concepts will be discussed in
Section 2) and in the IDL command line interface. Please note that in the table the variable names do not include their probe
prefix (e.g. tha_ for a probe 'A' variable).

0 .0 THEMIS Science Data Analysis Software Overview
The THEMIS Science Data Analysis Software (hereafter referred to as TDAS) is IDL-based. TDAS routines can be used todownload, open, analyze and plot L1 or L2 data and process L1 data into L2 data quantities. There are two main ways to use
the programs: with the command line interface or with the GUI interface.
Other features include coordinate transformations and utility routines to translate data into other products (e.g., ascii) as
necessary.

0 .0 Supplementary Documents
Various supplementary documents can be found on the THEMIS website. These include but are not limited to documentation
for:







Coordinate Systems
Time Conventions
Instrument Calibration
Data Calibration and Processing
Variable Naming (for data products)
Software Documentation (including this user’s guide)

These documents may be accessed from the THEMIS home page by selecting Documentation under the Software menu.
http://themis.ssl.berkeley.edu/index.shtml
They may also be accessed directly via the link below:
ftp://apollo.ssl.berkeley.edu/pub/THEMIS/3%20Ground%20Systems/3.2%20Science%20Operations/Science%20Operations%20Documents/

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 . THEMIS Data Analysis Software
0.0 System Requirements
The THEMIS Data Analysis Software requires an IDL developer’s license for Windows or a UNIX-like operating system,e.g. Solaris, Linux, or Mac OS X. The software has been tested on IDL 6.3, 6.4, 7.0, and 7.1 but should work on any level of
IDL above and including IDL 6.2 and below IDL 8.0. We have had reports of some issues with IDL 8.0 and above on certain
operating systems (for example, changed font sizes, leading to poor results using default plot settings), but most TDAS
functions should work in these environments. As of this writing, IDL 8.2.2 is the most current version, and testing has shownthat most of TDAS works, but on-the-fly calibration of some data types (e.g., FGM L1) is extremely slow. Exelis is aware of
the issue, and claims that it will be fixed in the next service pack. The external package, IDL_GEOPACK (for the
Tsyganenko magnetic field model), requires IDL 6.3 or above. There is a patch to IDL, which is recommended for best
handling of the CDF file format that is used by the THEMIS data files. See:
http://cdf.gsfc.nasa.gov/html/cdf_patch_for_idl6x_new3400.html
If you are using IDL 6.2, or if you are using Intel Mac with any version of IDL (up to 6.4), or if you are using IDL 7.0 you
must install this patch to read CDF files properly. It is recommended that you install this patch for all versions of IDL 6.2 orlater.
Mac OS X notes:
You need X11 running to view plots and use the GUI in IDL. You can search for X11 in the Spotlight to see if the
X11 application is installed on your system. X11 is available on your Mac installation disks, but may not be
installed by default.
There is a known problem, mentioned in the IDL 6.3 release notes, which affects all IDL users running Mac OS
10.4.x (Tiger) or 10.5.x (Leopard). The tlimit command will lock up IDL because the plot window will not receive
any mouse clicks. The workaround is slightly different, depending on the MacOS version.
Workaround: Change the X11 start-up parameters. Do the following: Determine the version of MacOS you're using by clicking Apple->About This Mac
 Open any terminal window (in the X11 application menu bar, you can choose xterm from the applications
menu)
 If your MacOS version is 10.4.x, enter the following at the shell prompt:
defaults write com.apple.x11 wm_click_through -bool true If your MacOS version is 10.5.x, enter the following at the shell prompt:
defaults write org.x.x11 wm_click_through -bool true
 Quit X11 (if it is running).
The new default will take effect the next time you start X11, and it will persist from that point (i.e., you will not haveto make the change again).
Note: X11actually needs to be running in the background.
Linux, Ubuntu notes:
There are problems with some versions of ubuntu and IDL graphic objects. If you find that widgets are not realized
when opening a new window, you may need to turn visual effects off. This can be done using Ubuntu systempreferences and setting Visual effects to none.

0.0 Known Limitations
1. Incompatibilities with Solar Software (SSW). There exist some name clashes if both TDAS and SSW are on yourIDL_PATH.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

2. ASI data: ASF (full resolution ASI data) requires a 64-bit machine with multiple Gbytes of virtual memory toload more than 1 hour’s worth of data.
3. Warning for IDL 7.0 users. A bug has been found with IDL 7.0 and CDFs that cause crashes on any operating
system when loading CDF data. All IDL 7.0 users must go to:
http://cdf.gsfc.nasa.gov/html/cdf_patch_for_idl6x_new3400.html and install this patch.
4. The IDL executive command .reset_session does not work for the THEMIS GUI software. Please use thecommand .full_reset_session to reset IDL sessions.
5. On-the-fly calibration of L1 FGM data is extremely slow under IDL 8.2.2. Input of ESA packet data is also
extremely slow.
6. On Windows, attempting to write to a write-protected file or directory will cause a crash due to an IDL bug.
7. The IDL built-in interpol command filters out NaN values by default in IDL 7.1, but not in earlier or later
versions.
8. We have had reports of problems using IDL’s built in “Print Setup” and “Print” GUI dialogs on the Linux andMac platforms. If you experience difficulty, we recommend using the “Export to Image” functionality to produce
an image file in EPS or some other format, then printing that file outside of IDL.

0.0 Installation and Configuration
Getting started is usually as simple as of downloading the code and adjusting your IDL path.
For a new installation:
1. Download and expand the latest TDAS release .zip file. See the THEMIS web site:
http://themis.ssl.berkeley.edu/software.shtml
2. Create a directory called TDAS into which you will copy the latest software.
3. Move the tdas_x_xx folder into the TDAS directory.
4. Configure IDL to search the TDAS directory for IDL programs. See Section 1.3.1 IDL PATH setup.
For an upgrade of an existing installation of TDAS, as per the above 4 steps:
1.
Remove old tdas_x_xx from the TDAS directory.
2.
Download and expand the latest TDAS release .zip file.
3.
Copy the new tdas_x_xx directory into the pre-existing TDAS directory.
4.
Re-start IDL.

0.0.0 IDL PATH Setup0 .0 .0 .0 IDL PATH Setup on Windows (and IDLDE on UNIX, Linux and Mac)For Windows or IDLDE on UNIX, use the File->Preferences widget to set up the path so IDL can find the TDAS IDL files.
Note: On IDL 7.0 or new this menu can be found under Window->Preferences
UNIX Note: If you use IDLDE on UNIX-like systems, these instructions only work if you do not set the IDL_PATH
environment variable before you call IDLDE. If IDLDE does not allow you to set the path by following these instructions,then follow the instructions for UNIX installation below.
On IDL 6.4 or older:
Start IDL (Windows) or IDLDE (UNIX, Linux, Mac).

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

Go to File->Preferences.
Select the “Path” tab.
If <IDL_DEFAULT> is not present, press ‘Insert Standard Libraries’.
Press “Insert”.
Browse to find the TDAS directory. (See Section 1.3 above: Installation and Configuration.)
Check the box to indicate “search subdirectories”.
On IDL 7.0 or newer:Start IDL (Windows) or IDLDE (UNIX, Linux, Mac).
Go to Window->Preferences.
Expand the menu to access the IDL->Paths section.
Press “Insert”.
Browse to find the TDAS directory. (See Section 1.3 above: Installation and Configuration.)
Check the box next to the path to indicate “search subdirectories”.
Select “Apply”
Select “Ok”
Type .full_reset_session at the IDL command prompt or restart IDL.

0 .0 .0 .0 IDL PATH Setup for IDL Command Line (UNIX, Linux or Mac OS X)
For the command line version of IDL, installation consists of setting up the IDL_PATH environment variable.
Simply set the IDL_PATH environment to search all subdirectories of the TDAS directory created in Section 1.3 Installation
and Configuration.
for csh or tcsh, place the following in your .cshrc file:setenv IDL_PATH ’<IDL_DEFAULT>:+/path/to/tdas’for bash or sh, place the following in your .bashrc (Linux, Solaris) or .bash_profile (Mac) file:export IDL_PATH=’<IDL_DEFAULT>:+/path/to/tdas’

It is important to replace the text “/path/to/tdas” with the directory on your system that contains the TDAS files. This might
be something like: ~/Desktop/tdas/ Also, don't forget to include the “+” before the directory. Without this, it will not work.
Mac OS X Notes:
You can edit your .bash_profile file using the standard Mac TextEdit program (normally, it's impossible to open 'hidden' files
beginning with '.' using TextEdit or the Mac Finder)
In the Terminal, type (or cut-and-paste)/Applications/TextEdit.app/Contents/MacOS/TextEdit ~/.bash_profile
That will open the .bash_profile file in the standard Mac text editor. The following configurations are recommended toenable you to use IDL from the Terminal.
# Configurations to make IDL and TDAS work from the Terminal
export DISPLAY=:0.0
IDL_LOC='/Applications/rsi/idl_6.3'
source ${IDL_LOC}/bin/idl_setup.bash
export IDL_PATH='<IDL_DEFAULT>:/path/to/tdas'# End configurations for IDL and TDAS

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Note that IDL_LOC may vary, depending on version of IDL installed. Search for actual location of IDL using Spotlight. In
newer versions of IDL the line may look something like: IDL_LOC='/usr/local/itt/idl70'
Tip:
You can drag the 'tdas' directory from the Finder into the TextEdit or Terminal window to paste the actual path for/path/to/tdas.
After saving the file, be sure to exit the TextEdit application from the menu bar, so you can get your command line prompt
back!

0.0.0 Data Directory Setup
The THEMIS Data Analysis Software requires a local data directory in which THEMIS data files can be cached. The
software will attempt to create the local data directory for you at the following default location, depending on your operating
system.
OS
Windows
Solaris, Linux, Mac OS X

LOCAL_DATA_DIR
C:\data\themis~/data/themis

These locations should work as-is for most installations; however, if you do not have administrative privileges to create thedata directory in the above locations, you can have your system administrator create it, or you can configure the THEMIS
Data Analysis Software to use an alternate location. See Remote Data Access and Local Data Cache (Sections 1.5.10 –1.5.11) for information about configuring an alternate location.

0.0.0 THEMIS Mirror Sites
THEMIS data is also available from a number of mirror sites around the world. There are currently four mirror sites inoperation in addition to the home THEMIS site at SSL. In order to get data from a mirror site, change the !
THEMIS.REMOTE_DATA_DIR variable to the appropriate site. (Directions for changing the can be found in Sections
1.5.10 – 1.5.11; Remote Data Access and Local Data Cache).
Server Location
SSL, UC Berkeley
SPDF, NASA GSFC
IGPP, UCLA
CESR, France
ISAS JAXA, Japan

REMOTE_DATA_DIR
http:// themis.ssl.berkeley.edu/data/themis/
http://spdf.gsfc.nasa.gov/pub/data/themis/
http://themis-data.igpp.ucla.edu/
http://cdpp.cesr.fr/themisdata/
http://themis.stp.isas.jaxa.jp/data/themis/

0.0.0 IDL_GEOPACK
To use the Tsyganenko Model extensions to the THEMIS software, you need to download and install the interface between
Tsyganenko's Fortran code and IDL. This interface was developed and provided for THEMIS as a courtesy by Dr. Haje Korth
of JHU APL. The IDL Geopack DLM is a Dynamic Link Module (DLM) for IDL. Installation instructions can be found at
http://themis.ssl.berkeley.edu/README.txt. You can also find detailed installation directions and the DLM files for various
platforms at http://ampere.jhuapl.edu/code/idl_geopack.html.
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0 Running TDAS without an IDL license
For users without an IDL development license, we have compiled TDAS in a form that can be run within the IDL virtual
machine, with no IDL license required. In this environment, the IDL command line is not available; everything must be done
through the TDAS Graphical User Interface (GUI).
The IDL VM software itself can be obtained from the Exelis web site, www.exelisvis.com. You will need to register on thatsite in order to obtain access to their IDL download area. It may be necessary to download the full version of IDL, which
includes the IDL virtual machine program. If older versions of IDL are available for download, we recommend IDL 7.06 as
the best environment for running TDAS. However, the latest version (8.2.2 at this writing) should also work, although someusers will need to adjust layouts and font sizes to obtain publication-quality plots.
Once you have the IDL VM software downloaded and installed, you will need to download the IDL-VM version of TDAS
from the Software area of the THEMIS web site:
http://themis.ssl.berkeley.edu/software.shtml
It is distributed as a zip file, which will need to be unpacked.
To run TDAS in the IDL virtual machine,
1. Start the IDL virtual machine executable
2. Click through the splash screen to get to the file selection dialog
3. Navigate to the TDAS installation
4. Go into the thm_gui_new directory and click on thm_gui.sav
This should bring up the main screen of the THEMIS GUI. From this point you should be able to load, plot, and analyze data
through the GUI, as documented in the TDAS Users Guide.
If you have problems or questions regarding the TDAS software in the virtual machine, please use the Science Help Request
form on the THEMIS web site:
http://themis.ssl.berkeley.edu/thm_sci_help_request_form.shtml

0.0 How to Get Started
Assuming you have the software installed, the best place to start is with a crib sheet. The crib sheets in the
idl/themis/examples folder give end-to-end examples of how to load, process and plot the data available for a given
THEMIS instrument. Cribs for general purpose plotting using tplot may be found in idl/ssl_general/examples/.

0.0.0 Crib Sheets in idl/themis/examples
thm_crib_asi
thm_crib_calc
thm_crib_cotrans_lmn
thm_crib_dproc
thm_crib_efi
thm_crib_esa_da

Crib sheet for loading and displaying All Sky Imager and Keogram data.
Crib sheet for the mini-language program ‘calc’
Crib sheet for coordinate transform to ‘LMN’ coordinates
Crib sheet for testing some common data processing routines
Crib sheet for Electric Fields Instrument waveforms.
Crib sheet for analysis of ESA particle distributions

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126thm_crib_esa_moments
thm_crib_esa_read_gmoms
thm_crib_part_slice2d
thm_crib_export
thm_crib_fac
thm_crib_fbk
thm_crib_fft
thm_crib_fgm
thm_crib_fit
thm_crib_gmag
thm_crib_gmag_greenland
thm_crib_gmag_maccs
thm_crib_make_ae
thm_crib_mom
thm_crib_mva
thm_crib_overplot
thm_crib_part_products
thm_crib_part_slice2d
thm_crib_plotxy
thm_crib_plotxyvec
thm_crib_plotxyz
thm_crib_scm
thm_crib_sst
thm_crib_sst_contamination
thm_crib_state
thm_crib_tplot_overlay
thm_crib_tplotxy
thm_crib_trace
thm_crib_twavpol
thm_map_examples

Crib sheet for ground processed ESA moments
Crib sheet for reading ground-processed ESA moments
Crib sheet for creating 2D ‘slices’ of ESA/SST particle distributions
Crib sheet for exporting THEMIS data and/or plots in common data formats.
Crib sheet showing how to transform into field-aligned coordinates
Crib sheet for Filter Bank.
Crib sheet for on-board Fast Fourier Transform data.
Crib sheet for Flux Gate Magnetometer
Crib sheet for on-board Fields Spin Fit
Crib sheet for GMAG, including wavelet demo.
Crib sheet for GMAG data from TGO/DTU networks.
Crib sheet for GMAG data from the MACCS network.
Crib sheet for creating geomagnetic AE indices
Crib sheet for on-board particle Moments.
Crib sheet for transformation into minimum variance analysis coordinates
Crib sheet for creating overview plots
Crib sheet for generating particle spectra & moments
Crib sheet for generating velocity slice distributions (ESA & SST)
Crib sheet with for plotxy, which creates 2d plots for 3d quantities
Crib sheet for plotxyvec, which plots arrow on plotxy, plotxyz images
Crib sheet with for plotxyz, which creates isotropic spectrographic plots
Crib sheet for Search Coil Magnetometer
Crib sheet for Solid State Telescope (SST).
Crib sheet for SST contamination removal
Crib sheet for State data – loading and plotting probe position data
Crib sheet showing how to overlay spectra on other spectra
Crib sheet with for tplotxy; creates 2d plots for 3d quantities in tplot
variables
Crib to demonstrate use of Tsyganenko trace routines, and means forgenerating plots of trace routines.
Crib for generation of wave polarization from SCM (Search Coil
Magnetometer) data
Examples for mapping Ground Base Observatories (GBO)

Run any of the crib sheets by typing:.run <thm_crib_xxx>

When execution stops at a 'stop' command in the crib sheet, type:.c

to continue.
Alternatively, you can cut and paste from the crib sheet to the command line.
The crib sheet thm_map_examples is not in the same format as the other crib sheets: it defines some procedures which you
can then run for yourself, or use as examples for your own code.

0.0.0 IDL Documentation for TDAS
To find more information on any of the TDAS routines used in the crib sheets, use:The source code of the crib sheets, which is included in the idl/themis/examples directory of the software
distribution.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126





HTML help included with the software distribution: point your web browser to idl/_tdas_doc.html at the location
where your TDAS software is installed locally.
IDL XDOC widget. At the IDL prompt, type:xdoc
IDL doc_library procedure. At the IDL prompt, type:
doc_library, ‘command_name’

Here is a sample THEMIS routine documentation header:;+;Procedure: THM_LOAD_GMAG,; thm_load_gmag, site = site, datatype = datatype, trange = trange, $;level = level, verbose = verbose, $;subtract_average = subtract_average, $;subtract_median = subtract_median, $;varname_out = varname_out, $;subtracted_values = subtracted_values, $;downloadonly = downloadonly, $;valid_names = valid_names;keywords:; site = Observatory name, example, thm_load_gmag, site = 'bmls', the;default is 'all', i.e., load all available stations . This;can be an array of strings, e.g., ['bmls', 'ccmv'] or a;single string delimited by spaces, e.g., 'bmls ccnv'; datatype = The type of data to be loaded, for this case, there is only;
one option, the default value of 'mag', so this is a;placeholder should there be more that one data type. 'all';
can be passed in also, to get all variables.
; TRANGE= (Optional) Time range of interest (2 element array), if;
this is not set, the default is to prompt the user. Note;that if the input time range is not a full day, a full;
day's data is loaded; level = the level of the data, the default is 'l2', or level-2;
data. A string (e.g., 'l2') or an integer can be used. 'all';
can be passed in also, to get all levels.
; /VERBOSE : set to output some useful info
; /SUBTRACT_AVERAGE, if set, then the average values are subtracted;
from the loaded variables,; /SUBTRACT_MEDIAN, if set, then the median values are subtracted;
from the loaded variables,; varname_out= a string array containing the tplot variable names for;the loaded data, useful for the following keyword:; subtracted_values = returns N_elements(varname_out) by 3 array;
containing the average or median (or 0) values;
subtracted from the data.
; /downloadonly, if set, then only download the data, do not load it;
into variables.
; no_download: use only files which are online locally.
; relpathnames_all: named variable in which to return all files that are;
required for specified timespan, probe, datatype, and level.
;
If present, no files will be downloaded, and no data will be loaded.
; /valid_names, if set, then this will return the valid site, datatype;
and/or level options in named variables, for example,;;
thm_load_gmag, site = xxx, /valid_names; get_support_data = does nothing. present only for consistency with other;load routines;;Example:; thm_load_gmag, site = 'bmls', trange =; ['2007-01-22/00:00:00','2007-01-24/00:00:00'];;Written by: Davin Larson, Dec 2006
; 22-jan-2007, jmm, jimm@ssl.berkeley.edu rewrote argument list, added

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

; keywords,; 1-feb-2007, jmm, added subtract_median, subtracted_value keywords; 19-mar-2007, jmm, fixed the station list...
; $LastChangedBy: jimm $; $LastChangedDate: 2007-05-21 19:44:54 -0400 (Mon, 21 May 2007) $; $LastChangedRevision: 678 $; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/branches/QA/idl/themis/ground/thm_load_gmag.pro $;-0.0 Software Functions
This section describes the functionality of the THEMIS software. The examples are given using the command line interface,
but the concepts are the same for the GUI.

0.0.0 Loading THEMIS Data
The THEMIS software is set up to work with Level 1 THEMIS data by default. Level 1 data are loaded from CDF files andcalibrated, creating data quantities which are the same as the Level 2 products. GMAG (ground magnetometer) data are by
default loaded from Level 2 files. ESA (Electrostatic Analyzer) data are loaded from Level 0 files. With the exception of ESA
data, TDAS does not use Level 0.
It is also possible to load raw Level 1 data. Calibration routines are available for those who want to have full access tointermediate outputs, settings of calibration parameters, diagnostic outputs, etc.
The THEMIS software automatically creates a local data cache which mirrors the structure of the THEMIS data archive. The
software is written such that the default settings will work for the majority of users. The location of the THEMIS dataarchive is also found automatically by the software.
To download some data and load it into IDL, specify a time range via the “timespan” command and the type of data forloading. If the data does not exist locally, it will be downloaded automatically before it is loaded into IDL.
At the IDL prompt, type:timespan, '2006­11­11', 1, /day

Then, use one of the thm_load commands, e.g.
thm_load_gmag, site='ccnv'

The example above used the “site” keyword to denote the ground station for the data to be loaded. For THEMIS probe data,
use the “probe” keyword. Note that all of the listed keywords are not present for all of the different load routines. This isparticularly true for the ESA, SST and MOM load routines which are under development.
List of routines for loading data:
thm_load_asi
Load All-Sky Imager data for any ground station (by keyword) or all available.
thm_load_ask
Load All Sky Keogram data for all observatories.
thm_load_bau
Load BAU housekeeping data
thm_load_efi
Load efi waveforms
thm_load_esa
Load ElectroStatic Analyzer data (for L2 esa data)
thm_load_esa_pkt
Load Level 0 ESA data
thm_load_fbk
Load Filter Bank data
thm_load_fft
Load on-board Fast Fourier Transform data.
thm_load_fgm
Load fgm waveforms (choice of fgl, fgh…)
thm_load_fit
Load On-Board Fields Spin-Fit data
thm_load_scm
Load Search Coil Magnetometer data.
thm_load_gmag
Load ground magnetometer data for any ground station.
thm_load_goesmag
Load Level 2 magnetometer data from GOES satellites (g10, g11, g12)
thm_load_hsk
Load IDPU housekeeping data – all or one by keyword.
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126thm_load_mom
Load on-board moments data
thm_load_scm
Load SCM waveform.
thm_load_slp
Load solar and lunar attitude and ephemeris data
thm_load_spin
Load THEMIS spin model parameters
thm_load_sst
Load Solid State Telescope data.
thm_load_state
Load Orbit and Attitude data
thm_part_load
Load ESA/SST data for producing derived productsStandard Load Procedure Keywords:
SITE
string: ground station name, or a list of ground station names, or ‘all’
PROBE
string: probe name, or a list of probe names, or ‘all’. e.g. ‘a b c’
DATATYPE
type of CDF variable for the given instrument.
LEVEL
Level of data file to load: 'l1' or 'l2' default is usually ‘l1’.
TYPE‘raw’ or ‘calibrated’. applies to ‘l1’ data only. ‘Calibrated’ is the default.
VALID_NAMES
Return valid names for DATATYPE, SITE, PROBE, and LEVEL
VERSION
Version of CDF file to load (useful for STATE data): 'v01', 'v02'
GET_SUPPORT_DATA Get support data quantities from CDFs well as data quantities, only used for ‘l1’
data.
SUFFIX
A string to be appended to the variable names for input data. Note that the
SUFFIX keyword is not applied to support data quantities which are loaded via
the GET_SUPPORT_DATA keyword; those variable names will remain withouta suffix.
CDF_DATA
Return a structure containing data and metadata from CDF.
Special note regarding experimental eclipse spin model keywords for THEMIS load routines
During normal operation of the THEMIS probes, data from the BAU sun sensor is used to keep track of the spacecraft's
orientation in the spin plane with respect to the sun, so that certain data products (spin fits, particle distributions, andmoments) can be produced in DSL coordinates. When the probe is in shadow, the BAU sun sensor is inoperative, and theonboard spin sectoring clock "freewheels" through the eclipse, using the last known spin period. But as the spacecraft cools
down, thermal contraction changes the moment of inertia, causing the spin rate to increase. As a result, the onboard DSL data
products drift out of sync with the true sun direction, causing a time-varying rotation in the spin plane with respect to "true"
DSL. The waveform data products are also affected, because the despinning process to transform from sensor coordinates to
DSL coordinates depends on the BAU sun sensor data.
This release of TDAS introduces a capability for correcting the probe data products for this eclipse-induced rotation in thespin plane. The FGM team has developed code to post-process the BAU sun sensor data, using a model of the eclipse spin
behavior to interpolate through the gaps during shadow periods, to produce an eclipse spin model with much better accuracy
than the BAU-only spin model. Both spin models are now available in the L1 state CDFs, and some THEMIS load routines
now take a use_eclipse_correction keyword to enable the onboard "pseudo-DSL" products to be corrected to somethingcloser to the true DSL coordinate system.
For waveform data (thm_load_fgm, thm_load_scm, thm_load_efi), spin fit and onboard moment data
(thm_load_fit, thm_load_mom), SST data (thm_load_sst), and ESA data (thm_load_esa_pkt, thm_load_pe??
routines), the eclipse corrections are enabled by adding the keyword value "use_eclipse_corrections=2" to the loadcommand. “use_eclipse_corrections=0” disables the corrections. . “use_eclipse_corrections=1” is used for
determining the corrections, and is for THEMIS SOC internal use only.
If eclipse corrections were enabled while loading the 3D ESA and SST particle data, they will automatically be used by
thm_part_moments for ground-processed moments.
These keywords are only effective when calibrated L1 data is requested. They have no effect for times when the spacecraft isin sunlight. The default behavior, when these keywords are not used, is to disable the eclipse corrections.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Since these eclipse spin model corrections are still considered experimental, and are under active development, users should
be aware of the following considerations:While testing has shown that the eclipse corrections are greatly improved compared to the BAU-only spin model,
we are not prepared to offer an estimate of the spin plane angular errors remaining in the corrected data.
The eclipse corrections are not enabled for any of the L2 data products at this time.
Users should consult the THEMIS/ARTEMIS science team before drawing any scientific conclusions from
eclipse-corrected data.

0.0.0 General Conventions: variable name construction and reference
The command line interface of TDAS provides a general interface for referring to a data quantity, based on the IDL input
keywords for the appropriate load routine. The lists in these keywords can be arrays of strings, or scalar strings containing
space-separated lists. For example:
PROBE: specifies the probe, or probes of interest: ‘a b c’ or [‘a’, ‘b’, ‘c’]
DATATYPE: specifies the type of data, for a given instrument: corresponds to a variable name in the CDF file
SUFFIX: a suffix to the variable name
The data is loaded into variables with the following name:tha_bbb_suf
where “a” is the probe designation, “bbb” is the datatype designation, and “_suf” is the optional suffix.
For some data, a midfix is added before the datatype: e.g. for all STATE and HSK data a midfix is added before the datatype
it in the variable name. e.g. tha_state_pos
In this example, the datatype is POS, but the state_ midfix had been added before it in the name.
The various thm_load and thm_cal (calibration) routines, as well as thm_cotrans (coordinate transform) accept the above
keywords to determine which data to operate upon.
General-purpose routines (e.g. tplot, described below) contained in TDAS can refer to sets of variables using glob-stylepatterns. For example:
th?_*_raw
refers to data for all probes for all non-state data types, which have the “_raw” suffix;
th[ab]_fg?
refers to FGL, FGH, and FGE for probes A and B.

0.0.0 Plotting the Data
0 .0 .0 .0 Plotting with Tplot
As previously mentioned, documentation that explains how to use these routines in detail can be found in the headers at the
beginning of the procedure files, in the cribs, or by using the ‘xdoc’ or 'doc_library' command. For example:
doc_library,'tplot'

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Plotting routines:
tplot
tplot_names
tplot_options
optionstlimit
xlim
ylim
zlim
get_data
store_data
Cribs:

General purpose time plotting utility for creating plots of lines and spectrograms.
Lists current stored data names that can be plotted with the TPLOT routines.
Sets global options for the tplot routine.
Sets options for specified tplot variable(s)Zoom into or out of a tplot.
Sets x-axis limits for specified tplot variable(s)Sets y-axis limits for specified tplot variable(s)Sets z-axis limits for specified tplot variable(s)Get data out of a tplot variable into a structure containing a time tag array and a data array.
Store a data array structure into a tplot variable.

(In the following, the path shown is relative o the local TDAS directory.)
idl/ssl_general/examples/thm_crib_tplot.pro
idl/ssl_general/examples/thm_crib_tplot_range.pro
idl/ssl_general/examples/thm_crib_tplot_layout.pro
idl/ssl_general/examples/thm_crib_tplot_export_print.pro
idl/ssl_general/examples/thm_crib_tplot_annotation.pro

tplot – Use to create a time series plot of user defined quantities.
idl/ssl_general/tplot/tplot.pro
tplot, 1
tplot, [1,2,3]
tplot,'amp slp flx2'
tplot, ‘th?_fgh’
tplot,'flx1',/ADD_VAR
tplot
tplot,var_label=['alt']; Plot the first quantity (as revealed by calling tplot_names); Plots a stack plot of the first 3 data quantities.
; Plots the named quantities; Plots a stack plot of High Rate Flux Gate Magnetometer data for all; available probes.
; Add the quantity 'flx1' to previous plot.
; Re­plot the last variables.
; Put Distance labels at the bottom.

tplot_names – Use to print a list of acceptable names to plot and to get info on those tplot variables.
idl/ssl_general/tplot/tplot_names.pro
tplot_names,'*3dp*'
tplot_names,'ehspec',/verbose
tplot_names,/time_range; display all names with '3dp' in the name; print out more info on the data structure in ‘ehspec’; print out the time range for tplot var in memory

tplot_options – Use to control the plotting of all tplot variables (e.g. the title, margins, etc. of the plot window).
idl/ssl_general/tplot/tplot_options.pro
tplot_options,'title','My Data'
tplot_options,'xmargin',[10,10]
tplot_options,'ymargin',[4,2]tplot_options,'position',[.25,.25,.75,.75]
tplot_options,'wshow',1
tplot_options,'version',3
tplot_options,'window',0
tplot_options,/help
tplot_options,get_options=opt
tplot_options,'ygap',0.0; Set title; Set left/right margins to 10 characters; Set top/bottom margins to 4/2 lines; Set plot position (normal coord); de­iconify window with each tplot; Sets the best time ticks possible; Makes tplot always use window 0; Display current options; get option structure in the variable opt.
; eliminate the vertical spacing between panels

options – Use to control the plotting of one or more tplot panels. This procedure can be used to set all IDL plotting keyword
parameters (i.e. psym, color, linestyle, etc) as well as some keywords that are specific to tplot (i.e. panel_size, labels, etc.)
idl/ssl_general/tplot/options.pro
options, ‘tvar_name(s)’,'panel_size',1.5 ; Change the relative panel width

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

options, ’tvar_name(s)’,'labflag',­1
options, ’tvar_name(s)’,'labflag',0
options, ’tvar_name(s)’,'spec',1
options, ’tvar_name(s)’,'y_no_interp',1
options, ’tvar_name(s)’,'y_no_interp',0
options, ’tvar_name(s)’,'ystyle',1
options, ’tvar_name(s)’,'ystyle',0
options, ’tvar_name(s)’,'spec',0; Set evenly spaced labels; No labels; set option to produce a spectrum plot
; prevent y­axis interpolation; allow y­axis interpolation; force exact y­axis limits; return to autoranging; change to multi­line plot

tlimit – Define a time range for tplot.
idl/ssl_general/tplot/tlimit.pro
tlimittlimit,'12:30','14:30'
tlimit, 12.5, 14.5
tlimit,t,t+3600
tlimit,/FULL
tlimit,/LAST; Use the cursor to set time range; t must be set previously; zooms to full time range available; previous limits

xlim, ylim, zlim – Sets plotting limits for plotting routines. Zlim typically applies to the brightness scale for spectrograms.
idl/ssl_general/tplot/xlim.pro
idl/ssl_general/tplot/ylim.pro
idl/ssl_general/tplot/zlim.pro
xlim
ylim,'Ne',.01,100,1
zlim,'ehspec',1e­2,1e6,1xlim,lim,­20,100; Set "TPLOT" limits using the cursor.
; Change limits of the "TPLOT" variable 'Ne'.
; Change color limits of the "TPLOT" variable 'ehspec'.
; create a variable called lim that can be passed to a
; plotting routine such as "SPEC3D".

Tplot variables can be stored in files using tplot_save and loaded using tplot_restore. You can also retrieve data from tplot
variables and manipulate it in IDL.
get_data, 'thc_pser_en_eflux', x, y, z
print, z[0,*]You can find these codes at idl/ssl_general/tplot/get_data.pro and idl/ssl_general/tplot/store_data.pro

0.0.0.0 Plotting with Plotxy
Plotxy and plotxyz are routines that are designed to plot two dimensional projections of three dimensional vector data or cuts
across a three dimensional space. The ratio of lengths of the axes will be maintained so that relationships between the axes
will not be distorted. Another way to say this is that they generate isotropic line plots. Any possible projection can be
specified by naming the two axes of the data that identify a plane or by providing a matrix whose columns define a genericplane. The plot will contain a projection of the data within the plane defined by the span of the axes or the span of the twocolumns of the matrix. Plotxy is used to plot array data and tplotxy is used to plot tplot variables. These routines are usefulfor plotting spacecraft position data and traces of magnetic field lines. Plotxyvec can be used to plot arrows over plotxy,
tplotxy and plotxyz plots.
Plots that are generated by plotxy, plotxyz, tplotxy, and plotxyvec can be arranged in the same window. Plotxy takes an arrayof vectors as an input. Tplotxy takes the name or names of tplot variables to be plotted as an input.
Documentation that explains how to use these routines in detail can be found in the headers at the beginning of the procedure
files, in the cribs, or by using the “doc_library” IDL command. For example, try: doc_library,'plotxy'. The plots
generated by these routines can be exported in the same ways that tplot plots can be exported.
The routines can be found at:
idl/ssl_general/tplot/plotxy.pro

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

idl/ssl_general/tplot/tplotxy.pro
idl/ssl_general/tplot/plotxyvec.pro
Cribs for the routines can be found at:
idl/themis/examples/thm_crib_plotxy.pro
idl/themis/examples/thm_crib_tplotxy.pro
idl/themis/examples/thm_crib_plotxyvec.pro
The following example demonstrates how to plot the orbit of THEMIS C.
;this sets the time range and loads the position datatimespan,'2008­04­02'
thm_load_state,probe='c d',coord='gse';set up a window for the plots
window,xsize=600,ysize=300;convert data from km to earth radii
tkm2re,'th?_state_pos',/replace;this will set up a two plot panel one will contain the x vs y plot of the spacecraft orbit;the other will contain the x vs z plot of the spacecraft orbit. The x axis will run from right toleft on the second plot.
tplotxy,'thc_state_pos thd_state_pos',multi='2 1',colors=[2,4]tplotxy,'thc_state_pos thd_state_pos',versus='xrz',/add,colors=[2,4]0.0.0.0 Plotting with Plotxyz
Plotxyz is a routine that is designed to plot isotropic or non-time-series spectrograms. Generally, plotxyz is used inconjunction with bin2d to generate a two dimensional array that contains values that are a function of two other variables.
For example, plotxyz can be used to generate a spectrogram of pressure vs. x-y position. Many of the options for plotxyz andplotxy are the same, but there is no version plotxyz that works directly with tplot variables. (I. e., there is no “tplotxyz”.)
Plotxyz, plotxy, tplotxy, and plotxyvec plots can be arranged in the same window together. Plotxyz requires three inputs, andaccepts many different options keywords. The first input is an M element one dimensional array that contains the values ofthe x axis. The second input is an N element one dimensional array that contains the values of the y axis. The third input
contains an MxN element two dimensional array that stores the z value of each combination of x and y.
Documentation that explains how to use these routines in detail can be found in the headers at the beginning of the procedure
files, in the cribs, or by using the 'doc_library' command. For example: doc_library,'plotxyz'. The plots generated bythis routine can be exported in the same ways that tplot plots can be exported.
The routines can be found at:
idl/ssl_general/tplot/plotxyz.pro
idl/ssl_general/misc/bin2d.pro
The crib for the routines can be found at:
idl/themis/examples/thm_crib_plotxyz.pro
The example below shows how to generate a spectrogram of density versus position using plotxyz.
;load the data and convert to distance in RE
timespan,'2008­02­14'
thm_load_state,probe='a',coord='gsm'
thm_load_mom,probe='a'tKm2Re,'tha_state_pos',/replace
get_data,'tha_state_pos',data=d_pos

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126get_data,'tha_peim_density',data=d_den;interpolate the data onto the same time gridden = interpol(d_den.y,d_den.x,d_pos.x);bin the data using bin2d;the '$' in the command below shows IDL that this is a single command that is printed on two lines.
;if you want you can remove the '$' and print the next two lines on a single line in IDL
bin2d,d_pos.y[*,0],d_pos.y[*,1],den,binum=20,averages=averages,$
xcenters=x_centers,ycenters=y_centers,flagnodata=!values.d_nan;plot the spectrogram
plotxyz,x_centers,y_centers,averages,xtitle='X [RE GSM]',ytitle='Y [RE GSM]',/grid0 .0 .0 .0

Angular Spectra and Moments

The routine thm_part_products.pro can be used to produce spectrograms and moments from THEMIS particle data. For
detailed command line usage see:projects/themis/examples/basic/thm_crib_part_products.pro
Spectrograms are produced by averaging across the dimension that are not being represented (e.g. a phi spectrogram averages
over energy and theta). Limits to phi, theta, and energy ranges will affect all products, including moments. Limits togyrophase and pitch angle ranges will only affect field aligned products and energy spectrograms. The exact field aligned
coordinate system can be selected as well as the resolution of the interpolated grid in the new coordinates.
To remove ESA background see:projects/themis/examples/advanced/thm_crib_esa_bgnd_remove.pro
To remove SST contamination see the following section (2.5.3.5)
Related IDL Routines:
Main Routines:
thm_crib_part_products
thm_part_load
thm_part_products

Crib sheet detailing command line usage
Loads particle data (Produces spectrograms and moments

Related Contamination Removal Routines:
thm_crib_sst
thm_crib_esa_bgnd_remove

Removal of SST contamination
Removal of ESA background

0.0.0.0 Removing SST Contamination
Sun contamination, electronic noise, and the on-board mask can be removed by passing various arguments to
thm_part_getspec, thm_part_moments, & thm_part_dist_array.pro These operations may only be performed on ground data(not for on-board moments) and they only work on full or burst distribution data. A crib describing the operations in detailcan be found at:
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126themis/examples/thm_crib_sst_contamination.pro
All three routines use the same set of arguments to remove contamination. Contamination is usually easier to see in angularplots. Moreover, data at different times may require slightly different settings to effectively remove the contamination, so it isoften useful to generate angular plots with thm_part_getspec to test that the contamination is being removed effectively
before generating moments. A basic description of the techniques used to remove the types of contamination is below:
Sun Contamination:
The routine fills in all the data that is more than some statistical limit from the data. The statistic that is used, the limit, andthe method of filling can be set by the user. Linear interpolation along phi has been found to be an effective method forfilling and the standard deviation from the median is effective at identifying contamination. A limit of 2.0 is the default.
If the contamination isn't being removed, lowering the limit or changing the methods used can sometimes be helpful.
On-Board-Masking:The on-board mask is identified by finding the phi bin that has a 0 value for a given percentage of the time interval.
Generally a value of 100% or 99% is very effective. 99% is often better because in some data sets that mask will not always
be 0, due to errors in transmission. The phi bin is then filled in using the user specified fill method. Linear interpolation
across phi generally works quite well.
Electronic Noise:Electronic noise is removed via a 2-step process. First the user generates an angular plot of the contaminated data of interest.
They then use edit3dbins to examine the relative values of the contaminated bins during at a time when flux is nearest to
0 in all angles. They select the bins that look contaminated during this time and pass the list of contaminated bins into
thm_part_getspec, thm_part_moments, or thm_part_dist_array along with the time interval of the
low flux region. The routines then subtract the values of selected bins during the low flux interval from those bins over theentire interval.

0 .0 .0 .0

Overlaying Spectrograms Using Tplot Pseudovariables

Pseudovariables are a little known tplot feature that allows one or more tplot variables to be stored in a single tplot variable
using the store_data command. For example,
store_data, 'pseudo_var', data=['tplot_var1','tplot_var2']
allows the user to plot the tplot variables tplot_var1 and tplot_var2 together in the same panel with the command:
tplot, 'pseudo_var'
One application of this feature is the merging of multiple spectrograms into a single plot. For example, one can combine fulland burst mode spectrograms into a single plot by overlaying the burst mode data on top of the full mode data. Below is an
example using ESA full and burst ion energy spectra:
thm_part_products, probe='a', datatype='peif', trange=['07-03-23/10:30','07-03-23/12:40']
thm_part_products, probe='a', datatype='peib', trange=['07-03-23/10:30','07-03-23/12:40']
Now create a pseudovariable that stores the full and burst data in one tplot variable:
store_data, 'tha_comb', data=['tha_peif_eflux_energy','tha_peib_eflux_energy']
The next step is to set the y-axis and z-axis limits of the pseudovariable. This ensures that the full and burst mode data will
have the same color and vertical scale.
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

ylim,'tha_comb',5,23000 ; set y­axis limits
zlim,'tha_comb',10,3e6 ; set all spectra to same color scale

0 .0 .0 .0

Particle Distribution Slices

Particle distributions from the ESA and SST are used to generate 2D slices of the particles’ three-dimensional velocity
distributions. The slices show contoured particle data (in counts or other units) plotted against their Cartesian velocities in
the given coordinates. Slices are created using one of three methods:
Geometric (Default): Points on the slice plane are assigned the value of the bin into which they fall. Values areaveraged in cases of overlapping bins or when the slice plane is coplanar with a bin's boundary. Slices can be cut inany arbitrary plane by specifying a normal vector and offset from zero. This method also allows for multiple
distributions to be used to create a single slice. High resolution plots can resolve the exact boundaries of each bin.
(Examples Below)
2D Linear Interpolation: Data points within the specified theta or z-axis range are projected onto the slice plane andlinearly interpolated onto a regular 2d grid. Slice orientation is limited to xy-axis cuts in the available
coordinates/rotations. (This method was taken from thm_esa_slice2d.pro)
3D Linear Interpolation: The entire set of scattered data is linearly interpolated onto a 3D volume and two
dimensional slices are pulled from the volume. Slices can be cut from the volume in any arbitrary plane byspecifying a normal vector and offset from zero (along the normal). Gaps in the data may be interpolated acrossusing this method, making it more suited for denser data (better for ESA than SST).
Velocity slices can be created using the command line routines outlined in the crib sheet,projects/themis/examples/basic/thm_crib_part_slice2d.pro
or by using the slices GUI. The GUI may be accessed through the main THEMIS GUI under the Analysis menu (see section2.7) or from the command line by entering:
thm_ui_slice2d
The GUI allows multiple slices within a given time range to be created, plotted, and exported with ease. When using thegeometric method up to four distributions can be selected from the Distribution Type list.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 1.5.3.7aCreating slices:
Coordinates and Slice Plane Orientation:
Coordinates (keyword = coord)
The data is first transformed into the requested coordinate system. The default is DSL (no transformation); GSM
and GSE coordinates are also available.
Rotation (keyword = rotation)
The orientation of the slice plane is specified by the Rotation options. Each rotation defines a new set ofcoordinates; the slice plane will be along the x-y plane of the specified coordinate system. Descriptions of each
option can be viewed by selecting the “?” button in the GUI and are also present in the crib sheet. The default
selection applies no rotation, thus using the x-y plane of the coordinates specified by the previous option (i.e. DSL,

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

GSM, or GSE). If 2D interpolation is being used then the given theta or z-axis limits will be applied in the rotatedcoordinates.
User Specified Orientation (keyword = slice_norm)
This option allows the user to specify the exact orientation of the slice plane by specifying the plane’s normal. The
normal vector is interpreted as being in the coordinates defined by the Coordinates and Rotation options. For
example, a normal of <0,1,0> with an “xGSE” rotation will cut a slice along the x-z plane of the coordinates definedby the “xGSE” rotation. This options is not available for 2D interpolation.
Data/Plot Resolution
Slice Resolution (keyword = resolution)
The resolution (number of points per dimension) of the final plot is determined by the Resolution spinner.
Interpolation methods default to lower resolutions (~ 50-150). When using the geometric method high resolutions(>350) can resolve bin boundaries (see example above). Increasing the resolution will slow the default method
some and will greatly slow 3D interpolation.
Regridding (keyword = regrid)
Initially each bin is represented by one data point whose phi, theta, and energy values are those of the bin’s center.
Regridding interpolates the data to a denser grid to using the nearest neighbor. This is primarily useful in cases
where 2D interpolation is unable to select enough points or is missing data. The geometric method ignores thiskeyword.
Slider Bar (GUI only)
When multiple slices are created the slider bar just below the main options (figure 2.5.3.7c) can be used to quickly
scroll back and forth among the plots.
Exporting (see crib sheet for command line use)
The current plot may be exported to .png or .eps format using the Export button. To export all loaded plots use theExport All button. The start time of the slice will automatically be printed into the file name wherever “(slice_time)”
appears.
Contamination/Background Removal
The slices load routine thm_part_dist_array accepts the same ESA background removal keywords as
thm_part_load. SST sun contamination will be removed automatically, however the user may specify whichbins to interpolate over if the default set is inadequate. These options are detailed in the two crib sheets noted below
and in Section 1.5.3.5 above. Common options are also found in the GUI under the Contamination tab.
Related IDL Routines:
Main Routines:
thm_crib_part_slice2d
thm_part_dist_array
thm_part_slice2d
thm_part_slice2d_plot

Crib sheet detailing command line usage
Loads array of particle distributions
Creates slice from array of particle distributions
Plots slice

Related Contamination Removal Routines:
thm_crib_sst
thm_crib_esa_bgnd_remove

Removal of SST contamination
Removal of ESA backgroundNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0 .0

Combined particle data products

A combined ESA and SST data product can be produced with the routine thm_part_combine.pro. The combined
product is created by interpolating across the energy gap between the two instruments. A default set of new energy bins isused for the interpolation, but can be specified by the user. SST calibration and contamination removal are applied bydefault, but may also be user controlled. Production of the combined data set can be resource intensive on older systems.
The combined data product can be used with thm_part_prodcuts and thm_part_slice2d to produce spectrograms,
moments, and distribution slices. For examples see:projects/themis/examples/advanced/thm_crib_part_combine.pro

0.0.0

Calibrations and Beyond

Refer to the crib sheet for each instrument for usage of the calibration routines. The interface to the various calibration
routines has not yet been standardized.
Calibration: from L1 data to physical quantities
thm_cal_efi
Calibrates Electric Fields Instrument
thm_cal_fbk
Calibrates Filter Bank
thm_cal_fft
Calibrates FFT data
thm_cal_fgm
Calibrates Flux gate magnetometer
thm_cal_fit
Calibrates spin fit data..
thm_cal_mom
Calibrates all (ESA and SST) on-board moment data
thm_cal_scm
Calibrates SCM data
For working with SST or ESA data and creating ground-processed moments, see the crib sheets.

0.0.0 Geophysical Coordinate Transformations
thm_cotrans can be used to transform a THEMIS vector data quantity stored in a tplot variable to any of the following
coordinate systems:
Abbreviation
Description
SPG
Spinning Probe Geometric
SSL
Spinning SunSensor L-vectorZ
DSL
Despun SunSensor L-vectorZ
GEI
Geocentric Equatorial Inertial
GSE
Geocentric Solar Ecliptic
GSM
Geocentric Solar Magnetospheric
SM
Solar Magnetic
GEO
Geographic Coordinate System
SSE
Selenocentric Solar Ecliptic Coordinate System
SEL
Selenographic Coordinate System
For details and diagrams, see:
http://themis.ssl.berkeley.edu/themisftp/3%20Ground%20Systems/3.2%20Science%20Operations/Science%20Operations%20Documents/thm_soc_110_COORDINATES_20100729.pdf

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The default output of thm_load routines is DSL. The thm_load routines set metadata in the tplot variable that indicate thecoordinate system of the data. Thm_cotrans is aware of this metadata, so it is not necessary to specify an input coordinate
system when calling thm_cotrans.
thm_cotrans usage:;Procedure: thm_cotrans;Purpose: Transform between various THEMIS and geophysical coordinate systems;keywords:; probe = Probe name. The default is 'all', i.e., transform data for all;
available probes.
;
This can be an array of strings, e.g., ['a', 'b'] or a;single string delimited by spaces, e.g., 'a b'; datatype = The type of data to be transformed, can take any of the values;
allowed for datatype for the various thm_load routines. You;
can use wildcards like ? and [lh].
;'all' is not accepted. You can use '*', but you may get unexpected;
results if you are using suffixes.
; in_coord = 'spg', 'ssl', 'dsl', 'gse', 'gsm', or 'gei';
coordinate system of input.
;
This keyword is optional if the coord_sys attribute;is present for the tplot variable, and if present, it must match;the value of that attribute. See cotrans_set_coord, cotrans_get_coord; out_coord = 'spg', 'ssl', 'dsl', 'gse', 'gsm', or 'gei';
coordinate system of output.
; in_suffix = optional suffix needed to generate the input data quantity name:;'th'+probe+'_'datatype+in_suffix; out_suffix = optional suffix to add to output data quantity name. If;
in_suffix is present, then in_suffix will be replaced by out_suffix;
in the output data quantity name.
; valid_names:return valid coordinate system names in named variables supplied to;in_coord and/or out_coord keywords.
;Optional Input Parameters:; in_name Name(s) of input tplot variable(s) (or glob pattern) (space-separated string list or array of strings.); out_name Name(s) of output tplot variable(s). glob patterns not accepted.
;
Number of output names must match number of input names (after glob;
expansion of input names). (single string, or array of strings.);; Example:; thm_cotrans, probe='a', datatype='fgl', out_coord='gsm', out_suffix='_gsm'
Several examples of thm_cotrans usage can be found in thm_crib_fgm.pro.
Note on thm_cotrans, non-inertial coordinate systems, and velocity transformations: If the input and output coordinate
systems are rotating relative to one another (for example, GEI to GSM), the interface to thm_cotrans does not account for thefact that the transformed velocity depends on both the input velocity, and the input position. The velocity offset due to therelative motion of the two coordinate systems will not be applied. For data quantities like particle velocities derived from
THEMIS moment data, this error is insignificant compared to the typical velocities observed. For other quantities, like probe
velocities taken from the STATE data, this approximation would be unacceptable. Therefore, thm_cotrans is not used totransform probe velocities; for this special case, we transform the probe position using thm_cotrans, then numericallydifferentiate the transformed positions to obtain transformed velocities.
A low-level coordinate transformation routine is available if working with simple arrays rather than tplot variables is desired.
cotrans
Transform between geophysical coordinate systems GSE, GEI, and GSM.
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0

Analytical Coordinate Transformations

0.0.0.0 Field Aligned Coordinate Transformations
The TDAS distribution allows transformation of three dimensional vectors into magnetic field aligned coordinate systems.
In order to rotate a vector into a field aligned coordinate system, a coordinate transformation matrix must first be generatedusing /themis/state/thm_fac_matrix_make.pro. This routine allows the generation of transformations for several different
varieties of coordinate system. The primary input to thm_fac_matrix_make is a tplot variable containing the magnetic field
vector, which is typically generated by calling thm_load_fgm.pro. Depending on the type of coordinate system variant
requested, a tplot variable containing the position vector array (generated by calling thm_load_state.pro) may also need tobe supplied via the pos_var_name keyword. The Z axis of the resulting coordinate system (transformation) will always be in
the direction of B field vector. The other_dim keyword determines the requested variant of the transformation by specifying
the second axis for the field aligned coordinate system. The third dimension will always be the cross product of this Z axis
and the other_dim axis. Type doc_library, ‘thm_fac_matrix_make’ at the IDL command prompt to see a descriptionof the different other_dim options or look at the header at the top of the procedure file.
One caveat is that the magnetic field tplot variable must be in GSE, GSM, or DSL coordinates, depending on what
transformation has been selected. Another caveat is that the position tplot variable must be in GEI coordinates, the default
coordinate system of thm_load_state. Also note that the resulting transformation matrices will only correctly transform datafrom the coordinate system of the input variable to the field aligned coordinate system. So if mag_var_name is in DSL
coordinates then you should only use the output matrices to transform other data in DSL coordinates.
Once the transformation matrix has been generated, the vector can be rotated by calling/ssl_general/cotrans/special/tvector_rotate.pro with the transformation matrix as the first argument, and the tplot
variable containing the vector to be rotated into the field aligned coordinate system as the second argument. Below is an
example:timespan, '2007­03­23'
thm_load_state,probe='c', /get_support_data
thm_load_fgm,probe = 'c', coord = 'dsl';smooth the Bfield data appropriately
tsmooth2, 'thc_fgs_dsl', 601, newname = 'thc_fgs_dsl_sm601';make transformation matrix
thm_fac_matrix_make, 'thc_fgs_dsl_sm601', other_dim='xgse', newname = 'thc_fgs_dsl_sm601_fac_mat';transform Bfield vector (or any other) vector into field aligned coordinates
tvector_rotate, 'thc_fgs_dsl_sm601_fac_mat', 'thc_fgs_dsl', newname = 'thc_fgs_facx'

See themis/examples/thm_crib_fac.pro for more examples of how to rotate vectors into field aligned coordinates.

0.0.0.0

Minimum Variance Transformations

The TDAS distribution allows transformation of three dimensional vectors into a minimum variance coordinate systemdefined by an interval or intervals from time series vectors.
This transformation is performed in two steps. First, transformation matrices must be generated from some input time series
vector data. Second, the transformation matrices must be used to transform time series vector data. These input data must be
stored in tplot variables.
The minimum variance coordinate system is defined by generating the covariance matrix for an interval of data. This matrix
is then diagonalized to identify the eigenvalues and eigenvectors of the covariance matrix. The eigenvector with the smallest
eigenvalue will be the direction of the z component of the new coordinate system. The eigenvector with the largest

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

eigenvalue will be the direction of the x component of the new coordinate system. The third eigenvector will be the y
direction of the coordinate system.
The user should note that the resulting transformation matrices will only correctly transform data from the coordinate systemof the input variable to the minimum variance coordinate system. So if the data used to define the coordinate system are in
GSE coordinates then you should only use the output matrices to transform other data that are in GSE coordinates.
The routine to generate the matrices can be found at:
idl/ssl_general/cotrans/special/minvar/minvar_matrix_make.pro
The routine to perform rotations using the minimum variance matrices can be found at:
idl/ssl_general/cotrans/special/tvector_rotate.pro
The cribs for these routines can be found at:
idl/ssl_general/cotrans/special/minvar/mva_crib.pro
idl/themis/examples/thm_crib_mva.pro

Additional documentation can be found in the headers at the top of the procedure
files listed above or by typing 'doc_library' from the idl command prompt. For
example: doc_library,'minvar_matrix_make' will show the documentation for'minvar_matrix_make'.
The example shown here uses fluxgate magnetometer data to generate a minimum variance coordinate system and transformthat data into the minimum variance coordinate system.
;this sets the time interval from which data should be loaded
timespan,'2007­07­10/08:10:00',22,/minute;this loads the data
thm_load_fgm,probe='c',coord='gse';this generates the transformation matrices
minvar_matrix_make,'thc_fgs_gse',tstart='2007­07­10/07:54:00',tstop='2007­07­10/07:56:30';this transforms the data
tvector_rotate,'thc_fgs_gse_mva_mat','thc_fgs_gse',newname='mva_data_day';this sets the axis labels
options,'mva_data_day',labels=['maxvar','midvar','minvar']
options,'mva_data_day',labflag=1;this plots the original data and the transformed datatplot,'thc_fgs_gse mva_data_day'0 .0 .0

Tsyganenko Model

0.0.0.0 Introduction
TDAS allows access to the Tsyganenko Fortran routines via a DLM interface written by Haje Korth. Wrapper code has been
provided in IDL to make use of the Tsyganenko model from IDL quick and easy, even for a user who is not familiar with themodels. Support has been provided for routines that provide the model magnetic field at a user specified set of locations andfor tracing field lines from a position to the ionosphere or the equator. Routines are also available to ease the generation ofmodel parameters from solar wind data. The supported models are the t89,t96,t01 and t04s models.
0.0.0.0 Installation
To run the Tsyganenko routines you will need to install Haje Korth's IDL GEOPACK wrapper for Tsyganenko’s originalFortran code. You will require IDL version 6.4 or above to run IDL_GEOPACK. The current version of the IDL GEOPACK
can be found at the THEMIS website at the following URL: http://themis.ssl.berkeley.edu/idl_geopack_75.zip . PleaseNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

download this file and unzip it. You then need to place two files in your idl dlm directory. If you do not know what yourdlm directory is you can type 'print,!DLM_PATH' from within idl. The first file is called 'idl_geopack.dlm'. The second file
will have a different name depending on your operating system. For windows it will be called 'idl_geopack.dll'. On mostother OS's it will be called 'idl_geopack.so'. This file will be found in a subdirectory of idl_geopack_all_75.zip that is named
for your operating system. After you copy these files two files into your idl dlm directory, all you need to do is restart idl. If
you want to test that the installation worked type 'print,igp_test()'. If this prints out '1', it worked.
These installation instructions can also be found in the software distribution itself in
idl/external/IDL_GEOPACK/README.txt

0.0.0.0 Model Routines
Routines to generate the model field vectors for time series of position vectors can be found in theidl/external/IDL_GEOPACK directory and its subdirectories. These routines take either tplot variables or arrays of times andpositions as arguments. They will produce the model magnetic field. Extensive documentation and examples can be foundin the cribs and in the headers at the tops of the files.
One caveat is that you should remember to set the period keyword equal to a number of seconds equal to the cadence of yourdata to prevent the result vectors from sawtoothing when the geomagnetic dipole is recalculated. If your position data is all ata single time do not worry about the period argument.
The cribs for the routines are:idl/external/IDL_GEOPACK/t89/tt89_crib.pro
idl/external/IDL_GEOPACK/t96/tt96_crib.pro
idl/external/IDL_GEOPACK/t01/tt01_crib.pro
idl/external/IDL_GEOPACK/t04s/tt04s_crib.pro
The tplot based routines are:idl/external/IDL_GEOPACK/t89/tt89.pro
idl/external/IDL_GEOPACK/t96/tt96.pro
idl/external/IDL_GEOPACK/t01/tt01.pro
idl/external/IDL_GEOPACK/t04s/tt04s.pro
The array based routines are:idl/external/IDL_GEOPACK/t89/t89.pro
idl/external/IDL_GEOPACK/t96/t96.pro
idl/external/IDL_GEOPACK/t01/t01.pro
idl/external/IDL_GEOPACK/t04s/t04s.pro
The routine that generates model parameters from solar wind data for the t96,t01, and t04s models is:
idl/external/IDL_GEOPACK/get_tsy_params.pro
Here is a simple example:
timespan,'2007-03-23'
thm_load_state,probe='b',coord='gsm'
tt89,'thb_state_pos',kp=2,period=60
tplot,'thb_state_pos_bt89'

0.0.0.0 Trace Routines
Routines to trace field lines from specified positions can be found in the idl/external/IDL_GEOPACK/trace/ directory. The
routines will use numerical techniques for solving differential equations to trace the magnetic field lines from a set of

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

specified positions to either the equator or the ionosphere. These routines take as arguments either tplot variables storing
three dimensional position data or arrays of vectors and times. They will produce footprints of the field lines on theionosphere or equator. Full traces of the entire field lines can be returned if requested as well. Plotting of traces can often
best be performed with the plotxy or tplotxy plotting routines. The trace routines can trace using any of the four supported
Tsyganenko models. The trace routines work equally well if all positions use the same time and are often used to look atfield lines traced from several positions at a single instant. More extensive documentation and examples can be found in theheaders at the top of files and in the crib.
These routines come with two caveats:
1. As with the model routines, if your data is not all at a single time the period keyword should be set to the cadenceof your data to prevent inaccuracies from geomagnetic dipole recalculations.
2. Solving differential equations can take a long time, so please be patient. Sometimes the field lines will continue
away from the earth an infinite distance or even fall into an infinite loop condition due to the insolubility of thesystem. The latter case only occurs rarely. To avoid the former case the R0 and RLIM parameters can be used to
set maximum and minimum distance cutoffs at which to stop tracing.
An extensive crib for these routines can be found at:
idl/external/IDL_GEOPACK/trace/ttrace_crib.pro
The tplot based routines can be found at:
idl/external/IDL_GEOPACK/trace/ttrace2equator.pro
idl/external/IDL_GEOPACK/trace/ ttrace2iono.pro
The array based routines can be found at:
idl/external/IDL_GEOPACK/trace/trace2equator.pro
idl/external/IDL_GEOPACK/trace/trace2iono.pro
The trace routines can also use the get_tsy_params routine to generate model parameters. It is at:
idl/external/IDL_GEOPACK/get_tsy_params.pro
Here is a simple example:
timespan,'2007­03­23'
thm_load_state,probe='b',coord='gsm'
ttrace2iono,'thb_state_pos',external_model='t89',par=2.0D,/km,period=60
tplotxy,'thb_state_pos_foot'0 .0 .0

Mini Language

A simple scripting language for working with tplot variables has been provided in a form that is usable at the command line
and from within the THEMIS GUI. At the command line you can access this language using the 'calc' command. From
within the GUI you can access this language by selecting “Analysis->Calculate...” from the main GUI window.
Here is an example of a mini language call from the command line:
calc,'”tha_state_pos_avg” = mean(“tha_state_pos”,2)'In the GUI this statement would simply be:”tha_state_pos_avg” = mean(“tha_state_pos”,2)
In both cases the command takes the average of each x,y,z triplet and stores the output in a new tplot variable that has
dimensions time by 1 rather than time by 3(x,y,z). Inside the gui the outer set of single quotation marks is not required.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Examples of command line usage can be found in the file:themis/examples/thm_crib_calc.pro
In all subsequent examples, the 'calc' command will be omitted for brevity.

Data Types:
There are three basic data types in the mini language:
1. Numerical constants.
These are terms like:
1,1B,1.2,­2.3e­4
The mini language accepts numerical constants of any type that IDL accepts with the exception of complex numbers
2. Normal variables
These are terms like:a,b,hello, world
These can be read out of the current IDL session or defined by a mini-language statement. Their only major restriction is thatwhen they are used in the GUI they are only in scope for the duration of a mini-language program.
3. Tplot/Gui variables.
These are terms like:“tha_state_pos”, “thb_fgs_dsl”,”thc_peif_en_eflux”
These are settings, time, and data bound together into a single name. Most of the data in the GUI and from Themis will be
represented in this form. To differentiate these variables from normal variables, they are always denoted with quotes (“ “).
When tplot/gui variables are used in expressions their times and other settings are carried along into the output if the output isalso a tplot/gui type.
Operations between Normal Variables and Tplot/GUI variables, are required to have matching numbers of elements andmatching dimensions to work.

Syntax:Statements in the mini language have one of two basic forms.
1. Basic Assignments:
These are statements like:a = 6374.4“thb_state_pos_re” = “tha_state_pos” / astate_var = “tha_state_pos”
The left hand side can be a normal variable or a tplot/gui variable. The right hand side can contain and combination ofnumerical constants, normal variables, tplot/gui variables, operators, and functions.
2. Compound Assignment/Operations:
These are statements like:“tha_state_pos” /= 6374.4
These have the same form as basic assignments but allow the user to write statements in a more concise form.( the statement
above is equivalent to:“tha_state_pos” = “tha_state_pos” / 6374.4

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Operators:
Operators can be used to combine any of the data types on the right hand of the equation. The only practical limitation on thenumber of operators and data types that can be combined in a single expression is the amount of available memory. These
operators follow the same operator precedence as IDL. Like many languages, the operator precedence can be overridden
using parentheses. The allowable operators are:
~ : logical negation (c = ~a)++ : increment (c = a++) or (c = ++a)­­ : decrement (c = a­­) or (c = ­­a)
­ : subtraction (ex: c = b­a)
+ : addition (ex: c = b+a)
* : multiplication (ex: c = b*a)
/ : division (ex: c = b/a)
^ : exponentiation ( ex: c = b^a)
< : array less­than (ex: c = b < a)
> : array greater­than ( ex: c = b > a)&& : logical conjunction ( ex: c = a && b)|| : logical disjunction ( ex: c = a || b)# : row­major matrix multiplication ( ex: c = a # b)## : column­major(traditional) matrix multiplication ( ex: c = a ## b)
mod : modulus operator (ex: c = a mod b)
and : binary conjunction (ex: c = a and b)
eq : logical equivalence (ex: c = a eq b)
ge : logical greater­than­or­equal­to (ex: c = a ge b)
gt : logical greater­than (ex: c = a gt b)
le : logical less­than­or­equal­to (ex: c = a le b)lt : logical less­than (ex: c = a lt b)
or : binary disjunction ( ex: c = a or b)
xor : binary xor (ex: c = a xor b)() : precedence override ( ex: d = (a + b) * c)Note that any of these operators can be combined with an '=' to create a compound operator/assignment statement in the mini
language.
Also users on the command line can obtain a list of the available operators using the following statement:
calc,operator_list=op
print,op

Functions:
The mini language supports a variety of different functions, but it does not maintain the function/procedure distinction that
IDL does. All routines must be function calls. All routines are built in. There are no user-defined function calls. All
functions have one required argument which can be an element of any data type. Some routines also accept a second optional
argument. The optional argument is always a number. Functions and operations can be combined together in the same waysthat a normal programming language would combine them. Example:“tha_state_pos_log” = log(“tha_state_pos”+10) / 6374.4
The list of available functions follows:
log(x[,base]) : By default, returns a base 10 logarithm on the input.
If [,base] is provided, this function will perform the logarithm

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

using the provided base. Example:“tha_peif_en_eflux_log” = log(“tha_peif_en_eflux_log”,2)ln(x): Returns a natural logarithm of the input.
exp(x[,base]) : By default returns e^x, where e is the natural base. If [,base]is provided, it will return base^x.
sqrt(x): Returns the square root of the input.
abs(x): Returns the absolute value of the input.
sin(x): Returns the sine of the input.
arcsine(x): Returns the inverse sine of the input.
sinh(x): Returns the hyperbolic sine of the input.
cos(x): Returns the cosine of the input.
arcos(x): Returns the inverse cosine of the input.
cosh(x): Returns the hyperbolic cosine of the input.
tan(x): Returns the tangent of the input.
arctan(x): Returns the inverse tangent of the input.
tanh(x): Returns the hyperbolic tangent of the input.
csc(x): Returns the cosecant of the input.
arccsc(x): Returns the inverse cosecant of the input.
csch(x): Returns the hyperbolic cosecant of the input.
sec(x): Returns the secant of the input.
arcsec(x): Returns the inverse secant of the input.
sech(x): Returns the hyperbolic secant of the input.
cot(x): Returns the cotangent of the input.
arccot(x): Returns the inverse cotangent of the input.
coth(x): Returns the hyperbolic cotangent of the input.
min(x[,dim]) : By default returns the single minimum for the entire input.
If [,dim] is provided function will perform the minimum across aparticular dimension of the input. A one dimensional array will
be returned. Typically min(x,1) will perform a minimum acrosstime. min(x,2) will perform a minimum across x,y,z, etc...
max(x[,dim]) : By default returns the single maximum for the entire input.
If [,dim] is provided function will perform the maximum across aparticular dimension of the input.
mean(x[,dim]) : By default returns the single mean for the entire input.
If [,dim] is provided function will perform the mean across aparticular dimension of the input.
median(x[,dim]) : By default returns the single median for the entire input.
If [,dim] is provided function will perform the median across aparticular dimension of the input.
count(x[,dim]) : By default this function returns the count of the number of
elements in the input. If [,dim] is provided this function willcount the elements in each particular dimension of the input andreturn a result with multiple elements.
total(x[,dim]) : By default this function returns the total of the elements in
the input. If [,dim] is provided this function will total theelements in each particular dimension of the input and return aresult with multiple elements.
On the command line, you can use the following command to obtain a list of available functions:calc,function_list=f
print,fNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Error handling:
When using the GUI any errors will be reported in a popup message and in the status bar at the bottom. On the commandline errors are returned through the 'error' keyword. For example:
THEMIS> calc,'illegal statement',error=e
THEMIS> help,e,/str** Structure <89b945c>, 4 tags, length=68, data length=68, refs=1:
TYPE
STRING'error'NAME
STRING'User statement syntax error'
STATE
LONG
3
TOKEN
STRUCT­> <Anonymous> Array[1]The returned statement contains the name of the error type and also returns information about the state of the interpreter thatcan be useful in helping THEMIS programmers diagnose and fix the error.

0 .0 .0

Data Export

You can export your data and/or plots to a variety of data formats.
Examples (please read procedure headers for additional options and information):
Export to ASCII files:
This example writes out Flux Gate Magnetometer Slow Survey data for all probes.
The ext keyword is being used to add the time of the data to the filename.
The dir keyword is being used to set the directory to which the files will be written.
tplot_ascii, 'th?_fgs', trange=timerange(/current), dir='~/thm/waves', ext='_20070520.txt'

Export to PNG:
This example writes a png of the plot displayed by the given tplot command.
tplot,'th?_fgs' ;plots the data
makepng, '~/thm/waves' ;make a png

file called~/thm/waves.png

Export to Postscript:
This example writes a postscript by recreating the previously generated plot.
tplot, ‘th?_fgs'
popen,'~/thm/waves'
tplot
pclose;setup the plot however you want it;start a ps called waves.ps;call with no arguments to replot previous plot
;finalize postscript and save it

Export to Encapsulated Postscript(EPS):This example writes an encapsulated postscript by recreating the previously generated plot.
tplot, 'th?_fgs';setup the plot however you want it
popen, '~/thm/waves', /encapsulated ;start an eps called waves.eps
tplot;call with no arguments to replot previous plot
pclose;finalize eps and save it

0.0.00Configuring the Local Data Cache and Remote Access Behavior

Data locations may be configured at IDL startup (for example, if you want the data to reside in a non-standard location), or
dynamically during an IDL session.
The following table summarizes the controls that can be used, in order of precedence:NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126





!THEMIS system variable
environment variable settings
thm_config.txt (editable with and IDL program: thm_ui_config)

The following table summarizes the settings available:!themis structure
Environment Variable
element
local_data_dir
THEMIS_DATA_DIR
remote_data_dir

THEMIS_REMOTE_DATA_DIR

no_download
force_download
no_update

N/A
N/A
N/A

VerboseN/A

Description
a writable, local directory in which to cache data files. The
default on Unix/Linux/Mac is ‘/disks/data/themis/’. On
windows, the default is ‘C:\data\themis\’
URL to a data archive where THEMIS data can be found. By
default, http://themis.ssl.berkeley.edu/data/themis
1: don’t access remote_data_dir
1: Always download data from remote_data_dir
0: download only if file on server differs or if local file does
not exist.
1: download only if local file does not exist. i.e. no clobber.
level of verbosity for themis commands,
0=silent. Values >1 are generally for debugging.

0 .0 .0 0 .0 Configuration at startup
If you want to change the local_data_dir where data will be stored, run thm_ui_config at the IDL prompt.
Change the setting for Local Data Directory and press ‘Save’; this will save the configuration to be used in all future IDL
sessions. The configuration is saved in a thm_config.txt file in an OS-specific location. Note that this operation only changes
the Local Data Directory for THEMIS data. It does not change the ROOT_DATA_DIR variable defined in Section 1.5.11.
See also Section 2.3.12: Configuration Settings.
0.0.00.0 On-the-Fly configuration
The local data directory location can be changed on-the-fly by setting the !themis.local_data_dir system variable. For
example, when you are on a PC connected to the SSL network, you may choose to use a networked data dir:!themis.local_data_dir = ‘\\justice\data\themis\’

The remote_data_dir structure element can also be updated to a different URL.
If you want the software to use only locally available data, and don’t want the software to try to download data, you can set:!themis.no_download = 1

Note that you can only set the !themis variable in an IDL session after a thm_ command has already been run, or after
explicitly calling thm_init. Using thm_ui_config from the IDL prompt without pressing ‘Save’ in the widget is an alternate
way of setting !themis for the current IDL session.

0.0.00.0 Note for users who connect using a web proxy server
If you are behind a firewall and have to access the net through a Web proxy, set the environment variable 'http_proxy' topoint to your proxy server and port, e.g. (for Unix) 'setenv http_proxy=http://web-proxy-my_instution.edu:3128’.
The URL *MUST* begin with “http://".
This can be done in your IDL_startup file, e.g. IDL > setenv, 'http_proxy= http://web-proxy-server.my_institution.edu:3128’

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.00 Managing Your Data Cache
There currently exist two experimental routines for managing your THEMIS data file cache. These routines serve as an
example of how you will be able to download all data for a given time range with a single command.
1.
thm_file_download – can be used to download all types of THEMIS data for a given time span.
2.
thm_file_cleanup – delete empty directories. This is a function call. It searches the hierarchy and return files
matching a given pattern, sorted by access time. This will only delete files if the “delete files” keyword is set.

0.0.00.0 Define the root_data_dir for ancillary (non-themis) data
To define the root data directory for ancillary (non-themis) data (e.g., wind, ace, goes), which can also be accessed andmanipulated by TDAS software, the default can be changed by setting an environment variable "ROOT_DATA_DIR".
For example the following line can be put in the IDL_STARTUP file:setenv,'ROOT_DATA_DIR=/mydatacache/'or an equivalent setting made in the shell. The default for ROOT_DATA_DIR is ‘/disks/data’ on Unix/Linux/Mac and‘C:\data’ for Windows. It is important to note that the default THEMIS data directory will then be
ROOT_DATA_DIR/themis/. This value can be changed using the methods described in Section 1.5.10.1.

0.0 Software Organization
The themis directory contains THEMIS-specific routines. The general directory (currently named ssl_general) contains
routines which are useful for more than one space-science mission for which THEMIS team members are developing code.
The external directory contains packages developed and maintained by other groups, but which are required for writing (andrunning) some of the THEMIS and/or general routines.
The idl directory of the distribution includes the following files and sub-directories.

_tdas_doc.html
themis/ssl_general/

Documentation in HTML format, including alphabetical list of all routines.
setup_themis
Sample setup script for csh (UNIX)
ground/routines for loading, processing and plotting ground-based data. e.g.
thm_load_gmag, thm_gmag_stackplot, imageplot, mosaicplot
spacecraft/fields/routines for loading, processing and plotting fields data, e.g.
thm_load_fgm, thm_load_fit
particles/ routines for loading, processing and plotting particles data, e.g.
thm_load_sst, thm_cal_sst
state/

Routines for reading state and performing coordinate transformations, e.g.
thm_load_state, thm_cotrans.

examples/common/Crib sheets, like thm_crib_ask
THEMIS-specific tools useful to multiple data types and instruments, eg
thm_config, thm_file_download, thm_init
The TDAS GUI and supporting routines
CDF utilities, including cdf2tplot, and other utilities like cdf2tplot,
cdf_info, cdf_load_vars (into IDL structure representation of CDF)
Routines useful for specific scientific analysis.
General coordinate transformation: cotrans, ssl2dsl, dsl2gse

thm_ui_new/
CDF/
science/cotrans/

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

tplot/misc/, tools/
key_param/
missions/

General time-plotting utilities
Miscellaneous routines used by tplot and other ssl_general routines.
Load routines for ACE, KP, WIND, POLAR data, some of these
Load routines for ACE, KP, WIND, POLAR data. Some of these replaceolder routines in the /key_param directory.

IDL_GEOPACK

Magnetic field modeling, Tsyganenko models

external/

The _tdas_doc.html file contains a complete listing of all routines in the hierarchy, along with links to complete
documentation.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 . Graphical User Interface
The THEMIS Graphical User Interface (GUI) provides a powerful interface to THEMIS science data. It is designed for easeof use in viewing and analyzing data and is set in a familiar windows-like environment. Features include the ability to read,load, and view data, create publishing quality plots, access commonly used THEMIS analysis software, and increased userinteraction.
The GUI code is bundled together with the THEMIS IDL code distribution; they are downloaded and installed as a single
package.
A text-only version of the documentation for the GUI is available within the software distribution at
idl/themis/examples/thm_gui.txt.

0.0 Main Window Overview
The main GUI window is shown below in Figures 3.1.1a and b. This is a snapshot of the window when the GUI is firststarted. Since no data or THEMIS GUI document has been loaded and no plots created, the main graph area will be blank.
Starting from the top of the window is the windows frame titled. THEMIS: Main Window. It has the standard window
features in the frame to minimize, maximize, and close the window.
Below the frame is the main menu bar. Commonly used menus include File, Edit, View, Page, and Help. Specific to the
THEMIS application are Graph and Analysis pull down menus.
Next, below the main menu bar is the toolbar. For quick and easy access to the most frequently used functions, the toolbar
contains icon buttons the user can click on versus navigating through the pull down menu hierarchy. All icon buttons in the
toolbar contain tooltips to provide the user with a brief description of the functionality.
Below this is the horizontal scroll bar, which allows you to pan left and right along the x-axis of any displayed data.
The large central area of the main window contains the graph area and is where plots are displayed. To the right of the grapharea is a scroll bar that allows the user to scroll vertically when multiple plots are displayed. (Unlike the horizontal scroll bar,
this scrolls across the images, but doesn't change the range of displayed data). If the view is zoomed in sufficiently, a scroll
bar will also appear on the bottom of the graph area which, like the vertical scroll bar, will allow scrolling across thedisplayed images, but not change the range of the displayed data.
And, finally, at the bottom of the window is a message bar. The message bar updates the user on the state of the GUI, thestatus of an operation, and provides general information to the user, including warning and/or error messages.

0.0.0 Pull Down Menus
Pull down menus use standard features that users are familiar with and including the following:Sensitive: A menu item may be sensitized or desensitized (grayed out) depending on the state of the GUI and/or theavailability of an operation at the time it is requested.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

Checked: Check marked menu items are used when an option can be turned on or off. The check mark allows the user totoggle on or off an item.
Sub: In cases where multiple options are available, a sub menu is used to further divide the functionality. Submenus will
have a carrot or arrow head indicating there are additional options to select from.
Dynamic: One menu, the Page menu, is not static and changes with the number of pages that have been created.
Pop-Up: In cases where a menu item displays another window, the name of the item will be following by three periods.
Accelerator: Some menus have accelerator keys associated with them. Accelerator keys provide a quick and easy way to
invoke functions. When a menu item has an accelerator key, the key combination will be listed next to the name of the menu
item.
An example pull down menu is shown below in Figure 2.1.1a.

Desensitized
Submenu

Window Pops Up

Accelerator
Key

Figure 2.1.1aNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Window Resize
Menu Bar
Tool Bar

Main Graph
Area

Status Bar

Figure 3.1.1b

0 .0 .0 Toolbar icons
The toolbar provides short cuts to more commonly used functions. The buttons contain familiar icons depicting the operation.
In addition, each tool bar button contains a tool tip that is displayed when the cursor hovers over the button. The tool tip
displays text describing the function of the button. Figure 3.1.2 shows a picture of the tool bar.

LoadManage
PlotNewHelp
Open/SavePrin Cop Expan Scroll
Forward/
Data
Data
d/
DataPage
THEMIS ty
Backwar
Reduc
DocumentPagde e

Figure 3.1.2

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Zoom

0 .0 .0 Graph Area
Shown below, in Figure 2.1.3, is an example of the main graph area with a graph plotted.

Figure 2.1.3

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0 Status Bar
The status bar is located below the main graph area and displays messages to the user. Messages include status updates, stateof the GUI and/or operation, success and failure notices, as well as warning and error information. It is important for the user
to remember to check the status bar periodically for messages, particularly if you think something is not correct. Information
displayed in this bar may be helpful and provide an answer to your question.

Figure 2.1.4
Please note, when a severe error or incorrect usage occur you will be notified via a pop-up dialog window explaining theerror. Additional instructions may be provided.

0 .0 .0 Buttons
In order to provide a consistent interface throughout the GUI, you will find most windows contain the set of buttons shown in
Figure 2.1.5.

Figure 2.1.5
OK: When this button is clicked whatever changes you made since the window was first displayed will be made, committed
within the system. The window will be closed and the main graph area will be updated to reflect the changes. Please note thatwhen OK is selected the original settings will be lost.
Apply: The apply button will update the main graph area so that you can view your changes. The window will not be closed
and your changes will not be committed.
Cancel: Whenever the cancel button is clicked all changes made since the window was first invoked will be reset to original
settings. The window will be closed. The main graph area will be updated to reflect its original state. You should note thatlike the OK button, when the cancel button is selected all changes are lost permanently.

0 .0 .0 Windows
A window within the GUI refers to any windows that is opened when pull down selections are made, a tool bar button isclicked and other user interactions. Windows have frames, titles, and minimize, maximize, and close buttons within theframe. Most windows are also modal. That is, the user must either click the OK or Close button, or the Cancel button ‘X’ inthe window frame before control is returned to the calling or original window.
NOTE: Screen size and system settings vary from machine to machine. During testing, a rare case was found that opened
some IDL windows to size zero. The windows included the dialog box pick file and printer setup used in the File pull downmenu. This is an error internal to IDL. If a window opens to size zero, you simply need to resize to see the content.

0 .0 .0 Pages
The user can have one or many pages during a session. A page contains one or many panels, titles, background color, etc. The
number of pages that have been created can be determined by using the Page pull down menu. The Page pull down menu also
provides a way for the user to toggle between pages since only one page can be displayed at a time.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0 Panels
A panel is a plot or graph on a page. Panels are usually contained within an axis frame and have x and y axes (and z axes forspectral data), traces, ticks, gridlines, and other features. One or many panels can be created per page.

0 .0 .0 Color Palette
Most of the Graph Options windows allow the user to change the color of labels, traces, background, grid, annotations, andmore. Whenever color can be modified, a Color Button (with a color palette icon) and Color Swatch with the current color
setting will be available. An example of the Color Button and Current Color Swatch are shown in Figure 2.1.9a.

Color
PaletteButtonCurrent
Color
SwatchFigure 2.1.9a

When the color button is clicked a Color Palette window is displayed. The user can select a color by clicking on the color
tiles or by using the RGB slider bars below the tiles. When a selection has been made the current color swatch in the middleof the window will be updated to reflect the new color. You can choose to accept the color by clicking on the Accept Button
or choose not to make any changes by clicking on the Cancel Button. Both the Cancel and Accept buttons will close the color
palette window and return to the original or calling window. If the user accepted the color, the current color swatch in theoriginal window will be updated. The color palette window is shown in Figure 2.1.9b.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.1.9b
The Color Palette window is a modal window and you must either make a selection or cancel the window in order to return
control to the calling window.

0 .0 .0 0 Data TreeAll data that have been loaded directly into the GUI or imported from tplot variables are displayed in a tree widget. Many of
the GUI windows require the user to select data for analysis or plotting and will be displayed in tree format. The tree widget
allows the user to expand or collapse the tree by clicking on the ‘+’ (expand) or ‘-‘ (collapse) buttons next to the data. The
data tree hierarchy is as follows:
MissionObservatory
Instrument
Data Group
Data Components
An example of a data tree is shown below in Figure 2.1.10.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Mission
Observatory

Instrument
Data Quantity

Instrument

Data
Components

Figure 2.1.10

0.0 Mouse and Keyboard Events
0.0.0 Tracking
When tracking is enabled any movement within the frame of a panel in the draw area will be tracked. Tracking can be
toggled on and off from the Graph pull down menu. The user can choose to track one panel or all panels. In addition the user
can track vertically, horizontally or both. When the GUI session is first started, tracking of all panels is on by default andtracking both vertically and horizontally. Figure 2.2.1 shows an example of the main graph area when tracking is turned on
and tracking all panels. Changing the tracking settings will affect what information is displayed in the legend, and which
panels the legend is displayed on.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 Legend

Horizontal andVertical Tracking
Lines

LegendFigure 2.2.1
When tracking is on a legend will be appear in the upper right corner of each panel that is being tracked. The values of eachdata point intersecting the vertical tracking line are displayed. See Figure 2.2.1 above. The user can choose to turn theposition legend on or off by toggling the Position Legend under the View menu. The legend is on by default. If only one
panel is being tracked, then only one panel will have a legend. The legend does not appear in exports or prints.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 Mouse Clicks
The mouse button offers several ways to interact with the GUI and the graph area. Mouse clicks include Single Click (leftbutton), Right Click, Ctrl-Click-Drag, and Click-Drag.
Single Click:
There are two possible events that a single click will generate. One is when marker(s) are present and the user clicks within
the highlighted area of a marker, the other is when the user clicks outside of a marker but within the graph area. Markers will
be explained shortly in Section 2.2.5. For now, we will describe a single click in the graph area, which brings up a graphoptions menu window. Which graph options window is displayed depends on where within the graph area the mouse button
was depressed.
There are 5 options.
Page: Any area that is outside of a panel, axis, label, or variable display will bring up the Page Options Window. In
the event the GUI cannot determine which object was clicked, the Page Options Window will be opened.
Panel: When the user clicks within the frame of any panel, the Panel Options window is displayed
X-Axis: When the user clicks on the X Axis the Axis Options panel is displayed.
Y-Axis: When the user clicks on the X Axis the Axis Options panel is displayed.
Variables: If variables are present the user can click in the variable display area to open the Variable Options
window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Single Click in
Y Axis region

Brings up Y Axis
Options window

Figure 3.2.3a

Please note that resolution and screen size vary between machines and platforms. If you click close to another option in thedraw and do not get the window you wanted, try clicking more in the middle of the area you want.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Right Click:
Clicking the right mouse button will bring up a context menu containing the most commonly used options associated withplotting and data analysis. The context menu contains the following menu items.

Right Click

Context Menu

Figure 3.2.3b

0.0.0 Keyboard Events
There are two kinds of keyboard events, scrolling and expanding/reducing.
Scroll: The user can scroll the panels in the active page forward or backward by using the left and right arrow keys. The plot
will be moved forward or backward in time by one major tick length.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Reduce/Expand: The panels can also be reduced or expanded by using Backspace or Tab keys. Tab will expand the panels
horizontally by two major tick lengths (one major tick length is added to both the left and right sides of the x axis). Similarly,
Backspace will reduce the panels displayed by two major tick lengths.
Accelerator Keys: Standard accelerator keys are available for the more frequently used functions. Accelerator keys include
Ctrl-O – Opens an existing THEMIS GUI Document
Ctrl-S – Saves a THEMIS GUI Document
Ctrl-Z – Close pageCtrl-P – Print pageCtrl-Q - Quit
Ctrl-R - Refresh
Ctrl-C - Copy

0.0.0 Markers
Marking is a feature that allows the user to mark or select regions of interest in panels on the active page. If “Track All” is set
in the Graph menu then all panels will be marked; if “Track One Panel” is set then only the panel the cursor is in is marked.
A Ctrl-Click-Drag operation is used to create a marker. If the cursor leaves the draw area, marking will be canceled. Figure
2.2.5 shows examples of two markers, one created while all panels were being tracked, the other with only one panel
tracking.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Cursor in marker

Selected Marker

MarkerFigure 2.2.5
Marker Color Codes:
Green: Indicates that the cursor is currently within the marker
Blue: Indicates the user has clicked the mouse button within that marker to make it ‘Active’ or the currently selected marker.
Only one marker can be active at a time.
Red: Represents all other markers (not active or the cursor is not within its area.
When a marker is ‘active’ (blue boundary lines) there are additional functions you can perform on the marker. To delete amarker select the Delete Marker option under the Edit pull down menu. To display only the marked area, select the Subset
option under the Edit pull down menu. A new page will be created and displayed containing only the marked area.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 Selecting Specific regions
Click and drag over an area in the draw window to create a new page containing the selected region. A rubberband box will
be drawn to denote the selected area. If the cursor leaves the draw area the zoom will be canceled. Figure Error: Reference
source not founda shows an example of a selected area. If the “Rubberband for X only” options is set (graph menu) then only
the selected region’s X range will be constrained when the new page is created. If that option is off the new page’s plots will
use the selected region’s X and Y bounds.

Figure 2.2.5

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 Zoom In/Out
In addition to zooming into marked regions and/or rectangular areas the user can also choose to modify the size of the visiblearea by using the zoom spinner widget on the toolbar. The zoom spinner allows the user to increase or decrease the size of thevisible region by entering a percent value of the original page size. The user should be aware that when zooming in and outof the page, the main graph area will not change in size, only the page will. You can see this in Error: Reference source notfound2.2.7, which shows an example of decreasing the page size by 50%.

0.0 File Menu
The file menu contains selections that are related to loading, saving, and managing data, as well as printing and exporting
image files. Figure 3.3 shows all options in the File pull down menu.

Figure 3.3

0.0.0 Open THEMIS Document
The THEMIS GUI includes the capability to save the state of a GUI session to a "THEMIS GUI Document" file (.tgd fileextension). TGD files are plain ASCII text, use XML to represent properties of GUI objects and loaded data, and can be
examined with any ASCII file editor. Many web browsers also include support for viewing XML documents (although one
may need to change the file extension to XML to get the browser to recognize the format).
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Any loaded data associated with a GUI session is NOT directly stored in the TGD file; instead, the document contains theinformation necessary to reconstruct the sequence of calls that were initially used to load the data. There are some pros andcons to this approach that users should be aware of:
5.
6.
7.
8.
9.

TGD files are relatively small, and can be easily shared as email attachments. Because they are plain ASCII text,
there are no significant file format differences between different platforms, so TGD files are portable between
systems.
Opening a TGD file may require internet connections to THEMIS data servers in order to download any data files
that are not already cached in the user's local file system.
Since the TGD file only records operations performed within the GUI. Operations performed outside the GUI or
data that is imported via manage data or tplot_gui will not be recorded in the THEMIS Document.
Opening a TGD file is a DESTRUCTIVE operation that wipes out the current window configuration and loaded
data, replacing it with the contents of the TGD file. We recommend that users save their work before opening a new
TGD file, and pay attention to any warning dialogs to avoid nasty surprises.
No versioning information is stored in the XML file, TGD files created under a particular version may not bereadable in other versions. Although, since the GUI interfaces are more stable than they were originally, this isless of a problem in recent releases.

To open a TGD file, select "Open THEMIS Document…" from the File pull-down menu. Navigate to the file you wish toopen, and click "Open" (or perhaps "OK", depending on your platform).
This should trigger the process of loading the data specified in the TGD file you just opened; you should see progressmessages scrolling by in the IDL command window. It may take several minutes to load all the data, depending on how
complex a document is being loaded; TDAS may also need to open an internet connection to the THEMIS data servers to
download any data files not already cached on your local file system.
If all goes well, when the data is finished loading, the main draw window should update and show the plots for the first GUI
page specified in the TGD file. Other pages saved in the TGD file should be accessible through the "Pages" drop-down menu
button. Any errors detected while parsing the XML file or loading the data will be reported by a pop-up error dialog, or amessage in the status area at the bottom of the main GUI window.

0.0.0 Save THEMIS Document
Please refer to the caveats in Section 2.3.7 regarding what is and is not represented in the THEMIS GUI Document
format, particularly regarding operations performed outside of the THEMIS GUI. We recommend a workflow
something like this:Warning: Due to an IDL bug on Windows platforms, the condition "write permission denied" is not properly
detected, and will probably crash your entire IDL session if you attempt to save to a file without write permission.
Use the "Load THEMIS Data" dialog to load the all the data you want to work with
Use the "Window" menu and "Graph->Plot/Layout options…" dialog to create some plots
Use "Save THEMIS Document" to save the window configuration, plot properties, and loaded data call sequence
information, creating a "checkpoint" that can easily be restored later
Perform any other manipulations (e.g. non-GUI operations), and be prepared to repeat them after opening the TGD
file at some later time to restore the check pointed GUI configuration.

When you're ready to save your plots and loaded data, click "Save THEMIS Document" under the File pull-down menu. All
pages, plot settings, data, and data operations will be saved. If this session has not yet been saved to a TGD file, aNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

platform-specific file-saving dialog will appear. Navigate to the directory where you'd like to save the file, select a new
filename if you don't like the default, and click "Save" (or maybe "OK", depending on your platform).
If "Save THEMIS Document" has already been invoked, or if the current session is the result of loading a TGD file, the filepicker dialog will not appear, and the filename from the most recent save or open operation will be used again.
If the save attempt fails, an error message should be displayed, either in a pop-up warning dialog, or a message in the statusarea at the bottom of the main GUI window. If the save succeeds, a success message will appear in the status area.
Hint: The THEMIS document can also be used to save default plot settings. Once you have created the font, size, colors,
grids, axes, etc. that you prefer, the save document option will preserve those values. Each subsequent time you start a GUI
session, you simply need to open the saved document to restore your preferences. See also 3.3.4 Template below.

0.0.0 Save THEMIS Document As
The File->Save THEMIS Document As… dialog also saves a TGD file. The only difference between "Save THEMISDocument" and"Save THEMIS Document As…" is that "Save THEMIS Document As…" always pops up a file picker dialog, allowing one
to change the filename associated with the GUI session. "Save THEMIS Document" will reuse the last filename successfully
saved to, only displaying a file picker the first time the GUI state is saved.
See the documentation for "Save THEMIS Document" in Section 2.3.2 for more information about saving TGD files.

0.0.0 Template
THEMIS templates allow the user to save settings such as font size, colors, line options, etc. THEMIS templates are savedwith the default file extension TGT.

0 .0 .0 .0 Open Template
File->Template->Open Template allows you to open a previously saved THEMIS template (see Sections 2.3.4.2 and 2.3.4.3
below for how to create a saved THEMIS template). Choosing Open Template will bring up a standard file picker dialog.
The exact appearance and functionality will depend on your platform. Once a template has been loaded the settings saved in
the template will be applied to any new work in the GUI. For example, saved settings such as the page title and backgroundcolor will be applied if you create a new page (see Section 2.8 for how to create a new pages), saved settings including panel
options such as grid lines will be applied to any new panels, and so on.
Note: to set a default template that will be opened whenever the GUI is run, see Section 2.3.12.

0.0.0.0 Save Template
THEMIS templates allow you to save page, panel, line, axis, and variable settings. For example, to save page settings firstuse the Page Options (see Section 2.6.6) to format the page title, footer and layout. Then, in the Page Options window, select“Save as Default”, then “OK”. From the File menu select Template->Save Template. This will bring up a file dialog (seeFigure 2.3.4.2). Navigate to the directory where you wish to save the template, and change the file name if you wish. Then
select Save.
The process for saving panel, line, axis, and variable settings is the same as for the page settings. First open the relevant
options window (see Sections 2.6.5 to 2.6.10), choose your settings, and select “Save as Default”. Then choose
File->Template->Save Template to save the template. Note that page, panel, line, axis, and variable settings can all be saved

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

within a single template file. For example, to save both page and panel settings, apply and “Save as Default” both the page
and panel settings before choosing File->Template->Save Template.
Selecting Save as Default in the Panel Options window will save only the currently selected panel’s settings. Similarly Saveas Default in the Line Options window saves the settings from the currently selected trace.
If “Save Template” has already been invoked in the GUI session, or a template has been loaded, the file picker dialog will notappear and you will instead be prompted as to whether you wish to overwrite the existing template file. If you have, forexample, loaded a template containing page settings and now wish to save panel settings, choosing “Save Template” andselecting “Yes” to overwrite the existing template will create a template with the new panel settings that also retains the page
settings.

0.0.0.0 Save Template As“Save Template As” also saves a THEMIS template TGT file. Unlike “Save Template”, “Save Template As” will always
bring up a file picker dialog allowing you to change the filename of the THEMIS template you are saving.
See Section 2.3.4.2 for further information about saving a THEMIS template.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 Reset Template
File->Template->Reset Template allows you to reset to the THEMIS default individual parts (e.g. page, panel, axis) of thecurrently loaded THEMIS template. For example, selecting Reset Template->Reset Page Template will reset the page settings(e.g. title, background color) to the THEMIS defaults for any new pages you create, while retaining any panel, line, axis, andvariable settings saved in the template.
Figure 2.3.4.4 shows the Reset Template sub-menu.

Figure 2.3.4.4

0.0.0 Load Data
The Load Data option, under the File pull down menu, opens a window that allows the user to select specific data sets to beloaded into memory. Four missions are available for loading data and include THEMIS, GOES, WIND, and ACE data. Thereis also a tab for loading THEMIS particle spectra.

0 .0 .0 .0 THEMIS Data
The left hand side of the window contains the data selection area and the right hand side of the window displays data that has
already been loaded

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.3.5.1
Data can be removed at any time by making a selection in the data tree and clicking the trash can. The data tree will be
updated to reflect the deletion. The user can also use the Clear All button below the data tree to delete all data.
At the bottom of the window is a status bar. Messages regarding the load process, data, and/or status of the window will be
displayed here.
When you have loaded all the data you want, click the Done button below the data tree.
Each different mission supported by the THEMIS GUI has separate configuration parameters. In the GUI you can control
configuration for each mission by editing the settings in the File->Configuration Settings Menu. For more see Section 1.3 Installation and Configuration.

0.0.0.0 THEMIS Derived Spectra
This window provides an interface to the TDAS routine thm_part_products mentioned in section 1.5.3.4. Specifically,
this tab allows the following spectrogram products to be produced and loaded directly into the GUI.
ENERGY: Spectrogram across the instrument's energy range
PHI: Azimuthal spectrogram along the spacecraft’s spin plane (DSL coordinates)
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

THETA: Longitudinal spectrogram along the spacecraft’s spin plane (DSL coordinates)
PITCH ANGLE: Magnetic field aligned longitudinal spectrogram (uses fgl data)
GYROPHASE: Magnetic field aligned azimuthal spectrogram (uses fgl data)
Plots for multiple probes and data types can be generated simultaneously. Limits to phi, theta, and energy ranges will affect
all products. Limits to gyrophase and pitch angle ranges will only apply to field aligned products and energy spectrograms.
The exact field aligned coordinate system can be selected as well as the resolution of the interpolated grid in the newcoordinates.

Figure 2.3.5.2

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 GOES Data
Selecting the GOES Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows is
specific to down loading GOES data. The user can select a time frame, the probes, and parameter types. Once the user has
made their selections, to download and import data into the GUI memory, click on the right arrow key, in between the GOES
Data Selection Area and the Data Loaded area. An hourglass will appear while data is being loaded. If the user chooses todelete data, they can select the variable name from the data loaded window and click the trash can.

Figure 2.3.5.3

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 WIND Data
Selecting the WIND Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows is
specific to down loading WIND data. The user can select a time frame, the instrument type, data type, and parameter types.
Once the user has made their selections, to download and import data into the GUI memory, click on the right arrow key, inbetween the WIND Data Selection Area and the Data Loaded area. An hourglass will appear while data is being loaded. If theuser chooses to delete data, they can select the variable name from the data loaded window and click the trash can.

Figure 2.3.5.4

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 ACE Data
Selecting the ACE Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows is
specific to down loading ACE data. The user can select a time frame, instrument type, data type, and parameter types. Oncethe user has made their selections, to download and import data into the GUI memory, click on the right arrow key, inbetween the ACE Data Selection Area and the Data Loaded area. An hourglass will appear while data is being loaded. If theuser chooses to delete data, they can select the variable name from the data loaded window and click the trash can.

Figure 3.3.5.5

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0 .0 .0 .0 FAST Data
Selecting the FAST Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows is
specific to down loading FAST data. The user can select a time frame, instrument type, data type, and parameter types. Oncethe user has made their selections, to download and import data into the GUI memory, click on the right arrow key, inbetween the FAST Data Selection Area and the Data Loaded area. An hourglass will appear while data is being loaded. If theuser chooses to delete data, they can select the variable name from the data loaded window and click the trash can.

Figure 3.3.5.6

0 .0 .0 .0 IUGONET Data
Selecting the IUGONET Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows
is specific to down loading IUGONET data. The user can select a time frame, instrument type, data type, and parametertypes. Once the user has made their selections, to download and import data into the GUI memory, click on the right arrow
key, in between the IUGONET Data Selection Area and the Data Loaded area. An hourglass will appear while data is being
loaded. If the user chooses to delete data, they can select the variable name from the data loaded window and click the trashcan.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.3.5.7

0 .0 .0 .0 OMNI Data
Selecting the OMNI Data tab displays a window similar in form to the THEMIS Data tab, however, this tabbed windows is
specific to down loading OMNI data. The user can select a time frame, resolution, and data types. Once the user has madetheir selections, to download and import data into the GUI memory, click on the right arrow key, in between the OMNI Data
Selection Area and the Data Loaded area. An hourglass will appear while data is being loaded. If the user chooses to delete
data, they can select the variable name from the data loaded window and click the trash can.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.3.5.8
0 .0 .0 .0 Geomagnetic and Solar Indices
Selecting the Geomagnetic/Solar Indices tab displays a window similar in form to the THEMIS Data tab, however, thistabbed windows is specific to down loading geomagnetic and solar indices. The user can select a time frame, resolution, anddata types. Once the user has made their selections, to download and import data into the GUI memory, click on the rightarrow key, in between the Index Data Selection Area and the Data Loaded area. An hourglass will appear while data is being
loaded. If the user chooses to delete data, they can select the variable name from the data loaded window and click the trashcan.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.3.5.9

0.0.0 Load Data using CDAWeb…
The "Load Data using CDAWeb…" dialog allows the user to load data from a large number of NASA missions. The
CDAWeb graphical download tool was originally developed by NASA. For information on the NASA tools for IDL, see:
http://cdaweb.gsfc.nasa.gov/WebServices/REST/CdasIdlLibrary.html
We have adapted their code to the needs of SPEDAS and the result is an integrated download tool that can receive data fromdozens of mission and transform this data to the tplot format used in SPEDAS. Then the data can be plotted or transformed
like any other data set. Figure 3.3.7 shows the CDAWeb Data Chooser window.
To use the tool, first we select the mission name (for example, “ARTEMIS”) and the type of the instruments (for example,“Magnetic Fields (space)”) and then we click the button “Find Datasets”. This gives a list of all available data sets and thedates of availability of each data set. We have to expand the data sets and select one or more data variables (using Ctrl+Clickto select multiple variables). We can select the start and end dates and times using the calendar widget. We have to pick dates
that are within the availability dates of the particular data set we have selected. It is also important to select a “Local CDF
directory” which is writable, because that directory will be used to download files for the CDAWeb data repository, even if
we do not retain those files. If we want to keep the downloaded CDF files, then we should check the checkbox “Save local
CDF file”. We can also define an optional prefix for the resulting variables, for example “artemis_”. Clicking on the “Get

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

CDAWeb Data” button downloads the requested data set. After the download is complete, we get a message that informs usthat the download was successful (or not) and another window which allows us to specify the name of the tplot parameternames. This last window is the same as when we import data from an arbitrary CDF file. After this, the CDAWeb Data
Chooser window closes and we can work with the data we have downloaded.

Figure 2.3.76

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 Save Data As…
The "Save Data As…" dialog allows the user to select a set of variables, and save the data as ASCII (with various formatting
options) or as a set of files in the UCLA binary "upper flat file" format. Unlike "Save THEMIS Document" or "Save As…","Save Data As…" does not attempt to save any GUI objects or plotting parameters.
Click "File->Save Data As…" to bring up the dialog. On Windows XP, it will look something like this, assuming some data
has already been loaded:

Figure 2.3.7

The left hand "Loaded Data" pane is a "tree widget" representing the data variables currently available. In the above screen
shot, many of the nodes are fully expanded. Click any box showing "+" to expand that node, or click a box showing"-" to collapse that node.
To the right of the "Loaded Data" pane are some additional controls. If the "Restrict Time Range" box is checked, only thedata with timestamps in the given time range will be saved. For now, the start and end times must be typed into the text box
in YYYY-MM-DD/HH:MM:SS format.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

If the "Save as Flat file" box is checked, the data will be saved in (binary) UCLA flat file format. For further information
about this format, please consult the UCLA documentation.
If the "Save as ASCII data file" box is checked, the data will be saved as ASCII, one line per record. If this format isselected, there are additional choices for how the ASCII data is formatted. The "Time Format" drop-down menu brings up alist of different formats for representing timestamps with varying degrees of precision. The "Floating Point Format"
drop-down menu specifies the precision and format of floating point quantities that are not internally marked as timestamps.
The "Header Style" drop-down menu offers a few options for including header lines in the ASCII output. If "None" isselected, no header will be produced; for "Field Names Only", a single header line will be included, listing the field names
associated with each data column; for "Tecplot", a Tecplot-compatible header will be produced with one line of field names,
and another line with a sample count and some other information.
The "Item Separator" drop-down menu allows the user to select whether columns are to be separated by commas, tabs, or
spaces. This option also applies to the header, if one is requested.
As an example, if "Header Style" is set to "Field Names Only" and "Item Separator" is set to "Comma", the resulting ASCII
file should be readable by Excel or other utilities that understand CSV ("comma separated value") formatted files.
The "Indicate flags with:" text box allows the user to choose what gets printed if an IEEE-754 "NaN", "Inf", or othernon-numeric floating point value is encountered during the conversion to ASCII. We suggest keeping the default text "NaN".
(The term "flag" is used because in some situations, TDAS inserts NaN values to "flag" missing or invalid data samples.)"Update document with location of data" is not yet implemented in this release (and perhaps never will be), and should bedisregarded for now.
The suggested workflow for this dialog is to first use the tree widget in the "Loaded Data" pane to select some subset of thecurrently loaded variables, then use the controls on the right hand side to select a file format, an optional time range, and any
additional style settings (if ASCII format is selected). Clicking the "Save" button will perform a few checks on the selected
data variables, and if the selection is valid, the GUI will pop up a file picker dialog to specify the filename and directory to
save.
Caveats:
This dialog does not permit saving arbitrary collections of variables. Owing to the record-oriented structure of these fileformats, all selected variables must contain the same number of samples. For UCLA upper flat file format, the only valid
data types are 4-byte integers, and 4- and 8-byte floating-point values. THEMIS data represented as bytes or 16-bit integers(for example, ASK) cannot be saved as UCLA upper flat files. These restrictions are enforced at the very end of theworkflow, when the user clicks "Save". The first variable name with an incompatible sample count or data type will bementioned in the error message; try removing that variable from the selection, and repeat the process until a valid ensembleof variables remains.
ASCII files generated from large data sets (e.g. several hours of ASK keogram data) are potentially enormous, and may
appear to lock up IDL for a long time while the file is being written. Even modest ASCII data sets may require several
minutes to be saved. These operations are somewhat inefficient; due to the need for column-by-column checking, formatting,and output of data fields.

0.0.0 Manage Data and Import/Export Tplot

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The Manage Data Window allows you to import TPLOT variables into the GUI, export TPLOT variables from the GUI,
delete GUI variables, and view/edit the meta-data associated with various GUI variables.
To import TPLOT variables you can select one or many (ctrl/shift-click) tplot variables in the left TPLOT Data area, thenpress the right arrow button to move data into the GUI. The data will then be moved into the GUI and attempt to detect thevariable meta-data that includes name, mission, observatory, instrument, units, and coordinate system. Figure 2.3.8a shows
the Manage Data window.

Figure 2.3.8a
When the right arrow is clicked to import tplot data, the Verify Data Window will be displayed allowing you to verify that
this data was correctly detected. Click the OK button if it is or 'Cancel' if you change your mind about importing. After youpress 'OK' on the Verify Data panel, the data will be loaded. Figure 2.3.8b shows the Verify Data window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.3.8b

To export GUI variables to TPLOT, select the GUI quantities that you would like to export from the tree at the right andselect the left arrow button to export them.
To delete GUI variables, select the GUI quantities that you would like to delete from the tree at the right, then select the trash
can button to delete them.
To examine the meta-data (name, mission, observatory, instrument, units, coordinate system, and file name) associated withparticular GUI variables. Select the variable to be examined in the tree at the right and select the magnifying glass button to
examine the meta-data. A menu like the verify menu will pop-up and you can view or edit the meta-data for the selected
quantities.

0.0.0 Export To Image File…
The Export to Image Menu allows you to generate an image file of your currently active page. The THEMIS GUI supports
the following file types: Portable Network Graphics (.png), Encapsulated Postscript (.eps), Windows Meta-File (.emf,
Windows Only), Windows Bitmap (.bmp), Graphics Interchange Format (.gif), Joint Photographic Experts Format/JPEG(.jpg), JPEG 2000 (.jp2), Apple PICT format (.pic).
The EPS export uses the routine ssl_general/misc/fancompress.pro to decrease the size of line plots when exported to EPS.
EPS files without compression can be tens or even hundreds of MB large. Fan Compression should generally keep the EPS
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

0.

Page margins can be easily changed under Graph->Page Options, Layout tab, to ensure all labels are visible on thepage.
Setting line plot resolution at or past 70% can make the file unreadable due to the size of the file.

0.0.00 Print
When the Print option is selected under the File pull down menu an IDL print dialog window will be displayed. The default
print device will be displayed and you can choose the number of copies you would like printed out. If you do not wish to use
the default printer listed, please see Section 2.3.11, Printer Setup, which allows you to select from all printers that arerecognized by your system. In addition, the Printer Setup window allows the user to control additional print parameters.
Figure 2.3.10 shows an example of the print dialog window.
NOTE Printing in IDL can be unreliable depending on your combination of Printer and OS. If you have any
problems printing, you should export your document to an Image (EPS or PNG) and print directly using your an OS
specific image viewer.

Figure 2.3.10

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.00 Printer Setup
The Printer Setup option available under the File pull down menu allows the user to set up print parameters, select print
devices, and print. The Print Setup option displays the standard IDL print dialog window. All print devices that your system
can detect are listed in the Select Printer box. In addition, you can control the number of copies, page range, collating details,
and preferences associated with the print device you selected. For detailed information about this dialog box and thepreferences you can set, please refer to the IDL User’s Guide. Figure 2.3.11 shows the Print Setup window.

Figure 2.3.11

0.0.00 Configuration Settings…
This button pops up a window that allows access to the system variables that control the automatic downloading process. You
can type in values for the different options in the window. Tabs at the top of screen allow selection of configuration
parameters for the different missions that the GUI supports loading data from. New tabs can be added (of removed) in the
future, depending on the number of missions that the GUI supports directly.
The first tab contains general SPEDAS configuration settings, such as the temporary directory that can be used for
downloading files, the verbose level for tplot messages (warnings and general information messages) and the name and pathof the preferred browser executable (which is especially useful for Unix-type machines).
The next tab contains information for the THEMIS mission files. The top text box gives the local data directory. THEMIS
data that are downloaded are written to this directory. The default value for users who are logged on to an ssl.berkeley.edu

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

about THEMIS templates. Note that when a default template has been loaded from the configuration settings it is still
possible to change the template in use in the GUI session by choosing File -> Template -> Open Template.
The Configuration Settings window is show in Figure 2.3.12.
RESET - If you press this button, configuration settings are returned to their original state prior to opening this window.
RESET TO DEFAULT - If you press this button, the configuration is returned to the default state in THM_CONFIG.pro, andany saved configuration file is deleted. This means that if you want to go back to a configuration that you have saved
previously, you need to reset the values and then save the configuration. Alternatively, you can locate the previously saved
file and copy it to the appropriate location in the APP_USER_DIR shown below.
SAVE - If this button is pressed, then the current configuration is saved in a file. This file ends up in a directory created by
the IDL APP_USER_DIR routine, on a windows system the path looks like this:"C:\usernme\.idl\themis\thm_config-4-win32\thm_config.txt". On a Linux machine, it looks like:"$HOME/.idl/themis/thm_config-4-linux/thm_config.txt"
Important: Once you have saved this file, it will always be read when you run any THEMIS routines -- you should only needto do this once for each operating system that you are using. Whenever you save a new file, the old file is copied to a filetagged with the current date and time.

0.0.00 Exit
The Exit option under the File pull down menu will terminate the THEMIS GUI session. All windows will be closed andcontrol returned to the command line.

0.0 Edit Menu
The Edit menu contains options that allow the user to copy the current page to the clipboard, delete markers, and a new page
containing either a copy of the current page or the content of the selected marker. Figure 2.4 shows the Edit pull down menu
selections.

Figure 2.4

0.0.0 Copy
The Copy option in the Edit pull down menu will place a copy of the current or ‘active’ page on the clipboard. You may also
use the accelerator key sequence Ctrl-C to copy the current page. Once the image has been placed on the clipboard, the user
may paste it into any program, such as a Word document. This option is most useful under Windows; on X11-based systems,
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

the clipboard data is stored as EPS commands rather than a raster image, and most applications will not be prepared to do
anything sensible when such data is pasted into them.

0.0.0 Delete Marker
If markers exist and one has been selected, the Delete Marker option under the Edit pull down menu will remove the marker
and redraw the page without the marker. Recall that when a marker is selected, the vertical lines bounding the marked area
are drawn in blue. If no markers exist, or none have been selected the procedure will do nothing and you can continue withother GUI operations.

0.0.0 Subset
The Subset option will create a new page based on the ‘active’ window or the selected marker. This menu item contains two
submenus, Page and Marker.
The first item, Page, makes a copy of the ‘active’ page and pastes that copy into a new page. The original page is preserved.
You can use the Page pull down menu to toggle back and forth between pages.
The second item, Marker, zooms in to the selected marker. Like with Subset Page, the Subset marker option will create a newpage, this time containing only the x range that is contained within the marker boundary. The original page is preserved.

0.0 View Menu
The View menu contains items that modify the look of the main GUI window and/or the page and panels displayed in themain graph area.

Figure 2.5

0.0.0 Refresh

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

You can use the Refresh option in the View pull down menu at any time to redraw the ‘active’ page. The Refresh option also
has an accelerator key, Ctrl-R.

0.0.0 Scroll Forward/Backward
Scrolling can be invoked in three ways, using the Scroll Forward or Scroll Backward option in the View pull down menu,
using the left and right arrow keys, or by using the scroll icons in the toolbar. A scroll request will move the x-axis forward or
backward by the range of a major tick. This operation will be done for all panels in the ‘active’ page.

0.0.0 Expand/Reduce
Similar to scrolling the Scrolling forward can be invoked in three ways, using the Scroll Forward or Scroll Backward option
in the View pull down menu, using the ctrl and tab keys, or by using the expand/reduce icons in the toolbar. A expand/reduce
request will expand/contract the x-axis of the displayed data by a major tick.

0.0.0 History Window
The history window is a list of the steps, operations, and plots that have been executed during the course of your session, as
well as warning and error messages. Just below the history window are buttons that allow the user to save the history in a file,and clear the history. The "Save" button will save the history in an IDL source file. When you click here, a file selection
window pops up, allowing you to choose the filename and path for the file. The default file is"thm_gui_history_yyyymmddss.pro" and is located in your local working directory. The time stamp on the default file nameis the local system time. The "Close" button close the history window. History window messages are not lost when thewindow is closed. History messages are recorded at all times while the THEMIS GUI is running, regardless of whether thewindow is displayed or not.
Since the history information includes error message, it will be used as a debugging tool. When an unexpected error isencountered during your session, you will be notified with a message and the Error Report Form will be displayed. When the
Save button is clicked in the Error Report window both the Error Report Form and the History file are saved. When the Save
button is clicked in the History window only the history file is saved. In addition to history messages, IDL journal messages
will also be appended to the file.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.5.4

0.0.0 Legend
The legend box displays a value for each variable within the panel. The value displayed is the value at the point where thevertical tracking line intersects the data line, in other words the x value of the data at the x position of the cursor. Wheneverthe cursor is moved the values in the legend box will be updated. Note that along with the y-axis labels, the legend labels andNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

values are color-coded and synchronized with the color of the line within the plot. Figure 2.5.5a shows an example of thelegend box.
Legend formatting, placement, and annotation options can be changed in the Legend Options window accessible through theGraph menu at the top of the GUI (figure 3.5.5b). The legend can be turned off by un-checking the Legend option in the
View pull down menu. The legend and tracking bars will not appear on any exported plots (images, postscript, physicalprints).

LegendFigure 3.5.5a

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.5.5b

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0 Graph Menu

Figure 2.6

0.0.0 Panel Tracking
Tracking can be toggled on or off by selecting the Panel Tracking option under the Graph menu. When tracking is on, youwill see a vertical bar tracking any cursor movement that occurs inside the frame of a panel. By turning off tracking, you also
turn off the position legend box in the upper right corners of the panels. This menu item will also turn off the Track One
Panel and Track All options.

0.0.0 Track One Panel
The user can choose to turn the vertical tracking line to track only one panel at a time versus all panels. When this mode isselected the vertical tracking bar will track only the panel that the cursor is in. If the position legend is on, only the legendbox of the panel the cursor is in will be updated. The Track One/Track All menu pairs are mutually exclusive so when one
mode is on, the other will be turned off.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.6.2

0.0.0 Track All
When in track all mode, the vertical line will track the cursor movement in all panels in the ‘active’ page. See Section 3.6.2
Track One Panel to see how the two menu items are paired.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.6.3

0.0.0 Plot/Layout Options
The Plot/Layout Options window allows the user to create panels and select data values for display on those panels. Panels
can be added, deleted, and reordered. Settings associated with panels and traces can be modified as well.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The left hand side of the window is used for selecting the variables to be used in plots. The right hand side of the window is
for manipulating panels. If no data has been loaded or panels created both these text areas will be blank. The Variable section
at the bottom of the window allows the user to select variables for display below the X axis of the selected panel.
There are two types of plots supported: Linear and Spectral. To add a plot of a particular type, select the data that you wantto add and select the line or spectra button. If you check "Show Data Components", you can select the data used to generate
the x,y, & z(spectra-only) axes of the plots. Figures 2.6.4a and 2.6.4b show examples of both.

Figure 2.6.4a
A new panel will automatically be created with the selected variable(s) when the “Line->” or “Spec->” buttons are pressed
unless the selected panel is blank. To disable this feature uncheck the Automatic Panels box on the upper left.
As new panels are added the panel number will increase sequentially, regardless of whether earlier panels were deleted orreordered. The row and column numbers are displayed in parenthesis next to the panel number. It is important to note that
Panel numbers do not change, however, row and column values can
The user can choose to delete a panel or trace by selecting (or highlighting) the item in the panel text box and clicking delete.
Further, the user can modify panel or trace settings by selecting the item and clicking the Edit button. See Sections 2.6.5 and2.6.7 for additional details.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The Up and Down arrow buttons provide a way to reorder panel rows or trace location on the panel. The left and right arrow
buttons move panels by column. Panels can be overlaid, in other words, they can have the same row and column number. The
user needs to be aware of this feature when reordering so that care can be taken to ensure the correct layout is created.
The row and column number of a panel can be changed using the Row and Column spinner widgets below the arrow buttons.
The total number of rows and columns per page can also be modified. Please note that the total number of page rows and/orcolumns cannot be set to a value less than the largest row and/or column value (e.g. Panel 4(5, 2) – Panel 4 is displayed inrow 5, the user cannot change the total rows to any value smaller than 5, likewise, in this example, total page columns must
be greater than or equal to 2).
The X axis of all panels on a page can be locked to that of a particular panel. To do this, select the panel you wish to lock toand click the Lock to Panel button in the bottom right corner of the window. The panel that all others are locked to will havean ‘(L)’ preceding the panel name. When locked the x-axis annotations are only displayed on the last or bottom panel.
When you remove a panel with locked axis and you have more than two panels, the space the removed panel occupied isdrawn blank, rather than moving the panels below it. This behavior is by design, and the reason is that in some situations
moving the other panels automatically would not be what the user wants, or it might not be obvious how to do it, for example
in two-column situations.

Figure 2.6.4b

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The default mode for this window is that the x-axis is time and the y-axis data. The user can choose to show all data
components by clicking the Show Data Components check box at the top of the window. When checked, a new tab for the
X-axis data will be displayed. In this mode the user can specifically select any x and y data values that have been loaded. You
must remember to return to the Y-axis tab and make a selection before clicking the Add button. Figure 2.6.4b shows the
Layout Options window in the Show Data Components mode.
At any time the user can click the Apply button to view the panel layout, the OK button to commit the layout, and close thewindow, or Cancel to undo changes and close the window.
At the bottom of the Layout Panel is a variable section. The text box will display any variables that have been chosen for
display below the x-axis. The user can also click the Add/Edit button to bring up the Variable Options window. See Section
2.6.10 for details on creating variables for display.

0.0.0 Line Options
When a trace (or line) is highlighted in the panel window and the Edit button clicked the Line Options window will be
opened. The Line Options window allows the user to modify any settings that are associated with plotting the line. The Edit
button is for traces only and will not open if a panel is selected.
Line Options can also be opened from the Graph pull down menu.
At the top of the window the user can change the panel and x and y-axes, the window will default to whatever the user
selected in the Plot/Layout Options window. Once a trace is selected each widget will be updated to show the current settings
for that trace. Line and symbol settings, as well as symbol frequency can be modified on this window. Figure 2.6.5 shows theLine Options window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.6.5
Line ModificationsShow Line: The show check box determines whether the line is displayed or not. A check indicates the line will bedrawn.
Mirror: The mirror check box will draw a horizontal line at zero and reflect the trace below.
Color: The color button will open the color palette allowing the user to select a different color. When a new color
has been accepted the current color swatch next to the button will be updated to reflect the change. If the Apply or
OK buttons are clicked the trace will be drawn in the new color.
Style: The line style drop list contains all the line styles that IDL allows (e.g. dashed, dotted, etc..).
Thickness: The thickness spinner widget lets the user change to size of the line.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Symbol Modifications
Show: The show check box will determine whether the symbol is displayed in the plot, or not. A checked box
indicates the symbol will be drawn.
Fill: Fill has not yet been implemented, however, when checked the symbol will be filled in with the selected color.
Style: The symbol style drop list lets the user choose any of the symbols that IDL allows.
Color: The color button will open the color palette allowing the user to select a different color. When a new color
has been accepted the current color swatch next to the button will be updated to reflect the change. If the Apply or
OK buttons are clicked the symbol will be drawn in the new color.
Size: The size spinner allows the user to increase or decrease the display size of the symbol.
Symbol frequency has five options for determining when a symbol is drawn and include: First Point, First and Last Point,
Last Point, Major Ticks, or Every x points. If the Every x points button is clicked a numeric value can be specified in thespinner widget (e.g. a value of 20 will plot a symbol every 20th point).
As with all graph options windows, the user can click the OK, Apply, or Cancel at any time.
Selecting Save as Default will save the settings for the currently selected trace, so that they can then be saved to a template
file. See Section 2.3.4 for information on saving THEMIS templates.

0.0.0 Page Options
The Page Options window controls settings global to the current page. To open this window Select Page Options in the Graphpull down menu.
The Text tab (shown below in Figure 2.6.6a) lets the user choose the settings for size, font, and color of the title, variables,and footer. The ‘Token…’ buttons let the user insert a time stamp with a variety of formats into the title/footer (note that the
GUI inserts the token at the current location of the cursor). The ‘Format…’ buttons change boldface and italic settings. The
Font Style frame controls font, font size, and font color (a color dialog box opens – see Figure) for both title and footer. Use
the Show check boxes to hide or show the title and footer. The “Apply to All Pages” button will apply the settings to all theavailable pages.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Set All Panels: This button works individually for each tab. Any operations done on a given tab after setting the button willpropagate to all panels. Behavior with Locked X-Axes on the X-Axis only: When Locked X-Axes in Plot/Layout Options ischecked [the default], the GUI will check Set All Panels for the Range, Ticks, and Grid tabs, while unchecking Set All Panels
for the Annotation and Labels tabs. We recommend that the user keeps these settings for the Annotation and Labels tabs
when axes are locked.
Auto Range: The range margin sets a margin between the plotted data and the plot box edge (above and below) as apercentage of the maximum minus the minimum of the displayed data. The bound auto-scaling range puts absolute limits on
how big the range can get; auto-ranges fully within the bounds are unaffected.
Floating Center: The GUI determines the center as a mean, or median of the data (the approximate mean/median options
currently function identically to the mean/median options.). If the axis uses linear scaling then floating range is calculatedusing the following equations. Minimum Range = center – span, Maximum Range = center + span. If the axis uses
logarithmic scaling then the floating range is calculated using the following equations: Minimum Range = base ^(log(center) – span), Maximum Range = base ^ (log(center) + span). In other words, the span of the floating center on alogarithmic plot is the number of orders of magnitude above and below the center that should be included in the plot.
In the equation above 'base' is either e or 10, and 'log' is either the natural logarithm or the base 10 logarithm, depending upon
the type of log scaling that is used.
If the axis is Fixed Min/Max: The user determines an absolute range.
Scaling: The user can select linear, logarithmic base 10, or natural logarithmic scaling. Figure 2.6.8a shows the Range Tab of
the X/Y Axis Options window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The Ticks tab sets where and how to draw the axis ticks, and contains two frames for Placement and Length The user canchoose to manipulate ticks by number, or by interval. When the ‘Major Ticks by Number’ radio button is on, the user canmodify the number of ticks in the spinner. By default, the GUI determines ticks automatically; however, the user can toggle
this feature on or off. Please note that when Aesthetic Ticks are on, the # of minor ticks will have no effect. Alternately, theuser can elect to manipulate ticks by interval. When the ‘Major Ticks by Interval’ button is on, the user can enter the number,the units, and/or the specific time at which to align ticks. If the axis is time, ‘Units’ sets the tick frequency in common timeunits, otherwise the units widget is not active. The ‘Draw Ticks’ drop list provides for different tick style’s and includes
drawing the tick inside the panel frame, outside the panel frame, or both. The Placement frame has right and left buttons thatswitch ticks on/off for the right and left y-axes of the plot box. The Length frame controls the lengths of the major and minor
axes. Figure 3.6.8b shows the Ticks Tab of the X/Y Axis Options window.
Tick options will be measured in orders of magnitude of data units if the axis is logarithmically scaled and data units if theaxis is linearly scaled.
Here are some examples that explain how these options work:
3.
4.

If the axis has linear scaling, the minimum range of the axis is 50, the maximum range of the axis is 100, the 'Major
Tick Every' is 10, major ticks will be placed at 55, 65,75,85, and 95.
If the range of the axis is from 10^1 to 10^6, the axis has base 10 logarithmic scaling and 'Major Tick Every' = 2.
Then major ticks will be placed at 10^2,10^4 and 10^6.

NOTE: When auto-ticks are chosen the number of ticks is an upper bound. The actual number of ticks will be determinedbased on the range of the data.
There is also an option to select the style of logarithmic minor ticks.(Log Minor Tick Type) :Full Interval will generate a logarithmic spaced set of minor ticks that cover the entire distance between major ticks even if
they have greater than one order of magnitude spacing or non-integer number of order of magnitude spacing. If this setting isused, the selected values for the minor ticks may not correspond to obvious values.
First Magnitude will generate a logarithmic spaced set of minor ticks that will start at the lower major tick and count upward
one order of magnitude. This may mean that there will not be minor ticks for the full interval, or that they may seemcompressed, but they will fall at obvious values. For example, if major ticks are at 1 and 100, and there are 8 minor ticks,
then minor ticks will be placed at 2,3,4,5,6,7,8,9
Last Magnitude will generate a logarithmic spaced set of minor ticks that will start at the higher major tick and countdownward one order of magnitude. This may mean that there will not be minor ticks for the full interval, or that they may
seem compressed, but they will fall at obvious values. For example, if major ticks are at 1 and 100, and there are 8 minor
ticks, then minor ticks will be placed at 20,30,40,50,60,70,80,90
Even Spacing will spaced ticks evenly. For example, if major ticks are at 1 and 100, and there are 9 minor ticks, then minor
ticks will be placed at 10^.2,10^.4,10^.6,10^.8,10^1,10^1.2,10^1.4,10^1.6,10^1.8

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Annotation options for numerical data include auto formatting, decimal notation, and scientific. Auto format will determine
if the number can be displayed in decimal format with the selected number of significant figures (Annotation Precision
dropdown). If not, then the number will be printed in scientific notation. When forcing to decimal notation the Annotation
Precision dropdown will designate the number of places printed after the decimal, not significant figures. Trailing zeros areautomatically clipped by the software (i.e. “10.00000” is printed as “10”).
For time axes the Annotation Format dropdown has a variety of format options (figure 2.6.8e).

Figure 2.6.8e

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

The Y-Axis Options window has an additional feature that the X-Axis Options does not. The user can choose to set all Labels
to black. By default the line color and label color are synced on the y axis, the Set All Labels Black allows the user tooverride the default colors. This can be useful in printing publication plots.
Note: Selecting Save as Default will save the settings for the currently selected panel, so that they can then be saved to atemplate file. See Section 2.3.4 for information on saving THEMIS templates.

0.0.0

Z Axis Options

The TDAS GUI allows graphing of three-dimensional spectral quantities from the spacecraft as well as ground-based
keograms. See the Section 2.6.4 Plot/Layout Options for details on graphing spectra.
Once spectral plots are created their extra display features and parameters can be edited in the Z Axis Options found under
the Graph pull down menu in the main window. Options for the X and Y-axes are still functional and can also be found under
the Graph pull down menu.
Settings:
The Settings tab (figure 2.6.9a) contains display and annotation options. The Panels drop list contains all plots in the active
page that have z-axes.
Color Table: The color table section allows the user to change the color scheme being mapped to z-axis values on the active
panel. A preview of the current selection can be seen on the right. The color bar represents numerical values in decreasingorder from top to bottom. Colors are mapped to numerical values according to the chosen Scaling.
Scaling: Determines how the selected Color Table is mapped to z-axis values. Values within the range are assigned linearlyby default but can be assigned according to a base-ten or natural logarithmic scale.
Colorbar Placement: Sets the position of the Color Bar. The Color Bar displays the color scheme of the associated panel plus
numeric annotations for scaling.
Number Ticks: The number of “ticks” (i.e. scaling annotations) that are displayed along the Color Bar. Ticks will only bedisplayed if the Color Bar is present.
Colorbar Margin: The distance, in number of pixels, between the plot area and the Color Bar.
Range: The z-axis range is automatically calculated by default and the color table is mapped with the selected scaling.
Checking the Fixed Min/Max box allows the user to specify the maximum and minimum values for the plot. Values above or
below the limits are respectively assigned the color corresponding to the maximum or minimum value.
Log Minor Tick Type: Determines the way that logarithmic minor ticks are spaced on the Z-axis.(See Section 2.6.8: X/Y
Axis Options for description of options)NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Note: Selecting Save as Default will save the settings for the currently selected panel, so that they can then be saved to atemplate file. See Section 2.3.4 for information on saving THEMIS templates.

0.0.00

Variable Options

The Variable Options window lets the user add variables beneath the selected panel. To get Variable Options, select it fromthe Graph pull down menu. Accepting and canceling changes: Clicking OK accepts the changes and refreshes the page.
Clicking Cancel rejects any changes. Dismissing the window via the operating system (‘X’ button) has the same effect as
clicking Cancel. The Apply button allows users to view the changes without closing the window. Hitting "Cancel" will undo
applied changes. Figure 2.6.10a shows an example of the Variable Options window.

Figure 2.6.10a
The Attributes frame: The Field attribute shows the proper data name of the variable and never changes. The Control
attribute shows which data name represents the abscissa for the variable. By default, the GUI sets the control to the time data
for the Field. The Text attribute changes the name of the variable as displayed in the Variables frame on the left and on theplotted panel. The Precision attribute sets the format of the variable annotations (time formats for time variables, floating
formats for numeric variables). Precision, by default, is calculated automatically, however, the user can choose to override
the default settings by selecting either the numerical or exponential radio buttons. The color attributes set the color of theselected variable. The ‘Include units in label’ check box currently has no effect. Use the ‘Show Variable’ check box to show

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

or hide a variable on the plot. Status information on the window operations appears in the status bar at the bottom of thewindow.
To add variables, click the add button (‘+’). The ‘Add Variable(s)’ dialog appears with a tree view of the loaded data. Selectindividual data products, or entire branches. Shift-click or ctrl-click to select ranges or elements. Click OK to accept the
selections, or Cancel to start over. Any selections now appear in the Variables frame on the left. Click OK to accept and havethese variables appear below the current panel, or Cancel to exit Variable Options with no changes. The user may also
select a variable (click on it) to change its attributes (see the Attributes frame on the right), to delete it (‘-‘ button), or tochange its position in the list (up and down arrows). The Label Margin (below Attributes) changes the margin between all
variables (for the selected panel) and the left y-axis of the plot box, and also changes the margin between the variable legend
and the right y-axis of the plot box. An example of the Add Variable window is shown below in Figure 2.6.10b.
Note: Selecting Save as Default will save the settings for the currently selected variable, so that they can then be saved to atemplate file. See Section 2.3.4 for information on saving THEMIS templates.

Figure 2.6.10b

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

A note on locking axes: The GUI hides all variables except those on the last panel when ‘Lock X-Axes’ is checked (seePlot/Layout Options on the Graph pull down menu). This behavior may be modified in later versions.

0.0 Analysis Menu
The Analysis pull down menu contains selections that allow you to perform various functions on data. Figure 2.7 shows theAnalysis Menu options.

Figure 2.7

0.0.0 Calculate
The Calculate Window allows you to access a built in language that will perform simple vector operations on GUI data. The
Syntax of the language itself is described in Section 1.5.8 of this manual. Commands for the language can be typed into thetext box on the left. Each line will be treated as a separate line. If you want to insert a particular data quantity, just select thequantity from the menu at the right and the quantity will be added to the program text box. You can also insert variables that
store the values of numerical constants by selecting them from the drop list in the lower right corner of the window. On the
far right side of the window, are drop lists containing common ideal functions and operators. By clicking on an item in thedrop list, the function or operator will be inserted into the text box at the last position of the cursor.
Rather than typing your commands in the GUI you can also type a GUI program in a plain text file and load it into the GUI
by selecting the 'Open' button at the bottom. If you want to save the program that you currently have in the text box, selectthe 'Save' button at the bottom of the window.
When you are ready to run the program, select the 'Run' button at the bottom and the Calculate program will be executed.
Any quantities that are created will be automatically loaded into the GUI, but if they are much different from the quantities
that they came from you may want to double check their meta-data in the manage data menu.
To exit this window, click on the 'X' in the upper right hand corner of the window or the 'OK' button at the bottom of thewindow. The Calculate window is shown in Figure 2.7.1.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.7.1

0.0.0 Nudge
The Nudge Traces option allows the user to “nudge” a trace on a line plot. “Nudging” simply shifts the given trace by aspecified amount of time. To activate, select “Nudge Traces” from the “Analysis” pull-down menu on the Main GUI. Notethat you need to have created a page and panel and plotted some data before anything will happen when you make thisselection. If there has been data plotted, then a window will pop up, allowing you to select the panel, and trace that will be
nudged. An example of this window is shown below. There are two drop-down menus that allow you to select the panel andtrace that will be nudged. For the current selection, panel 1 is selected, and the trace “tha_state_pos_x” is selected. The units(time units or records) are selected on the right side of the panel; in the example the shift will be given in hours. The numberof hours (or minutes, or seconds, etc…) can be selected in the window below the trace selection window. Note that you cantype a value into this window as well as use the arrows on the side to scroll values.
When the “Apply” button is clicked, the trace is shifted. This is accomplished by creation of a new variable. The amount of
the shift is recorded in the variable name to avoid confusion, to allow for easy recovery of the original values, and to allow anudged variable to be plotted along with the original. In this example, the new variable name is “tha_state_pos_x_3_hr” andis shown on the panel where the nudged trace is plotted.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.7.2
Warning: Note that traces are shifted one at a time. If you are attempting to nudge a spectrogram (e.g, THEMIS ESA or SST
flux spectrograms, or ASK All Sky Keograms) then you may get unpredictable results when the plot shows up.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0

Data Processing

When you click on “Data Processing…” on the Analysis pull-down menu on the Main GUI, a window pops up that allows
you certain data processing tasks.
This window is shown below. On the left side is a window that shows the data that has been loaded. You can click on eachvariable in this window, and set it to “active” by clicking on the right arrow button in between windows. This process works
both ways; you can set data to “inactive” by clicking on it in the right-hand window and clicking the left arrow button in the
middle. You also have the option to clear the active data by clicking the “Clear Active” button. Data processing tasks are only
possible when there is “active” data.
In this window, the “active” data set is “tha_fgh”. Any data processing task will affect these data only. Note that it is notpossible to select individual traces for data processing; the full variable is processed.

Figure 2.7.3
A data processing task will change the active data set to be the data that has been just been created, so once a task is finishedthis variable will show up in the right-hand window, and also it will be added to the loaded data tree on the left. Clicking the“Done” button closes the window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 Subtract Average
For each active data set, the average value is subtracted, new variables are created, the new names have the syntax: new_var= old_var+"-d", and the new variables become the active data sets`. Note the change in both windows in the figure below, thenew variable has been added and set to active.
0.0.0.0 Subtract MedianFor each active data set, the median value is subtracted, new variables are created, the new names havethe syntax: new_var = old_var+"-m", and the new variables become the active data sets.
0.0.0.0 Smooth Data
This process performs boxcar smoothing of the data. A widget will pop up providing options for this operation, You canselecting the resolution of the smoothing window. The default is 61 seconds. You can also determine whether smoothing isdone over the data forward from each point in the data, backward from each point in the date, or centered on each point in thedata.(Default) The smoothing operation supports automatic interpolation to a specific cadence. You can also turn on and off
check boxes determining whether time interpolation is done, whether true time integration is performed, and whether tosmooth NaNs. Finally, you can control the suffix on the output. These options are described in more detail in the header for
the TDAS routine "smooth_in_time.pro"
Select "OK" to process data. "Cancel" or "X" will close the window without processing.

Figure 2.7.3.3

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 High Pass Filter
Click this button to apply a high-pass filter to the data. The options window that pops up allows you to control the width of
the averaging window used to calculate the low pass(which is subtracted from the data to generate the high pass). You canalso automatically interpolate to a specific cadence and control the suffix of the output.

Figure 2.7.3.4
0.0.0.0 Block Average
Click this button to average that data over time. The options window that pops up allows control of the width of each block
over which the average is performed. The average can also be limited to a subset of the time range of the data quantities
being processed. Finally, you can control the suffix of the output.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 3.7.3.5
0.0.0.0 Clip
Clips data of the independent variable(y/z axis) in a group to the selected interval. The options window that pops up allows
control over the minimum and the maximum for the clipping. You can also control whether points adjacent to the out ofrange points are also removed. "Insert Flag" allows a particular value to replace clipped values. Finally, "Insert NaNs"
allows NaNs to be inserted in place of clipped values. You can also control the suffix appended to the output quantities.

Figure 2.7.3.6

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.0 Deflag
Interpolates or repeats the most recent valid data value over gaps in the data (gaps are denoted by NaNs, and can be createdby the clipping process; a “deflag” often happens after NaN values are inserted by a “clip” operation). A window pops up tocontrol the parameters for the deflag routine. You can select the method "Repeat Last Value" which will fill flagged regionswith the value on the boundary of the region, or "Interpolate" which will interpolate between the values at the boundaries offlagged regions. "Set Flag" allows you to specify the value used as the flag, otherwise NaN is assumed. "Set Maximum
Gap" determines the maximum size for a flagged region to be deflagged. You can also control the suffix appended to theresulting quantities.

Figure 2.7.3.7

0.0.0.0 Degap
The degap procedure locates gaps in data, and fills them in with 'NaN' values, so that the plotting process displays the data
gaps correctly (Otherwise it simply draws a line across the gap). It figures out where to add data points by checking whichtime differences are greater than or equal to an input time interval, plus a margin, and inserts equally spaced 'NaN' data points
at time intervals with spacing determined by the size of the data gap divided by the number of points that fit with minimum
cumulative error. "Set Flag" allows a value other than NaN to be specified as a flag, and "Set Maximum Gap" allows the
maximum gap size to be flagged to be set. You can also control the suffix appended to the resulting quantities.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.7.3.8

0.0.0.0 Clean Spikes
This process removes large single point spikes from messy data. Spikes are identified by removing any regions above athreshold that are larger than a smoothed signal subtracted from the signal. The available settings allow control over how big
the difference over the smoothed curve needs to be, and how large a subset of the curve will be included in the smoothing.
You can also control the suffix appended to the resulting quantities.

Figure 2.7.3.9
0 .0 .0 .0 0
Time Derivative
This process takes the time derivative of the active data sets. The available options allow the data to be smoothed before thederivative is calculated, thereby removing very high frequency components in the derivative. You can also control the suffix
appended to the resulting quantities.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.7.3.10
0.0.0.00 Wavelet Transform
The data is split into components, and a basic wavelet transform is performed on each component, with "_wv" appended tothe old variable names. (Note that this is designed for data that are either electric or magnetic field data type. Applying this toother data (e.g., spectrograms) will cause non-intuitive results.)

Figure 2.7.3.11a
Since this process can be very memory-intensive, the user is first asked to specify a time range. A window allows the user to
input start and end times.

Figure 2.7.3.11b
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Note the values shown here are rough estimates of the available memory and estimated memory usage. If they are close, thenit is advisable to click the “NO” button. The process will continue if the “YES” button is pushed. Typical machines have 1 to
2 G-bytes of memory as of this writing (Feb-2009), but if there has been data loaded the available memory may be less. For
Window PCs IDL may be limited to 2 GB or less.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0.00 Power Spectrum
When the Power Spectra button is clicked a new window will be opened containing power spectral parameters that the user
can manipulate. The user can choose between dynamic or time power spectra, and select window size and shift, time range
and how the data is to be binned. The data is split into components, and a power spectrum is obtained from each component.
Appended to the original variable names are "_dpwrspc " or "_tpwrspc” depending on the type of power spectra the user
selected, or a suffix can be selected. Note that this is designed for data that are either electric or magnetic field data type.
Applying this to other data (e.g., spectrograms) will cause non-intuitive results.

Figure 2.7.3.12
0.0.0.00 Coordinate TransformWhen the "Coordinate Transform" button is clicked, a dropdown menu appears with different choices for coordinatetransforms. Each possible output coordinate system has a button. The possibilities are: "SPG" (Spacecraft Probe
Coordinates), "SSL" (Spinning Spacecraft Coordinates), "DSL" (Despun Spacecraft Coordinates), "GSE" (Geocentric Solar
Ecliptic), "GSM" (Geocentric Solar Magnetospheric), "GEI" (Geocentric Earth Inertial),“SM” (Solar Magnetic), "SSE"(Selenocentric Solar Ecliptic), and "SEL" (Selenographic).
Only the active data sets are transformed. The input coordinate systems for the active data sets are automatically obtained.
Data with "Unknown" coordinates and ground-based data will not be transformed. Note that state data for the appropriate
THEMIS probe is necessary for the coordinate transform to occur. If it is not present, then a pop-up will alert the user, andgive the option to load the state data.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Click on the "Transform" button to perform the transformation. Warnings and error messages will appear in the text windowat the bottom, and also in the progress window on the main widget. Click on the "Close" button to dismiss the popup.

Figure 2.7.3.13

0.0.0.00 Interpolate
Selecting the interpolate button opens a window containing interpolation options. This function uses the standard IDL
interpolate routines. Besides manipulating the interpolation parameters the user can also limit the time range and specify thesuffix for the new variable name. Clicking the OK button run the interpolate function on any variables that are in the Active
Data area on the Data Processing window.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.7.3.14

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0Magnetic Field Models

The SPEDAS GUI can be used to generate and trace geomagnetic field models using the IDL Geopack library. The models
currently available from the GUI include IGRF as well as the Tsyganenko 89, 96, 01 and 04 models.
The magnetic field models panel allows you to: Calculate the field model at a position (versus time) Trace the field from a position to the equator (versus time) Trace the field from a position to the ionosphere (versus time)

Figure 3.7.4
The user can switch between different field models by selecting the tab containing the field model they wish to use. The
default field model is Tsyganenko 04. To calculate the field model at a position contained in a TPLOT variable, such as aNAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

THEMIS position vector, first load the required data into the GUI using the File menu. Each tab contains buttons for selecting
the required solar wind and geomagnetic parameters used by each model. Once the required data is loaded into the GUI, open
the Field Models window from the Analysis menu and click “Select a position variable” to choose the previously loaded
TPLOT variable containing position data. Next, select the solar wind and geomagnetic parameters (which can be loaded
using the Load OMNI Data tab in the Load Data window). Finally, select the output variables required (model at position,
trace to equator and trace to ionosphere) and click “Generate”.

0.0 Plugins Menu
Plugins are peripheral GUIs, often mission specific, that interface with SPEDAS through its plugin API. Plugin software canaccess all data stored in the SPEDAS as well as it's graphical features. This allows for custom analysis and automatic
production of customized plots.

0.0.0 GOES Overview PlotsThe GOES Overview Plot window will produce overview/summary plots for a particular GOES spacecraft over a specified
time window. All data for the summary plot will be loaded into the GUI and the overview plot automatically generated on a
new page. Some GEOS data may be overwritten when producing overview plots. Creating a new plot for a particularspacecraft will overwrite all data loaded for previous overview plots for that spacecraft. A URL is also provide to view daily
summary plots on the web.

Figure 2.8.1

0.0.0 THEMIS Overview Plots
The THEMIS Overview plot window will produce overview/summary plots for a particular THEMIS spacecraft for a
specified time window. All data for the overview plot will be loaded into the GUI and a new page containing the overview
NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

plot will be generated. Some THEMIS data may be overwritten when producing overview plots. Creating a new plot for aparticular spacecraft will overwrite all data loaded for previous overview plots for that spacecraft. A URL is also provided toview daily summary plots on the web.

Figure 2.8.2

0.0.0 THEMIS Particle Distribution Slices
The THEMIS Particle Distribution Slices option opens the GUI mentioned in Section 1.5.3.7. From here the user can
generate slices of velocity distributions from THEMIS SST and ESA data. For a detailed description see Section 1.5.3.7
Particle Distribution Slices.

0.0 Page Menu
The Page pull down menu contains options to open, close and toggle between pages. The Page menu options are shown
below in Figure 3.9.1

Figure 2.89.1

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.0.0 New
The New option under the Page pull down menu will open a new page. The new page will be blank since no data or panels
have been selected. Figure 3.8.1 shows an example of a new page. In addition, the new page will be added to the Page pull
down menus. To create new panels on this page select the Plot icon button on the tool bar or the Plot/Layout option under theGraph menu.

0.0.0 Close
The THEMIS GUI allows the user to have multiple pages. If you wish to close a page there are several ways this can be
done. The first is using the Page pull down menu and selecting the Close option. The currently displayed page, or the ‘active’
page will be closed. Other pages will still be available. The main graph area will redraw the first page in the list, unless there
are no more pages, in which case a blank graph area will be drawn. In addition, the Page pull down menu dynamic options
will be updated and renumbered to reflect the change.
Besides the file pull down menu, you can also type Ctrl-Z or select the Close option under the File pull down menu.
It should be noted that once a page is closed the settings that were associated with that page will be lost, unless you requested
Save THEMIS Document under the File pull down menu before you closed the page. The data that was plotted in the page
still remain are available for analysis and plotting. Only the plot settings are deleted.

0.0.0 Pages
The lower portion of the Pages pull down menu contains dynamic menu items and is dependent on the number of pages thathave been created. Figure 3.8 above, shows an example of the pull down menu with three pages. Each of the dynamic menu
items are checked menus. Only one page can be checked or displayed at a time, since only one page can be displayed at atime. The user can toggle between pages by simply clicking the page they wish to view. When new pages are created a newmenu items is added to the list. Likewise, when pages are closed, the menu items are renumbered to reflect the new pagecount. If all pages have been closed, the last page (page one) will be cleared, however it will remain as a blank page.
Similarly, when the GUI is initialized there a blank page is already created.

0.00 Help Menu
The user can view a text version of this document or create a help request form. Figure 2.10 shows the Help pull down menu
options.

Figure 2.10

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide126

0.00.0 Help Window
Clicking on the Help menu and selecting Help Window… will open a dialog box that will provide you with the URL for the
online User’s Guide document. Pressing the “Open Help” button opens the local pdf help file. Figure 2.10.1 shows the help
dialog window.

Figure 2.10.1

0.00.0 Help Request Form
When this button is clicked, a text window pops up displaying the THEMIS Science Help Request Form. This allows the user
to input information about the error which has occurred. There is a save button, which saves the help request form in a file. In
addition to the request form a history file will be saved containing history window and journaling messages. Both files shouldbe emailed to SPEDAS_Science_Support@ssl.berkeley.edu. Click the Close button to dismiss this widget.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Figure 2.10.2

0.00 TPLOT
0.00.0 Import / Export
The GUI maintains an internal representation of the data for its own use. Data loaded into the GUI directly use thethm_load_data routines available in the software distribution. Tplot variables created at the command line can be imported
into the GUI for internal use, or exported from the GUI for command line use. The Load THEMIS Data and Manage Data

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126

Import/Export Tplot items under the File pull down menu provide options to manage the data. See Sections 2.3.5 and 2.3.8
for further details.

0.00.0 tplot_gui
In addition to importing and exporting tplot variables the user can also plot variables from the command line for display
within the GUI. Tplot_gui works in the same way that tplot works, however, tplot_gui will display the plot on a new page in
the GUI graph area. Tplot used in the original way will display the plot in a new window that is external to the GUI. For
example, at the IDL command line you can type the following:
IDL> tplot_gui, ‘tha_fgl_dsl’
Before drawing the plot, the Verify Data panel will be opened. See Section 2.3.8 for details on managing, importing, andexporting data. Once you accept the meta-data values and click the OK button a new page and plot will be created.

0.00 SPEDAS GUI Software Extensions
The following missions are providing packages/plug-ins which are (to be) included in the SPEDAS distribution:a) Energization and Radiation in Geospace (ERG) Mission (plug-in)
Contacts: Yoshizumi Miyoshi (miyoshi@.stelab.nagoya-u.ac.jp),
erg-sc-core@st4a.stelab.nagoya-u.ac.jp
ERG site: http://gemsissc.stelab.nagoya-u.ac.jp/erg/b) Inter-university Upper atmosphere Global Observation NETwork (IUGONET)Contact: Tomoaki Hori Stel (horit@stelab.nagoya-u.ac.jp)
UDAS site: http://www.iugonet.org/en/software.htmlc) Radiation Belt Storm Probes (RBSP) – will be part of TDAS
Contact: Peter Schroder (peters@ssl.berkeley.edu)
RBSP site: http://rbsp.jhuapl.edu/
Details on the GUI API can be found in the TDAS Software Developers Guide.

NAS5-02099 File SPEDAS 1.0/TDAS 9.0 User Guide

126