Science Software – v2.00 Training UCB, UCLA and Colorado July 23 – July 27, 2007

1. Science Software – v2.00 Training UCB, UCLA and Colorado July 23 – July 27, 2007

2. Agenda • Agenda • 09:00 Welcome and Logistics D. King • 09:15 Probe and Science Status V. Angelopoulos • 09:30 Web Site Review • All Except Software and Help V. Angelopoulos • Software and Help D. King • 10:00 V2.00 Software Status Report V. Angelopoulos • 10:15 Themis Data Analysis Software K. Bromund • 11:00 Graphical User Interface (GUI) J. McTiernan • 11:45 Summary and Action Items D. King • ------- Break for Lunch --------- • 1:00 Software / IDL Setup Team • Software / IDL GUI Demo J. McTiernan • Software / IDL Command Line Demo K. Bromund • 3:45 Wrap-up D. King

3. Welcome • Welcome and Logistics • Morning and Afternoon Sessions • THEMIS Beta and Official Web Sites • Initial Release – v2.00 • Scientists Enhancing Software • Action Items and Summary • Your Feedback and Suggestions

4. Status Report • V2.00 Science Software Status Report • General • Loads, introduces and calibrates all L1 quantities, all instruments • Loads calibrated L2 quantities • FGM • L1, L2 data available since early March 2007 • Spin ripples (power system) and 11Hz noise (ETC board) cleanup in progresS • SCM • L1 data available since early March 2007 • Spin ripples (power system) and 8/32Hz noise cleanup available • L2 frequency spectrograms only (FBK) available now; timeseries in next release • EFI • All L1 data available from TH-C since May 2007, TH-D,E since Jun 7 • Bias currents correct on all since last Thursday, July 19 • Spin ripples (power system) and 8/32Hz noise cleanup available • L2 frequency spectrograms only (FBK) available now; timeseries in next release • ESA • No L1 data, only L0 data – however, transparent to the user • All data available since ESA turn-on, mid-March • L2 omnidirectional energy spectrograms; ground moments available now, • L2 on-board moments available in the next release • SST • L1 data available since SST turn-on, mid-March • L2 omnidirectional energy spectrograms available now, • L2 on-board moments available in the next release

5. THEMIS Data Analysis Software • K Bromund • SP Systems Inc./NASA/GSFC • M Davis, D Larson, H Frey, J Bonnell, J McTiernan, J Lewis, D King, V Angelopoulos – UC Berkeley • K Ramer, P Cruce, H Schwarzl – UCLA • E Georgescu – MPE • P Robert, O LeContel– CETP • B Jackel, E Donovan – Calgary

6. Overview Overview • Software Objectives • Powerful, Flexible Command Line Interface • GUI to provide Easy Access to Key Features • Software Installation • Data Distribution • Key Routines, crib sheets. • Examples

7. Software Objectives • Code is available to everyone, but not required to analyze data. • IDL based (library of routines –but no main program!). • Command driven. • Separates the tasks of: • Reading files. • Manipulating data • Plotting • Platform independent. Works on: • Solaris • Linux • Windows • MacOSx

8. Software Design • Implements automatic file retrieval • Given time interval and data type as input • Relies on well defined directory structure. • Automatic WEB download to local directory cache. • All data is easily “loaded”, “manipulated” and “plotted”. • Level 2 Data Loaded by default • Option to Load Level 1 data • Can be loaded directly in 'raw' or 'calibrated' format. • Calibration routines can be called separately from Load routines. • Able to compare calibrated with raw data. • Goal: keywords to load routines control processing parameters. • Software maintains variables (data quantities) and associated metadata. • Command line interface commands are building blocks usable for batch mode processing and/or GUIs.

9. System Requirements • IDL Patch Recommended • http://cdf.gsfc.nasa.gov/html/cdf_patch_for_idl6x_new.html • Required for IDL 6.2 and below • Required for Intel Mac, regardless of IDL version • For Mac, system configurations are required to run IDL • X11 – may need to be installed. • mouse click-through • one-time X11 configuration necessary for proper operation: defaults write com.apple.x11 wm_click_through -bool true • see User's Guide for full instructions.

