This file is a guide to the thx_data_*-* directory.
Author: Vladimir Kondratovich, SP Systems, Inc
Date: November 1, 2008

1. NOTATIONS

Data files cover the full time interval for each event. All file names contain start and end times 
in the format yyysmsdshs-yyyemedehe. Names contain a letter denoting THEMIS probe 
(x = a to e). The correspondence between letter and number for THEMIS probes is: 
b c d e a for 1 2 3 4 5.

For example, the data directory tha_data_2008081815-2008081906 contains data collected 
by THEMIS-a (or THEMIS-5) probe from 2008/08/18 15:00 to 2008/08/19 6:00 UT.

2. DATA FORMAT

Data are ASCII files with headers explaining the kind of data, units, and format. Each file then 
contains a format string for automated reading in IDL (code read_data.pro is 
enclosed). The third line indicates the number of records (to speed up reading). The first column 
provides the date string in THEMIS format yyyy-mm-dd/hh:mm:ss.mil . It can be 
converted to and from the UNIX time with the help of time routines from the THEMIS TDAS 
software package. Numerical records are written by IDL in G format. Occasionally, 
they may contain NaN (not-a-number symbol by IDL).

We provide a universal IDL reader read_data.pro to read our (uncompressed) data and 
flag files. The reader substitutes NaN by 0 (zero) and issues a warning message that should 
be ignored. You can correct this default treatment of NaNs at your convenience - 
see further explanations in the code read_data.pro. The reader should be able to read 
all our data files created after November 1, 2008. For earlier data files, you have to 
adjust the format manually.

3. DATA CONTENT

3.1. DataMerged

Subdirectory DataMerged contains merged THEMIS data used for plotting. THEMIS data 
contain up to 4 data streams for physical quantities displayed on our plots. Our code 
evaluates the time coverage provided by these data streams and takes the one with 
the best coverage as the major data stream. Then it evaluates whether or not the 
remaining data streams can patch gaps in the time coverage of the major data stream 
(we do not intersperse data because the calibration process may be different for 
different streams). A flag file tracking the data sources is created. The following 
data are stored in the directory DataMerged:

b_data_thx_*-* contains GSM components of magnetic field;
b_flag_thx_*-* contains corresponding flags;

e_data_thx_*-* contains GSM components of electric field;
e_flag_thx_*-* contains corresponding flags;

ed_data_thx_*-* contains the electron density;
ed_flag_thx_*-* contains corresponding flags;

esp_data_thx_*-* contains the electron spectrogram;
esp_flag_thx_*-* contains corresponding flags;

etemp_data_thx_*-* contains the electron temperature tensor in FAC;
etemp_flag_thx_*-* contains corresponding flags;

id_data_thx_*-* contains the ion density;
id_flag_thx_*-* contains corresponding flags;

isp_data_thx_*-* contains the ion spectrogram;
isp_flag_thx_*-* contains corresponding flags;

itemp_data_thx_*-* contains the ion temperature tensor in FAC;
itemp_flag_thx_*-* contains corresponding flags;

iv_data_thx_*-* contains the ion velocity in GSM (from ESA moments);
iv_flag_thx_*-* contains corresponding flags;

sc_coords_thx_*-* contains the s/c coordinates in GSM;
sc_vels_thx_*-* contains the s/c velocity in GSM;

v_data_thx_*-* contains the measured s/c potential or a fill value;
vcalc_data_thx_*-* contains the calculated cutoff potential (NaN if the calculation diverges).

3.2. DataBNC

Subdirectory DataBNC contains vector data transformed to the Boundary-Normal 
Coordinates (BNC, called also LMN) with respect to the nominal magnetopause 
(Sibeck's model). The following data are stored in the directory DataMerged:

b_lmn_thx_*-* contains LMN components of magnetic field;
b_flag_thx_*-* contains corresponding flags;

e_lmn_thx_*-* contains LMN components of electric field;
e_flag_thx_*-* contains corresponding flags;

iv_exb_lmn_thx_*-* contains the ion velocity in LMN (from ExB);
iv_exb_flag_thx_*-* contains corresponding flags;

iv_mom_lmn_thx_*-* contains the ion velocity in LMN (from ESA moments);
iv_mom_flag_thx_*-* contains corresponding flags;


4. RELATED READING

File DescriptionMCD.doc gives a general description of this Magnetopause Crossing 
Database. It is available for download on the GIFWALK pages 
http://cdaweb.gsfc.nasa.gov/cgi-bin/gif_walk

Pull-down menu "Data/Data Description" on THEMIS web site 
http://themis.ssl.berkeley.edu leads to a description of THEMIS variables, which is
helpful for understanding the data source abbreviations used in this database.
