SPEDAS training session
by courtesy of Arase PWE and MGF team– beginners’ course–

M. Teramoto1, M. Shoji1, S. Matsuda2, T. Hori1, T. F. Chang1, S.
Kurita1, K. Keika3, Y. Miyoshi1
1 ERG Science Center, ISEE, Nagoya University
2 Nagoya University
3 The University of Tokyo

Goal of this training} To get familiar with how to download, read, and plot ERG

satellite data.
•
•
•

•

Download and plot ERG satellite orbit data
Download and plot the MGF and PWE/OFA l2 and PWE provisional CDF
data of ERG satellite
Create and plot multi-tplot variables

Download and plot other scientific instrument data of ERG
satellite(Additional)

Combine other satellite/ground data with ERG satellite data
(Additional)• Coordinate transformation from satellite coordinates(Additional)•

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Space Physics Environment Data Analysis Software(SPEDAS)
SPEDAS frameworkDatarepository

CDF

CDF

CDF
Van Allen
Probes

CDF

ERG satellite
data
Each project develops
and releases APIs toautomaticallydownload and readeach project data

CDF

ERG-related groundobservation
network data
CDF
HDF?

CDF

ERG simulation /modeling data
ERG-SC develops dataarchives and APIs to read thedata from SPEDASSPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

What can you do with SPEDAS?
} time-series plots} filtering of data
} frequency analysis} mapping to the ground maps
} …

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Preparation: before using SPEDASSPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

A few basics of IDL before entering SPEDAS…
}

Insert a comma ( , ) between a command, its arguments, and keywords.
IDL> tplot , 1 , title='New plot'}

A string is expressed as a text sandwiched by delimeters ( ' ) or ( " ).
IDL> print, 'This is a text.'}

An array is expressed as comma-separated elements that are bracketed.
IDL> arr1 = [ 2, 3, 4, 5 ]IDL> string_arr1 = [ 'text1', 'text2', 'text3' ]}Typical errors beginners often encounter:% Attempt to call undefined procedure: '????'.
à command/routine name (????) is misspelled.
% Syntax error.
à , ' ( ) [ ] is missing or mismatched in most cases.

}

Use Up arrow key to reuse previously typed commands. You can edit them with
Left/Right arrow, Backspace keys and execute!
SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Preparation:
Initial setting of SPEDAS for ERG data
Clear out IDL's variables and compiled files

IDL> .full_reset_session
Initialize

IDL> erg_init, remote_data_dir ='https://ergsc.isee.nagoyau.ac.jp/data/ergsc_training/nagoya_201803/'
Setup the username and password to access the ERG Data

ERG> uname = ‘?????'
ERG> pass = ‘???????'

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

memo

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

ERG satellite orbit data

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Orbit data:
Set time range and load ERG orbit data
Setup the time range (‘YYYY-MM-DD/hh:mm:ss’)

ERG> timespan,'2017-03-28/00:00:00’,3,/day
Load orbit data

ERG> erg_load_orb
ERG> tplot_names(*) Using the IGRF model("erg_orb_l2" means ERG Level-2 orbit data)

pos_gse/gsm/sm

s/c position [Re] in GSE, GSM, SM coordinates

pos_rmlatmlt

Radial distance [Re], magnetic latitude [deg], local time [hr] of s/c
position

pos_eqs/c position mapped to the magnetic equator

pos_iono_north/south

Geographic latitude and longitude [deg] of s/c footprints at 100 km
altitude in the northern/southern hemisphere

pos_blocal / blocal_mag

model B-field vector (blocal) and B-field strength (blocal_mag) [nT]at s/c position

pos_beq / beq_mag

model B-field vector (beq) and B-field strength (beq_mag) [nT] at
s/c position mapped to the magnetic equator

pos_Lm

McIlwain's L-parameter of s/c position for pitch angles of 90, 60,
and 30 deg

vel_gse/gsm/sm

s/c orbital velocity [km/s] in GSE, GSM, and SM

man_prep/man_on/eclipse_flagflag for maneuver preparation (man_prep), maneuver on/off (man_on), and solar eclipse (eclipse)

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

tplot variable as the primary data model} ’erg_orb_l2_pos_???' in prev. page is called tplot variable.
} ”tplot variables" bind an indexed name-string to a data

