2018/5/28

How to use UDAS egg
UDAS egg provides users with the templates for IDL procedures that can load their own data files intothe SPEDAS (Space Physics Environment Data Analysis Software)/IDL (Interactive Data Language).
According to this document, the users can easily create the load procedure for their data by modifying
the template procedure (about 10 lines identified in this routine). As of May 2018, it supports CDF(Common Data Format) and ascii format.
(0) Rules of the road
When you use the UDAS egg, please refer to the rules of the road of the IUGONET project:
Rules of the road: http://www.iugonet.org/rules/
Please note that we do not take any responsibility or liability for any damage or loss caused by theUDAS egg.
(1) System Requirements
OS: Windows、MacOSX、Linux
IDL: v8.0 or higher
SPEDAS：v2.0 or higher (v3.0 is recommended)(2) Supported file formats(2-1) CDF（Common Data Format）(2-2) ascii format
The current version supports three format types (0-2) shown as follows:0) Time series data arranged in the following order (i.e., date, time, and data);----------------------------------------------------2018-03-01 00:00:00

ydata1[0]ydata2[0]ydata3[0]…

2018-03-01 00:00:01

ydata1[1]ydata2[1]ydata3[1]…

2018-03-01 00:00:02

ydata1[2]ydata2[2]ydata3[2]…

2018-03-01 00:00:03

ydata1[3]ydata2[3]ydata3[3]…

2018-03-01 00:00:04

ydata1[4]ydata2[4]ydata3[4]…

----------------------------------------------------where ydata1, ydata2, ydata3, … are the column data.
1As for the date and time format string, various formats are acceptable, for example,
YYYY-MM-DD/hh:mm:ss
YYYY MMDD hh mm

YYYY,MM,DD,hh,DDhhmm ssyyMMhhmm ssssmm,

ss：One or more strings for the delimiter of data can be specified by keyword.
The loaded data can be plotted with lines by “tplot” command, as shown below.
The figure below shows an example of the line plot of the magnetic field vectors.

1) Time series data that includes more than one row data at the same time. For example,----------------------------------------------------2018-03-01 00:00:00

vdata[0]ydata1[0]ydata2[0]ydata3[0] …

2018-03-01 00:00:00

vdata[1]ydata1[1]ydata2[1]ydata3[1] …

2018-03-01 00:00:00

vdata[99]ydata1[99]ydata2[99]ydata3[99]2018-03-01 00:01:00

vdata[0]ydata1[100]ydata2[100]ydata3[100]…

2018-03-01 00:01:00

vdata[1]ydata1[101]ydata2[101]ydata3[101]…

vdata[99]ydata1[199]ydata2[199]ydata3[199]…

：：…

：2018-03-01 00:01:00

2

：----------------------------------------------------where vdata repeats every time, for example, altitude for the atmosphere data, frequency for thespectral data, and range for the radar data.
The loaded data can be drawn in color by “tplot” command. The figure below shows an example ofthe color plot of the wind velocity, where the vertical axis shows vdata (alitutde) and the color shows
ydata (wind velocity).

2)This format is similar to 1, but the data are arranged in a row, as shown below;----------------------------------------------------2018-03-01 00:00:00

ydata[0]2018-03-01 00:01:00
2018-03-01 00:02:00

ydata[1]ydata[2]… ydata[99]ydata[100] ydata[101]ydata[102]… ydata[199]ydata[200] ydata[201]ydata[202]… ydata[299]：----------------------------------------------------Similarly to 1, the loaded data can be drawn in color by “tplot” command. The vdata corresponding to
the vertical axis must be given by keyword.

(3) Preparation
1. Confirm URL of the website which includes data files you want to load, or copy the data files onyour PC.
3

2. Download udas_egg_x_xx.zip on your PC. Copy it to the directory you want and resolve it.
3. Set IDL path to udas_egg_x_xx.

(4) How to create your load procedure
1. Duplicate loadproc_template_xxx.pro and change the file name to your defined name.
2. Open the file by a text editor and change the procedure name (loadproc_template_xxx) to yourdefined name.
3. Edit the file.
Modify the parameters marked by “Step 1-4” in the file.
3-1.

Step1: Set parameters

local_data_dir : A base directory in which downloaded data files are stored. The “root_data_dir”
function returns “C:/data/” for Windows, “/disks/data/” or “~/data” for Mac and Linux. You can
set a relative path from the base directory in Step2.
remote_data_dir : A base URL of the website which includes data files. If the data files are not open
to public but only in your PC, please input any string such as a space '' (i.e., remote_data_dir= ' '). You can set a relative path from the base URL in Step2.
acknowledgement : You can write data usage policy here. When you run this load procedure, thispolicy will be displayed in the command window.
site_list : If there are several kinds of data files, you can set this array of string. Here, it is assumed
that there are some observation sites. If there is no site or only one site, please input any dummy
string to site_list and delete the keyword “site”.
datatype_list : If there are several kinds of data files, you can set this array of string. For example, thedatatype is a parameter such as sampling interval, wavelength, observation mode, and file version.
If there is no parameter, please input any dummy string to datatype_list and delete the keyword“datatype”.
3-2.