10. Configuring the Software • Set up the IDL path • Windows and IDLDE on any platform: File->Preferences Path Tab Press Insert Browse to find your installation and then select the ‘idl’ directory Check the box preceding the path to 'search subdirectories' • UNIX-like systems (Mac OS X, Linux, Solaris) setenv IDL_BASE_DIR /path/to/tdas_2_00da0/idl source $IDL_BASE_DIR/themis/setup_themis • Download the User's Guide For More Information:ftp://apollo.ssl.berkeley.edu/pub/THEMIS/3 Ground Systems/3.2 Science Operations/Science Operations Documents/Software Users Guides/

11. Data Definitions • The software operates on Level 1 and Level 2 data. • Data Level Definitions: • Level 0 Data – • Raw files (*.pkt) one per APID. • Only used for loading ESA data. • Level 1 Data - • CDF (Common Data Files) files (*.cdf) • Contain raw, uncalibrated data. i.e. counts, DAC units. • Used primarily by instrument scientists. • Typically requires software to interpret. • Level 2 Data • CDF files – contain physical quantities • Available for most instruments/data quantities

12. Data / Directory structure • Data Directory structure is large! • Scores of files per day • ~3GB/day for all probes (L1 data) • Directory hierarchy keeps directory sizes manageable • Software performs automatic file retrieval. • Software maintains directory hierarchy. • Behavior of Automatic File Retrieval is configurable • Can be set to ‘No Download’ or ‘No Update’ mode • Root directory of local copy of hierarchy determined automatically, but configurable. • GUI and Command Line share same local file cache and configurations. • thm_ui_config IDL widget • 'Config' button in the thm_gui IDL widget. • Environment variables

13. Primary Routines • Load Routine Summary Notes: (*) calibration routine available but still under development - data reduction and analysis routines available: see crib sheet

14. Primary Routines • Usage Conventions: Use keywords to determine functionality data level calibration coordinate transformation datatype and probe keywords determine what data is loaded and/or created through calibration process /get_support_data keyword to load support data required by thm_cal* and thm_cotrans routines. Example thm_load_state, probe = 'a', /get_support_data thm_load_fgm, probe='a', coord='gsm', datatype='fgl', level=1, type='calibrated'

15. Primary Routines • Calibration Routines • thm_cal_efi • thm_cal_fbk • thm_cal_fit • thm_cal_fgm • thm_cal_scm • thm_cal_mom • Calibration can be called separately from thm_load routine when raw data is loaded • for other instruments, see examples in crib sheet.

16. Primary Routines • Coordinate Transformations • thm_cotrans • transforms to/from any of the following coordinate systems in a single call • updates metadata in output. • knows coordinate system of input from metadata • Currently Supported Coordinate Systems • SPG Spinning Probe Geometric • SSL Spinning SunSensor L-vectorZ • DSL Despun SunSensor L-vectorZ • GEI Geocentric Equatorial Inertal • GSE Geocentric Solar Ecliptic • GSM Geocentric Solar • Example • thm_load_state, /get_support_data • thm_cotrans, 'th?_fg?', out_coord='gsm'

17. SPG coordinates: X normal to solar panel 1 Z along probe geometric axis (out of page) Other coordinate systems: x z SSL (Spinning, Sun Sensor, L-vector) DSL(Despun, Sun direction, L-vector)

18. Sun Sensor ESA SST

19. Primary Routines • Plotting • tplot • tplot_names • tlimit • tlimit, /full • tlimit, /last • ctime, t • get_data • store_data • tr = timerange(/current) • etc. Data Processing • tdegap • tdeflag • wav_data • dpwrspec • etc. Exporting • tplot_ascii • makepng • makegif • tplot_save • tplot_restore

