IDL/SPEDAS tutorial featuring Arasedata...brought you byCenter for Heliospheric Science
ISEE, Nagoya Univ.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

1

Goal of this tutorial• We are going to learn how to load, plot, and manipulate
ERG satellite data as well as other related observation
data using IDL/SPEDAS.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

2

Keep in mind upon the tutorial• This is a "hands-on" tutorial for IDL/SPEDAS, not a time for email check!
• Communicate with the lecturer, tutors, and neighboring skilledusers.
• Today's session might not be able to cover all topics in thetutorial slides due to time limitation. It is highly recommended
to go through the entire contents later by yourself.
• We will proceed rather slowly with intermediate-level users,
but you can practice at your own pace.
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

3

What's SPEDAS?

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

4

Space Physics Environment Data Analysis System (SPEDAS)
SPEDAS
frameworkDatarepository

CDF

CDF

CDF
Van Allen
Probes

CDF

Each project
develops andreleases APIs toautomaticallydownload and readeach project data

ERG
satellite
data
CDF

ERG-related groundobservation network
data
CDF
HDF?

CDF

Mar. 15, 2024

ERG simulation/ modelingdata
ERG-SC develops dataarchives and APIs toread the data from
SPEDAS

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

5

What can you do with SPEDAS?
• loading Arase data and other related data
• time-series plots• filtering of data
• frequency analysis• mapping to the ground maps
• ...

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

6

Basics of SPEDAS:
tplot and tplot variable

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

7

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!

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

8

How SPEDAS works?
One of the simplest procedures would be:
1. Run IDL
2. Initialize the SPEDAS environment on IDL
3. Set a date/time range for which data are loaded.
4. Load data
5. (Manipulate the loaded data)
6. Plot the data

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

9

How SPEDAS works? (cont'd)
In SPEDAS command lines,
prompt> idl
IDL> erg_init
ERG> timespan, '2017-05-27', 7, /day
ERG> erg_load_mgf(manipulate tplot variables)
ERG> initct, 1080, line_clrs=7;; colormap setting

ERG> tplot, ['erg_mgf_l2_mag_8sec_dsi', 'erg_mgf_l2_magt_8sec']Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

10Set a date/time range
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-05-27/00:00:00 UTC
ERG> timespan, '2017-05-27'
For 90 min from 2017-05-29/03:25:30 UTC
ERG> timespan, '2017-05-29/03:25:30', 90, /minMar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

11tplot variable as the primary data model• 'erg_mgf_l2_mag_8sec_dsi' 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'

Mar. 15, 2024

Memory space of IDL
timeTime
seriesarray
data 1Data
array

metadata

timeseries Timedata 2 array

Data
array

metadata

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

12

Ex: How the MGF load procedure works
SPEDAS session
Request to download

PC

ERG> erg_load_mgf

f il

e

on

yo
ur

erg_mgf_l2_mag_8sec_dsi
…

St
or
e

CD

F

load as tplot vars.
erg_mgf_l2_8sec_20170501_v03.
04.cdf・・・

Mar. 15, 2024

1 year latency for each ERG productWorking group password is required for thedata within 1 year after observation.

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

13

Data Products of Arasenn

Overview of the ERG projectnMiyoshi et al., EPS, 2018a
ERG Science CenternnOrbit（predict/definitive, L2/L3）

nAttitude（L2）n

MGF（pre/L2）

Miyoshi et al., EPS, 2018bnn

PWE（pre/L2/L3）nKasahara et al., EPS, 2018n

Kumamoto et al., EPS, 2018nOzaki et al., EPS, 2018n

Matsuda et al., EPS, 2018nKasaba et al., EPS, 2017n

XEP（L2/L3/L4）n

HEP (HEP-H/HEP-L, pre/ L2/L3/L4)nnnKasahara et al., EPS, 2018

LEPi(pre/L2/L3/L4)nn

Yokota et al., EPS, 2017

MEPe(pre/L2/L3/L4)nnMitani et al., EPS, 2018

MEPi(pre/L2/L3/L4)nAsamura et al., EPS, 2018

LEPe(pre/L2/L3/L4)
nMar. 15, 2024

Matsuoka et al., EPS, 2018

Kazama et al., EPS, 2017

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

14

Listing tplot data & viewing the content
ERG> tplot_names
ERG> print_tinfo, 'erg_mgf_l2_mag_8sec_dsi'

All tplot variables arelisted with unique index
numbersMar. 15, 2024

The actual data structure bound to tplot variable'erg_mgf_l2_mag_8sec_dsi' is shown.

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
IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

15

Listing tplot data & viewing the content
ERG> tplot_names, 'erg_mgf_l2_mag_8sec_dsi', /verbose
ERG> tplot_names, 1, /v

Metadata (informationon the data) are
dumped.
RULES_OF_USE carries"rules of the road" inusing the data.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

16

Rules of the road (Statements on data policy)• All data users should follow
the Rules of the road.
• Users are encouraged toreport any suspicious data
to the PI. (erg_xxx_info@isee.nagoya-u.ac.jp)

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

17

Important tips for the color
table
Two commands exist in SPEDAS to define a color table:• loadct2• initct
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

18

Color table setting with loadct_sd
loadct_sd, num(num: the number of color table)

accepted keywords:
center_hatched, hatched_width, hatched_color

FAST-special(default)

SD Cutlass

SD APL

JET

ViridisTurboloadct_sd overwrites
color tables of No.
43–48 with those on
the left.

loadct_sd, 42 or 43

loadct_sd, 44

loadct_sd, 45

loadct_sd, 46loadct_sd, 47

loadct_sd, 48

color-blind friendly
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

19

Color table setting with loadct_sd
ERG> loadct_sd, 48, /center_hatched
ERG> loadct_sd, 48, /center_hatched, hatched_color=5
ERG> loadct_sd, 48, /center_hatched, hatched_color=5, hatched_width=60/center_hatched insertss "white"around the middle of a color scale.

Mar. 15, 2024

hatched_color replaces "thewhite" for hatching with anarbitrary color.

hatched_width can change thewidth of the hatched area.
(default: hatched_width = 20)

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

20

More standardized way of setting the color table with initct
ERG> window
ERG> initct, 1080 ;; 1000–1074 are the same as 0–74 of loadct except 41–43, while 1075–1118 are the originals
ERG> initct, 1080, line_clrs=7
ERG> plot, [0],[0] & draw_color_scale, rang=[0,1], pos=[0.2,0.2,0.25,0.8]
ERG> for i=0, 6 do plots, [0.4,0.8],[0.8,0.8]-0.1*i, color=i, linestyle=4, thick=2
ERG> initct, 1080, line_clrs=8
ERG> plot, [0],[0] & draw_color_scale, rang=[0,1], pos=[0.2,0.2,0.25,0.8]
ERG> for i=0, 6 do plots, [0.4,0.8],[0.8,0.8]-0.1*i, color=i, linestyle=4, thick=2

7 line colors are those optimized for color-blind individuals [Wong, Nature Methods, 2011].
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

21

In this tutorial...
Either of the following 4 color tables are used in thistraining material:loadct_sd, 48
Turbo

Mar. 15, 2024

initct, 1072

initct, 1080

CB-RdYlBu

Viridisinitct, 1079

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

Plasma22

Resources• The color table list and how to use colormaps of thematplotlib in python:• IDL memo by Nishida-san, Kwasan Observatory, Kyoto Univ.
https://www.kwasan.kyoto-u.ac.jp/~nishida/idl/defaultcolortable.html
Please pay attention to not only the color table but also the size of characters in the slides!

!p.charsize = 1.0 (default)

Mar. 15, 2024

!p.charsize = 1.6

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

23

Manipulate and decorate
plot panels

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

24

Plotting a tplot data by tplot
Tplot with tplot variable names (string)
ERG> tplot, 'erg_mgf_l2_mag_8sec_dsi'
ERG> tplot, [ 'erg_mgf_l2_mag_8sec_dsi' , 'erg_mgf_l2_mag_8sec_gse' ]Tplot with the index number of a tplot variable

ERG> tplot, 1
With an array of variable indices to combine multiple variable in a single plot window

ERG> tplot, [2,1]Some wildcards can be used

ERG> tplot, 'erg_mgf_l2_mag_8sec_*'

The tplot command accepts
variables as arguments invarious formats.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

25

Useful manipulators for tplot: tplot_remove_panel, tnames_cp()
ERG> tplot, 'erg_mgf_l2_mag_8sec_*'

Then run tplot, [1,4]ERG> tplot_names, /current
1 erg_mgf_l2_mag_8sec_dsi
2 erg_mgf_l2_mag_8sec_gse
3 erg_mgf_l2_mag_8sec_gsm
4 erg_mgf_l2_mag_8sec_sm

Then copy & paste necessary vars andgive them to the tplot command

ERG> tnames_cp( /tplot )['erg_mgf_l2_mag_8sec_dsi','erg_mgf_l2_mag_8sec_gse','erg_mgf_l2_mag_8sec_gsm','erg_mgf_l2_mag_8sec_sm']

ERG> tplot_remove_panel, [1, 2];; Remove 1st and 2nd panels and replot.

Or use tplot_remove_panel010

How todo this?

2
3
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

3

26

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

ERG> options, 'erg_mgf_l2_mag_8sec_*', ytitle= 'Arase mag' , ysubtitle='[nT]'
ERG> options, 'erg_mgf_l2_mag_8sec_sm', labels=['Bx_sm', 'By_sm', 'Bz_sm' ]ERG> options, 'erg_mgf_l2_mag_8sec_sm', colors=[ 0, 1, 2 ]ERG> tplot, 'erg_mgf_l2_mag_8sec_sm'

ytitle,ysubtitle

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

labelscolors27

Change the time range of a plot
Select a time period by mouse-clicks on the plot window

ERG> tlimit
Specify a time period explicitly

ERG> tlimit, '2017-05-29/03:30' , '2017-05-29/08:30'
Back to the last plot period
ERG> tlimit, /last
Restore the original plot periodthat was set by timespan
ERG> tlimit, /fullMar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

28

Separate a tplot variable with vector data
ERG> split_vec, 'erg_mgf_l2_mag_8sec_sm'
STORE_DATA(260): Creating tplot variable: 19 erg_mgf_l2_mag_8sec_sm_x
STORE_DATA(260): Creating tplot variable: 20 erg_mgf_l2_mag_8sec_sm_y
STORE_DATA(260): Creating tplot variable: 21 erg_mgf_l2_mag_8sec_sm_z

ERG> tplot, 'erg_mgf_l2_mag_8sec_sm_?'

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

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

29Change the vertical range of a plot
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_sm_x', 150,350,

0ERG> tplot

Zoomed in a more limited
range in the vertical scale.

Tips:
Putting 0 for both ymin and ymax
sets the y range to auto-scale.
ERG> ylim, 'thg_mag_atha_x', 0, 0Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

30

Dump to png, postscript, and Ascii files
To a png file or postscript file.
ERG> cwd;Display the current directory/yyyy/xxxx/erg_mgf_plot.png

CWD(25): Directory changed to: /yyyy/xxxx
ERG> tplot, 'erg_mgf_l2_mag_8sec_sm_?'
ERG> makepng, 'erg_mgf_plot';à erg_mgf_plot.png

ERG> popen, 'erg_mgf_plot'
ERG> tplot;Redo the last plot

ERG> pclose; à erg_mgf_plot.ps

Dump the data content of a tplot variable to a Ascii file.
ERG> tplot_ascii, 'erg_mgf_l2_mag_8sec_gse';--> erg_mgf_l2_mag_8sec_gse.txt

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

31

SPEDAS manual viewed with a web browser
Open /YOUR_SPEDAS_DIR/idl/_spd_doc.html
with your web browser to view the
automatically generated documents for
SPEDAS routines.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

32

Basics of SPEDAS:
Various filtering routines for
tplot data

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

33

boxcar-average data– avg_data –avg_data, 'varname', timebin
varname: tplot variable names or index numbers
timebin : a time window in sec with which the boxcar-averaging is applied to the data
ERG> del_data, '*'ERG> timespan, '2017-05-29-03:30',70,/minRemove all tplot variables
and reload the data

ERG> erg_load_mgf & options, 'erg_mgf_l2_mag_8sec_sm', colors=[0, 1, 2]
ERG> split_vec, 'erg_mgf_l2_mag_8sec_sm'
ERG> avg_data, 'erg_mgf_l2_mag_8sec_sm_x' , 600.
ERG> tplot, ['erg_mgf_l2_mag_8sec_sm_x', 'erg_mgf_l2_mag_8sec_sm_x_avg' ]The data boxcar-averaged
with a time bin of 600
secondAs a result, the number of data
points is reduced to every 600 s.
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

34

Smoothing data – tsmooth_in_time –tsmooth_in_time, 'varname', timebin

varname : tplot variable name(s)timebin : time window in second for running average

ERG> tsmooth_in_time, 'erg_mgf_l2_mag_8sec_sm_x', 600.
ERG> tplot_names… … … …
19 erg_mgf_l2_mag_8sec_sm_x… … … …
23 erg_mgf_l2_mag_8sec_sm_x_smoothed
ERG> tplot, [ 19 , 23 ]The data is running-averaged witha time window of 600 second. We
can use this as a rough low-passfilter.
Note that the number of data
points is conserved.
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

35

High-pass filter in time – thigh_pass_filter –thigh_pass_filter, 'varname', timebin

varname : tplot variable name(s)timebin : time window in second for running average

ERG> thigh_pass_filter, 'erg_mgf_l2_mag_8sec_sm', 600.
ERG> tplot_names… … … …
4 erg_mgf_l2_mag_8sec_sm… … … …
24 erg_mgf_l2_mag_8sec_sm_hpfilt

ERG> tplot, [ 4 , 24 ]Time variations with periods shorter
than 600 sec are shown.
Actually this command justsubtracts the low-pass-filteredvalues derived withtsmooth_in_time from the original
data, not uses any digital filtering
process such as FFT.
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

36

Basics of SPEDAS:
Frequency analysis of tplot
dataMar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

37

Dynamics spectra – tdpwrspc–
tdpwrspc, 'varname'varname : tplot variable name(s)ERG> tdpwrspc, 'erg_mgf_l2_mag_8sec_sm_hpfilt'
ERG> tplot_names… … … …
25 erg_mgf_l2_mag_8sec_sm_hpfilt_x… … … …
28 erg_mgf_l2_mag_8sec_sm_hpfilt_x_dpwrspc
ERG> tplot, [ 25, 28 ]ERG> tlimit,'2017-05-29/03:00','2017-05-29/08:00'

FFT with the hanning window isapplied to derive dynamic frequency
spectra of the data.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

38

Wavelet analysis – wav_data –wav_data, 'varname'varname : tplot variable name(s)wav_data accepts data with less than 32768
samples. The number of data points is reduced
as done with avg_data in this case.

ERG> wav_data, 'erg_mgf_l2_mag_8sec_sm_hpfilt_x'
STORE_DATA(260): Creating tplot variable: 31 erg_mgf_l2_mag_8sec_sm_hpfilt_x_wv_pow
ERG> zlim, 31, 1, 2000, 1
ERG> tplot, ['erg_mgf_l2_mag_8sec_sm_hpfilt_x','erg_mgf_l2_mag_8sec_sm_hpfilt_x_wv_pow']

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.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

39

Other information sources for SPEDAS• SPEDAS wiki
• http://spedas.org/wiki/index.php?title=Main_Page•

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

• Change log of the source repository for the bleeding edge of SPEDAS• 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-J wiki (for Japanese SPEDAS user)• https://github.com/spedas-j/member_contrib/wiki

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

40

Other information sources for Arase• ERG-SC web page (incl. ERG plug-in and data download pages.)• https://ergsc.isee.nagoya-u.ac.jp• ERG-SC wiki
• https://ergsc.isee.nagoya-u.ac.jp/mw/index.php/Main_Page

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

41

Quick review of the usagesof the part_products library

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

42

What's "part_products"?
• A set of generic routines bundled to SPEDAS
to make tplot variables for various types ofspectrum plot.

part_products
library

3-D flux
data
Typically a 4-D array(time x energy x azim x elev)

Mar. 15, 2024

2-D
spectrumdata• time x energy• time x pitch angle• …
• …

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

43

Basic usage of part_products: Energy spectra of average flux
timespan, '2017-04-12'
erg_load_lepe, datatype='3dflux', uname=uname, pass=pass, /no_sort_enebin
erg_lep_part_products, 'erg_lepe_l2_3dflux_FEDU', output='energy'
loadct_sd, 48 ;; using the color table Turbo
tplot, 'erg_lepe_l2_3dflux_FEDU_energy'Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

44

Basic usage of part_products: Pitch angle spectra
timespan, '2017-04-12/04:00',4, /hour & get_timespan, tr
erg_load_mgf & set_erg_var_label
magvn = 'erg_mgf_l2_mag_8sec_dsi' & posvn = 'erg_orb_l2_pos_gse'
erg_load_mepi_nml, datatype='3dflux'
erg_mep_part_products, 'erg_mepi_l2_3dflux_FPDU', output='pa', $energy=[8000., 13000.], trange=tr, mag=magvn, pos=posvn, /no_ang_weighting
options, 'erg_lepe_l2_3dflux_FEDU_energy', 'color_table', 1079 ;; Different color tables are used for variables.
options, 'erg_mepi_l2_3dflux_FPDU_pa', 'color_table', 1080;; 1079: Plasma, 1080: Viridis
tplot, ['erg_lepe_l2_3dflux_FEDU_energy','erg_mepi_l2_3dflux_FPDU_pa']

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

45

Basic usage of part_products: Energy spectra for a limited PA range
erg_load_mepe, level='l2', datatype='3dflux'
erg_mep_part_products, 'erg_mepe_l2_3dflux_FEDU', output='energy', $trange=tr, mag=magvn, pos=posvn, pitch=[0, 7], /no_ang_weighting
options, 'erg_mepe_l2_3dflux_FEDU_energy', color_table=1072, reverse_color_table=1
tplot, ['erg_lepe_l2_3dflux_FEDU_energy','erg_mepi_l2_3dflux_FPDU_pa',$'erg_mepe_l2_3dflux_FEDU_energy']Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

46

Basic usage of part_products: Velocity moments
erg_mep_part_products, 'erg_mepi_l2_3dflux_FPDU', output='fac_moments', $trange=tr, mag=magvn, pos=posvn, /no_ang_weighting
options, 'erg_mepi_l2_3dflux_FPDU_ptens_mag', colors=[0,1,2,3,4,5] ;; Set line colors
vns = tnames( /tplot ) ;; Obtain a list of the previously plotted variables
tplot, [ vns, 'erg_mepi_l2_3dflux_FPDU_'+['ptens_mag', 'density_mag'] ]Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

47

Resources• A bit more (still brief!) tutorial for the part_products
library is available from the ERG-SC website at:https://ergsc.isee.nagoya-u.ac.jp/data_info/howto.shtml.en

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

48

Arase Orbit and ionosphericfootprint

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

49

Arase orbit datasets@ ERG-SC website

Level (model)
Level 2(IGRF)

Data type

Data-load routine

Definitive

erg_load_orb

Predicted (spre, mpre, lpre)

erg_load_orb_predict, datatype='spre or mpre
or lpre'OP77Q model

Level 3
T89 model using Kp(IGRF +
erg_load_orb_l3, model='op or t89 or ts04'
TS05 (TS04) model using
external
fields)Note: L* andadiabatic invariants are provided only in Level-3 orbit data.
IMF and Dst
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

50

Arase orbit data with tplot
timespan, '2017-03-27/00:00', 1, /day ;; Set to 2017-03-27 00:00-24:00 UT
erg_load_orb;; Download and load the orbit data

options, 'erg_orb_l2_pos_sm', colors=[0,1,2], labels=['X','Y','Z'] ;; colors and labels
tplot,'erg_orb_l2_pos_sm'

Mar. 15, 2024;; Plot the data

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

51

Arase orbit data with tplotxy
timespan, '2017-03-27/06:00', 8, /hour;; 2017-03-27 06:00–14:00 UT

tplotxy, 'erg_orb_l2_pos_sm', xrange=[-6, 6], yrange=[-6, 6]

Mar. 15, 2024;; Plot the data

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

52

Arase orbit data with tplotxy (cont'd)
tplotxy, 'erg_orb_l2_pos_sm', xrange=[-6, 6], yrange=[-6, 6], versus='xy';; on the SM X-Y plane

tplotxy, 'erg_orb_l2_pos_sm', xrange=[-6, 6], yrange=[-6, 6], versus='xz';; on the SM X-Z plane

tplotxy accepts many options to modify the plot:
tplotxy, tplot_variable_name $ ; (e.g., ‘position_sm’), versus='xy' ; choose axis (e.g., xy or xz), multi= 'n_col n_raw’ ; make multi plots (‘# of colum # of raw’), over = over ; overplot on the current window, add = add ; add plot
, additional plot options ; (e.g., title, xrange, color, linestyle, etc.)

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

53

Arase footprint with the map2d library
map2d_init & map2d_coord, 'geo'
map2d_set, /erase & overlay_map_coast

map2d_coord, 'aacgm'
map2d_time, 1000 ;; Set to draw the grid and world map at 10:00 UT on 2017-03-27
map2d_set, /erase & overlay_map_coast

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

54

Arase footprint with the map2d library (cont'd)
split_vec, 'erg_orb_l2_pos_iono_north' ;; Split the footprint position based on IGRF into GEO lat. and lon.
map2d_coord, 'geo'
map2d_set, /erase & overlay_map_coast
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_0', 'erg_orb_l2_pos_iono_north_1'

The footprint trajectoryof Arase is drawn on theworld map in
geographical coords.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

55

Arase footprint with the map2d library (cont'd)
map2d_coord, 'aacgm' ;; Switch the coordinate system to AACGM
timespan, '2017-03-27/08:00', 4, /hour ;; Set the time range to 08:00–12:00 UT on 2017-03-27
map2d_time, 1000 ;; Draw the map at 10:00 UT
map2d_set, /erase, /mlt, scale=60e+6
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_0', 'erg_orb_l2_pos_iono_north_1'

The footprint trajectoryof Arase is drawn on the
Mlat-MLT grid in AltitudeAdjusted Corrected
Geomagnetic (AACGM)
coords.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

56

Arase footprint with the map2d library (cont'd)
map2d_coord, 'aacgm' & map2d_time, 1000 ;; Draw the map at 10:00 UT
map2d_set, /erase, /mlt, scale=60e+6
overlay_map_coast
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_0', 'erg_orb_l2_pos_iono_north_1', plottime=!map2d.time

The footprint trajectoryof Arase is drawn on theworld map in AltitudeAdjusted Corrected
Geomagnetic (AACGM)
coords at 10:00 UT.

Why is the footprint
trajectory different fromthe prev. one?

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

57

Arase footprint with the map2d library (cont'd)erg_load_orb_l3, model='t89' & erg_load_orb_l3, model='ts04'
split_vec, 'erg_orb_l3_pos_iono_north_*'map2d_time, 1000 ;; Draw the map at 10:00 UT
map2d_set, /erase, /mlt, scale=20e+6, glatc=60., glonc=250.
overlay_map_coast
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_0', 'erg_orb_l2_pos_iono_north_1', $plottime=!map2d.time, trace_color=0
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_t89_0', 'erg_orb_l2_pos_iono_north_t89_1', $plottime=!map2d.time, trace_color=1
overlay_map_sc_ifoot, 'erg_orb_l2_pos_iono_north_TS04_0', 'erg_orb_l2_pos_iono_north_TS04_1', $plottime=!map2d.time, trace_color=2

MLAT=70

IGRF
T89

The footprint trajectories
of Arase mapped withdifferent B-field models.

TS05
MLAT=60
Mar. 15, 2024

(TS04,T04s)

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

58

Appendix

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

59

Appendix A-1:
List of velocity moments by part_products
del_data, '*'timespan, '2017-03-27/10:00', 1, /hour& get_timespan, tr

erg_load_mepe, datatype='3dflux', varformat='FEDU'
erg_load_mepi_nml, datatype='3dflux', varformat='FPDU'
erg_load_mgf & erg_load_orb
erg_mep_part_products, 'erg_mepi_l2_3dflux_FPDU', pos='erg_orb_l2_pos_gse', mag='erg_mgf_l2_mag_8sec_dsi',
output='moments', trange=tr
erg_mep_part_products, 'erg_mepe_l2_3dflux_FEDU', pos='erg_orb_l2_pos_gse', mag='erg_mgf_l2_mag_8sec_dsi',
output='moments', trange=tr
Primary parameters calculated with the part_products:}
density: number density}

avgtemp: scalar temperature (!)}

velocity: bulk velocity}

vthermal: thermal velocity}}

mtens: momentum flux density tensor
ptens: pressure tensor}

t3: temperature tensor (!)}

magt3: perpendicular/parallel temperature (!)}

flux: number flux}

eflux: energy flux

All vector and tensor quantities in DSI coordinates.
(!) Note that these are NOT a temperature defined
as a width of Maxwellian distribution.

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting@Kanazawa Univ.

60

Appendix A-2:
3-D data structure common to particle data that SPEDAS can handle
ERG> help, dists[0]** Structure <18a6808>, 21 tags, length=196736, data length=196725, refs=2:
PROJECT_NAMESTRING'ERG'SPACECRAFT

LONG

1

DATA_NAMESTRING'LEP-e Electron 3dflux'

UNITS_NAMESTRING'flux'UNITS_PROCEDURE STRING'erg_convert_flux_units'

SPECIESSTRING

'e'

VALID

BYTE

CHARGE

FLOAT-1.00000

MASS

FLOAT

5.68566e-06

TIME

DOUBLE

1.4920128e+09

END_TIMEDOUBLE

1.4920128e+09

DATA

FLOAT

Array[32, 16, 12]

BINS

FLOAT

Array[32, 16, 12]

ENERGYFLOATArray[32, 16, 12]

DENERGYFLOAT

Array[32, 16, 12]

NENERGY

LONG

32

NBINS

LONG

192

PHI

FLOAT

Array[32, 16, 12]

DPHI

FLOAT

Array[32, 16, 12]

THETA

FLOAT

Array[32, 16, 12]

DTHETAFLOAT

Array[32, 16, 12]

1

An example for LEP-e 3-D flux
data:
dist is an array of structures eachof which contains a set of data foreach spin.
"DATA" holds the flux data as a 3-D array of 32 ene.
ch x 16 spin sector x 12 sensors for this case.
ENERGY and DENERGY are the central energies andenergy ranges of the energy channels.

PHI, DPHI, THETA, and DTHETA have phi/theta
angles of particle-going directions and angularwidths measured by directional channels of aparticle instrument in the DSI coordinate system.

ERG>

Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting@Kanazawa Univ.

61

Appendix A-3:
Some other options available for erg_part_en_pa_spec_plot
erg_part_en_pa_spec_plot, dist $, time=time $; a time or time range for plotting, units=units $; physical unit 'flux','eflux','df_km','df_cm', with_contour=with_contour $; to overlay contour lines, zrange=zrange $; explicitly set the range for the color scale, npabin=npabin $; number of pitch angle bins (default: 19), rslt=rslt $; to obtain data arrays which have been plotted, noplot=noplot; set to suppress replotting

You can use this for other particledata.
For example:
timespan, '2017-04-12/16:00', 2, /hour
get_timespan, tr
erg_load_mepe, datatype='3dflux'
dists = erg_mepe_get_dist( $'erg_mepe_l2_3dflux_FEDU', trange=tr)
erg_part_en_pa_spec_plot, dists
Mar. 15, 2024

IDL/SPEDAS tutorial, ERG science meeting @Kanazawa Univ.

62