structure on IDL containing time-series data withmetadata.
SPEDAS session#1 'tplot var. name 1'#2 'tplot var. name 2'

Memory space of IDL
time-seriesTimedata 1
array

Dataa
rray

metadata

time-seriesTimedata 2
array

Dataa
rray

metadata

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Orbit data:
Definitive orbit as a time series plot: tplot, tplotxy
Plot orbit time series data

ERG> tplot, 'erg_orb_l2_pos_gsm'
Plot orbit data in the X-Y plane.

ERG> tplotxy, 'erg_orb_l2_pos_gsm'

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Set a date/time range: timespan
ERG> timespan, timestr, N, option
timestr : a string expressing a particular date/timein UTC in the format of 'yyyy-mm-dd/hh:mm:ss'
N : number of time length (Default: 1)
option : unit (/day, /hour, /min, /sec, Default: /day)

For 1 day from 2017-03-28/00:00:00 UTC
ERG> timespan, '2017-03-28'
For 10 min from 2017-03-28/01:31:41 UTC
ERG> timespan, '2017-03-28/01:31:41', 10, /min
SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Listing tplot data & viewing the content: tplot_names,
print_tinfo
ERG> tplot_names
ERG> print_tinfo, ’erg_orb_l2_pos_gse'

The actual data structure bound to tplot variable isshown.

X: time array containing time labels in decimal UNIX time
Y: data array, in this case, a 2-D array of time x 3-components*print_tinfo can be used only for the tplot variables directlycreated from CDF files.
All tplot variables are listed with unique index numbers
SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Separate a tplot variable with vector data: split_vec
ERG> split_vec, 'erg_orb_l2_pos_rmlatmlt'
STORE_DATA(264): Creating tplot variable: ...
STORE_DATA(264): Creating tplot variable: ...
STORE_DATA(264): Creating tplot variable: ...
ERG> tplot, 'erg_orb_l2_pos_rmlatmlt_?'

split_vec takes a tplot variablewith vector or array data to create
new tplot variables containing eachcomponent of the vector/array data.

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Orbit data:
Insert orbit values below a time-series plot
ERG> set_erg_var_label
ERG> tplot;just type "tplot" to replot the previous panels

Using subroutine to add labels(Lm,MLT,MLAT) with time

ERG> split_vec, 'erg_orb_l2_pos_rmlatmlt'
ERG> options, 'erg_orb_l2_pos_rmlatmlt_x', ytitle='R'
ERG> options, 'erg_orb_l2_pos_rmlatmlt_y', ytitle='MLAT'
ERG> options, 'erg_orb_l2_pos_rmlatmlt_z', ytitle='MLT'
ERG> tplot_options, var_label=['erg_orb_l2_pos_rmlatmlt_z','erg_orb_l2_pos_rmlatmlt_y', 'erg_orb_l2_pos_rmlatmlt_x']
ERG> tplot(Lm, MLAT, MLT)

An example to add
new labels(R,MLAT,MLT)(R, MLT, MLAT)SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Decorate the plot panel: options, tplot_options
Sets options for each tplot variable.
options, varname, option1='…', option2='…', …
varname: tplot variable name (wildcards accepted)
option?: name of tplot variable attribute

Sets global options for the "tplot" routine.
tplot_options, toption1='…', toption2='…', …
toption?: global options to be set
ERG> tplot_options, /help
Show the current tplot options

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

memo

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Scientific instrument data of ERG satellite:
MGF and PWE data

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
MGF L2 data
Reset time range (No extra keyword: one day)

ERG> timespan, '2017-03-28'
Load Magnetic field data

ERG> erg_load_mgf, uname=uname,pass=pass
ERG> tplot,'erg_mgf_l2_mag_8sec_gse'

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Change the vertical scale of a plot: ylim
ylim, varname, ymin, ymax, logflag
varname : variable name(s)ymin/ymax : lower/upper limit along vertical axis
set both to 0 (zero) for plotting with auto-scale
logflag : set 0 (zero) for plotting on a linear scale, or 1 for a log scale

ERG> ylim, 'erg_mgf_l2_mag_8sec_gse', -300,300,
ERG> tplot, 'erg_mgf_l2_mag_8sec_gse'0

Zoomed in a more limited
range in the vertical scale.

Tips:
Putting 0 for both ymin and ymax sets the y range toauto-scale.
ERG> ylim, 'erg_mgf_pr_mag_8sec_gse', 0, 0

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
PWE and MGF data
Load PWE data
ERG> erg_load_pwe_pre, uname=uname, pass=pass
ERG> tplot, [ 'erg_mgf_l2_mag_8sec_gse' , 'erg_pwe_pre_HFA-merged' ,'erg_pwe_pre_OFA_E_spectra_132' , 'erg_pwe_pre_OFA_B_spectra_132' ,'erg_pwe_pre_EFD_DPB_spectra' ]SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Change the time range of a plot: tlimit
Select a time period by mouse-clicks on the plot window
ERG> tlimit
Specify a time period explicitly

ERG> tlimit, '2017-03-28/00:00' , '2017-03-28/08:00'
Back to the last plot period
ERG> tlimit, /last

Restore the original plot periodthat was set by timespan
ERG> tlimit, /full

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
PWE/OFA L2 data
Load PWE/OFA L2 data
ERG> erg_load_pwe_ofa, uname=uname, pass=pass
ERG> tplot, [ 'erg_mgf_l2_mag_8sec_gse' , 'erg_pwe_pre_HFA-merged' ,'erg_pwe_ofa_spec_l2_E_spectra_132’ ,'erg_pwe_ofa_spec_l2_B_spectra_132, 'erg_pwe_pre_EFD_DPB_spectra' ]SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
Checking CDF attributes: show_cdf_att
All the global and variable attributes are shown in this panel.

ERG> show_cdf_att, tvar

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

memo

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Access the data structure in a tplot variable andcreate a new tplot variable (get_data, store_data)

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Access the data structure in a tplot variable: get_data
ERG> get_data, varname, data=data, dlimits=dlimits, lim=lim
varname: tplot variable
data: the data structure is stored
dlimits: most of metadata are stored
lim: some plot properties are stored
ERG> help, data.x , data.y"get_data" extracts the data structureof a tplot variable and saves in a
structure "data" of IDL session in theabove case, so that users can accessthem by referring to as "data.x" or"data.y", for example.

The information on the original CDF data
file (CDF) and metadata, and various plot
properties are extracted into a structure"dlimits".

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Tips: structure variables in IDLCreating a structure in IDL
Structure = {tag1: var1, tag2: var2, …}
Structure = create_struct(tag1, var1, tag2, var2, …)Referring to a field within the structure
Structure.tag1
Structure.(tag_num)

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Create a new tplot variable:store_data
ERG> store_data, varname , data = { x:timearr, y:datarr }varname: name of a newly created tplot variable (should be a character)timearr: 1-D array containing time values in SPEDAS time of time-series datadatarr: 1-D or 2-D array containing the data values of time-series data. The size of 1st dimension should
be identical to that of timearr.

}}}

SPEDAS time is the UNIX time in double-precision floating-point values. UNIX time is theelapsed second since 00:00 UTC on January 1, 1970.
Usually we use time_double() function to calculate a SPEDAS time value from a time stringsuch as '2017-03-28/12:30:00'.
SPEDAS time values can easily be converted to time strings with time_string() function.

Please refer to the SPEDAS wiki at
http://spedas.org/wiki/index.php?title=Time_handlingfor more details of the time handling in SPEDAS.

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Create and plot multi-tplot variables with PWE data
Get data from tplot Variable and save the data array

ERG> get_data, 'erg_mgf_l2_magt_8sec', data=data
Calculate the electron cyclotron frequency

ERG> fce = data.y / 10^(9.) * 1.6 * 10^(-19.) / (9.1093D * 10^(-31.)) / 2. / !pi /1000.
ERG> fce_half = fce / 2.

Create and store the data with the new variable name

ERG> store_data, 'fce', data={x:data.x, y:fce}, dlim={colors:fsc_color('yellow')}
ERG> store_data, 'fce_half', data={x:data.x, y:fce_half},

dlim={colors:fsc_color(‘magenta')}
ERG> tplot,['erg_pwe_pre_HFA-merged', 'erg_pwe_ofa_spec_l2_E_spectra_132', 'fce','fce_half']

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Create and plot multi-tplot variables with PWE data
Create and store the multi-data with the new variable name
ERG> store_data, 'erg_pwe_pre_HFA_merged_gyro', data =['erg_pwe_pre_HFA_L_spectra_ey','erg_pwe_pre_HFA_H_spectra_ey','fce']
ERG> store_data, 'erg_pwe_ofa_spec_l2_E_gyro', data =['erg_pwe_ofa_spec_l2_E_spectra_132', 'fce','fce_half']
ERG> store_data, 'erg_pwe_ofa_spec_l2_B_gyro', data =['erg_pwe_ofa_spec_l2_B_spectra_132', 'fce','fce_half']
Set the yrange of tplot ( min, max, 0 for linear / 1 for log )ERG> ylim, 'erg_pwe_pre_HFA_merged_gyro’, 1, 1e4, 1
ERG> ylim, 'erg_pwe_ofa_spec_l2_E_gyro', 0.032, 20, 1
ERG> ylim, 'erg_pwe_ofa_spec_l2_B_gyro', 0.032, 20, 1
ERG> tplot, ['erg_pwe_pre_HFA_merged_gyro', 'erg_pwe_ofa_spec_l2_E_gyro','erg_pwe_ofa_spec_l2_B_gyro’]

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Dump to png and postscript files
To get a png file or postscript file
ERG> cwd;Display the current directory
CWD(25): Directory changed to: /yyyy/xxxx
ERG> tplot
ERG> makepng, ’erg_pwe_plot';à erg_pwe_plot.png
ERG> popen, ’erg_pwe_plot'
ERG> tplot;Redo the last plot
ERG> pclose ; à atha_plot.ps/yyyy/xxxx/erg_pwe_plot.png

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Power spectrum at a particular time
ERG> t_index = nn('erg_pwe_ofa_spec_l2_E_spectra_132', '2017-03-28/18:53')
ERG> get_data, 'erg_pwe_ofa_spec_l2_E_spectra_132’ , data=ofa_e_spec
ERG> tf_index = nn('fce_half ', '2017-03-28/18:53’)
ERG> get_data,'fce_half ', data=data_fce_half
ERG> plot, ofa_e_spec.v, ofa_e_spec.y[t_index,*],$
ERG> /ylog,/xlog,xstyle=1,xrange=[0.032,20],$
ERG> xtitle='Frequency[kHz]',ytitle='Power[mV^2/m^2/Hz] 'ERG> oplot, [data_fce_half.y[tf_index],data_fce_half.y[tf_index]],[1e8,1],color=fsc_color(‘green’)

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

ERG / Arase
Online information}- Quick Looks
https://ergsc.isee.nagoya-u.ac.jp/cef/erg_1day.cgi}- ERG-SC
https://ergsc.isee.nagoya-u.ac.jp/}- CIDAS system
http://cidas.isee.nagoya-u.ac.jp/kyodo/cidas.shtml.ja

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

memo

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Frequency analysis of tplot data

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Dynamics spectra – tdpwrspc–
tdpwrspc, 'varname'varname : tplot variable name(s)ERG> tdpwrspc, 'thg_mag_atha-d'
ERG> tplot_names… … … …
5 tha_mag_atha-d_hpfilt… … … …
9 thg_mag_atha-d_x_dpwrspc
ERG> tplot, [ 5, 9 ]FFT with the hanning window isapplied to derive dynamic
frequency spectra of the data.

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Wavelet analysis – wav_data –wav_data, 'varname'varname : tplot variable name(s)wav_data accepts data with less than 32768
ERG> split_vec, 'thg_mag_atha-d'samples. The number of data points is reduced as
ERG> avg_data, 'thg_mag_atha-d_x', 5.
done with avg_data in this case.
ERG> wav_data, 'thg_mag_atha-d_x_avg'
STORE_DATA(264): Creating tplot variable: 13 thg_mag_atha-d_x_avg_wv_pow
ERG> tplot, 'thg_mag_atha-d_x_avg*'
ERG> zlim, 13, 100, 1000000, 1
ERG> tplot, 'thg_mag_atha-d_x_avg*'

Wavelet analysis is applied to derive
dynamic spectra of the data.
zlim is similar to "ylim" command,but set the lower/upper limit of thecolor scale for a spectrum-type plot.

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Other information sources for SPEDAS}SPEDAS wiki}

http://spedas.org/wiki/index.php?title=Main_Page}}

Change log of the source repository for the bleeding edge of SPEDAS}}

User's guide, Plug-in developer's guide, tips and tricks, The list of available crib sheets,…

http://spedas.org/changelog/

Crib sheets for TPLOT in Your_SPEDAS_dir/idl/general/examples/
}
}
}
}
}
}

crib_tplot.pro -- basic tplot intro
crib_tplot_annotation.pro -- How to control annotations in tplot (labels, text,
etc...)
crib_tplot_export_print.pro -- How to export tplot data and tplot plots
crib_tplot_layout.pro -- How to control tplot plot layouts
crib_tplot_range.pro -- How to control the range and scaling of tplot plots
crib_tplot_ticks.pro -- How to control tplot plot ticks. (location, size, etc...)SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Scientific instrument data of ERG satellite:
Particle data

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
MEP-e 3-D flux data
Load MEP-e data

ERG> erg_load_mepe, uname=uname, pass=pass
Plot magnetic field and MEP-e data

ERG> tplot,['erg_mgf_l2_mag_8sec_gse','erg_mepe_l2_3dflux_FEDU’, 'erg_mepe_l2_3dflux_FEDO']SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
Load the other particle data
Loading LEP-i, MEP-e, MEP-i, HEP and XEP data
ERG> erg_load_lepi_pre, uname=uname, pass=pass
ERG> erg_load_lepe_pre_omniflux, uname=uname, pass=pass
ERG> erg_load_mep_pre, species='i', datatype='omni', uname=uname, pass=pass
ERG> erg_load_hep_pre_omniflux, uname=uname, pass=pass

ERG> erg_load_xep_pre, uname=uname, pass=pass
ERG> tplot_names... …
26 erg_mgf_l2_mag_8sec_dsi……
60 erg_mepe_l2_3dflux_FEDO
61 erg_lepi_pre_FEDO
62 erg_lepe_pre_FPDO……
66 erg_mepi_omni_FPDO……
70 erg_hep_pre_FEDO_L
71 erg_hep_pre_FEDO_H
72 erg_xep_pre_count……

Please remember the index numbers of these tplot
variables on your screen:
they could differ for different person, depending on inwhat order you have loaded variables.
The numbers are used for the plot in the next slide!
SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:
Put other particle data together to the plot
ERG> tvar = [ 26, 72, 70, 71, 60, 62, 61, 66]

Please line them up in the order, from top to bottom, of.

ERG> tplot, tvar

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

memo

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Sample cases of ERG data analysis

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Data analysis:
3-day plot of XEP data and geomag. indices
ERG> timespan, '2017-06-16', 3, /dayLoad HEP data

ERG> erg_load_hep_pre_omniflux, uname=uname, pass=pass
Load other index data

ERG> omni_hro_load, /res5min
ERG> tplot,[ 'OMNI_HRO_5min_SYM_H' ,'OMNI_HRO_5min_AL_INDEX' , 'erg_hep_pre_FEDO_*' ]SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Onboard instrument data:

Coordinate transformation of MGF data
Coordinate transformation (SGA, SGI, DSI, J2000)
From J2000 to the geophysical coordinates -------> using “cotrans”

ERG> erg_cotrans, 'erg_mgf_l2_mag_8sec_dsi', 'mgf_j2000',in_coord='dsi', out_coord='j2000'
Coordinate transformation (SM<-->J2000)

ERG> spd_cotrans, 'mgf_j2000', 'mgf_gsm', in_coord='j2000',
out_coord='gsm'

ERG> tplot, ['mgf_gsm', 'erg_orb_l2_pos_blocal']

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018

Data analysis:
Frequency analysis of MGF data
Please prepare a tplot variable "mgf_sm" containing the magnetic field vectors in SM
coordinates for March 28
ERG> timespan, '2017-03-28’, 1, /dayDynamic spectra by FFT with the Hanning window
ERG> tdpwrspc, 'mgf_sm'
ERG> wav_data, 'mgf_sm_z' Dynamic spectra by a wavelet analysis
ERG> tplot,'mgf_sm_z*'

Use tlimit to zoom in aperiod between perigee
points!

SPEDAS training session, ERG wave data WS @ISEEMarch 28, 2018