Step2: Set a relative path from the base URL (pathnames) and file name (filenames)

pathnames : Specify a relative path from “remote_data_dir”. For example, if the data files are in“http://iugonet.org/data/sitename/YYYY/MM/”, then you can set
remote_data_dir = 'http://iugonet.org/data/'
pathnames = site[isite] + '/YYYY/MM/'
filenames : Specify the format string of the file name. For example, if the file name is “(sitename)_YYYYMMDD.txt”, then you can set
4

filename = site[isite] + 'YYYYMMDD.txt'*** The downloaded files are stored in the directory: local_data_dir + pathnames.
*** If you want to load data files from you PC, please put them in the directory: local_data_dir +pathnames.
3-3.

Step3: Set parameters for reading data files

3-3-1. In case of CDF
The parameters are used for the “cdf2tplot” function.
The “cdf2tplot” loads data from CDF files and creates tplot variables whose names are definedin the CDF files. So, the name of the tplot variables are automatically determined.
prefix : A prefix which is added to the loaded tplot variables.
suffix : A suffix which is added to the loaded tplot variables.
varnames : If you know the name of variables defined in the CDF files, you can specify which datawill be loaded by this keyword.
3-3-2. In case of ascii format
The parameters are used for the “cdf2ascii” function.
format_type : You can specify the type of ascii format shown in (2-2). Please choose a number from 0to 2.
tformat : Format string for date and time. For example, the following formats are acceptable:'YYYY MM DD hh mm ss''YYYY-MM-DD/hh:mm:ss.fff''YYYY/MM/DD hh:mm:ss''yy MM DD hh mm ss'
As for the time format, please refer to the “time_parse” procedure:
http://themis.ssl.berkeley.edu/socware/spedas_3_00/idl/general/misc/time_spd_doc_list.html#TIME_PARSE
tvar_column : A scalar or a vector that identifies the column number for output. For example,
tvar_column = 0
tvar_column = [0,1,2,3]
tvarnames: A string or string array for output tplot variable names. For example,
tvarnames = 'var_' + site[isite] + '_' + datatype[idt]creates the tplot variables named “var_(sitename)_(datatype)”
The “tvarnames” has usually the same number of element as that of “tvar_column”.
Exceptions:
When format_type=0, the setting of tvar_column=[0,1,2,3] and tvarnames='tvar1' creates the5variable “tvar1”, which includes four vectors. If you set tvar_column=[0,1,2,3] andtvarnames=['tvar1', 'tvar2', 'tvar3', 'tvar4'], each tplot variable “tvar1” to “tvar4” has each vector
identified by tvar_column=0 to 3.
When format_type=2, tvar_column is not used and tvarnames must be a scalar.
delimiter : A scalar string that identifies the end of a field. One or more single characters are allowed,
for example,
delimiter=','delimiter='/:,'
data_start : Number of header lines you want to skip. For example,
data_start=10
comment_symbol : A string that identifies the character used to delineate comments. For example,
comment_symbol='%'comment_symbol=';'v_column :A scalar that identifies the number of column of vdata, where vdata[1:nx,1:nv] is used to create
tplot variations by the command as follows;store_data, tvarnames, data={x:xdata, y:ydata, v:vdata}.
xdata[1:nx] is made from date and time and ytada[1:nx,1:nv] is identified by tvar_column.
This keyword is used in the case of format_type=1.
vvec :
A vector for vdata, where vdata[1:nv] is used to create tplot variations by the command as
follows;
store_data, tvarnames, data={x:xdata, y:ydata, v:vdata}.
This keyword is used in the case of format_type=2.
time_column :If this keyword is set, "tformat" is not used. A vector with 6 elements that shows the existence ofdate and time data, [year, month, day, hour, minute, second] in the ascii file. For example, if thedata file includes the columns for [hour minute second] only, thentime_column = [0, 0, 0, 1, 1, 1]
input_time :You need to set this keyword if the “time_column” is set.
For example, if the data file includes the columns for [hour minute second] only, then you needto set [year, month day] as follows;
input_time = [2017, 3, 1, 0, 0, 0]
3-4.

Step4: Set options for loaded tplot variables
6

For example, the following commands can be used here.
tclip : Replaces the values of the tplot variable that are beyond the specified limits with NaN.
ylim : Set y-axis limits for plotting.
options : Set some options for plotting, for example, labels for the x- and y-axes, color and labels
for lines, etc. For “options”, please refer tohttp://themis.ssl.berkeley.edu/socware/spedas_3_00/idl/general/tplot_spd_doc_list.html#OPTIO
NS(5) References
There are some examples of the load procedures created from the UDAS egg in the “examples”
directory.

7