20. Variable Names • Probe specification. Example: tha • a – can be one of [a-e] specifies probe • Particle data. Example: tha_peif • p – particles • e – ESA, s – SST • i – ions, e – electrons • f – full, r – reduced, m – moments, b – burst • FGM data. Example: tha_fgl • l – low telemetry rate, h – high telemetry rate, e – engineering decimated high rate, s – spin fit. • Electric Fields and SCM. Example: tha_efs • ef - efi, sc – scm, fb – fbk, ff – fft • s – spin fit, f – full orbit or fast survey, p – particle burst, w – waves burst. • Wildcards accepted in names when plotting and data processing: • th?_fg? • th[ab]_fg[lh] • th?_state*

21. thm_crib_fgm thm_crib_fit thm_crib_gmag thm_crib_mom thm_crib_scm thm_crib_sst thm_crib_state thm_crib_tplot thm_map_examples Crib Sheets Crib Sheets for Loading, Processing and Plotting • thm_crib_asi • thm_crib_dproc • thm_crib_efi • thm_crib_esa_da • thm_crib_esa_moments • thm_crib_export • thm_crib_fbk • thm_crib_fft .run thm_crib_asi or cut and paste or copy and modify for your own use

22. Command Line Example 1 • To load data: • timespan,'6-10-2',2,/days • thm_load_gmag,site='ccnv',$/subtract_average • To plot data: • options,'thg_mag_ccnv',$labels=['Bx','By','Bz'] • tplot_options, 'title', $'GMAG Examples' • tplot,’thg_mag_ccnv’

23. Command Line Example 2 • Split the 3-vector into components: • split_vec,'thg_mag_ccnv' • Compute transform of one component • wav_data,'thg_mag_ccnv_x',/kol $ ,trange=tr ,maxpoints=24l*3600*2 • Set color limits (log scale) • zlim,'*pow', .0001,.01,1 • Plot it. • tplot,'*ccnv_x*',trange=tr • Wavelet transform on an interval of interest • Define and display the interval • Tr = ['2006-10-2/16:00','2006-10-3/05'] • timebar,tr

24. Command Line Example 3 • thm_crib_esa_da • data analysis • of ESA electron • spectra and • distributions:

25. Graphical User Interface

26. The THEMIS Graphical User Interface J. McTiernan 23-Jul-2007 http://ssl.berkeley.edu/~jimm/themis/thm_gui.ppt

27. IDL> thm_gui • Called from IDL command line. • Gives the ability to load and plot data, and also some data processing tasks. • Calls various TPLOT routines • IDL functions are available from command line when widget is up. • Find this document: http://ssl.berkeley.edu/~jimm/themis/thm_gui.ppt

28. Main Widget:

29. Choose Data to Load: Click here for FGM data

30. Data choice window: Nothing will happen until you click here

31. Choices show up in History Window: Click here to clear choices.

32. Load Data: Click here to load.

33. Oops, Nothing happens unless you choose a time range Click Here to choose times.

34. Time Range Window: You can type here. Initially times are set to 1970-01-01/00:00:00 Times show up in history as you type. Click here for a time selection widget

35. Time selection widget:

36. Selection shows up in the History: Now you can load data.

37. After loading, All data is “active”. State data has been loaded automatically for FGM.

38. Setting Active Data: Type a string, or click to set data to “active”

39. What next? Plotting. Data Processing Coordinate transform

40. Coordinate Transform: Click one of these to choose output coordinates. Shows current transform Click here to do the deed. Message window: this will show warnings, errors, and progress.

41. Clicked on GEI, and Transform Button:

42. Back on the main widget: New “active” data. Remember – only active data is processed.

43. Plot Widget: If there is active data, plot pops up first.

44. Plot Widget: Setting “PNG” Click here Click here File shows up in working dir. Remember to click on SCREEN to return to screen plots

45. Check History: These are the IDL commands used.

46. Data Processing (dproc) widget:

47. Data Processing (dproc) widget: Deletes Active Data.

48. After dpwrspec button: (and time limits button) *For some time ranges, this crashes in the IDL POLY_FIT routine, due to a singular matrix detected.

49. Note new “active” data: These processes reset the “active” data.

50. Other Stuff: Click here for an overview plot: