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

2. THEMIS Science Software TrainingSoftware − 2UCLA, July 25, 2007 Agenda 09:00Welcome and LogisticsD. King 09:15Probe and Science StatusV. Angelopoulos 09:30Web Site Review All Except Software and HelpV. Angelopoulos Software and HelpD. King 10:00Themis Data Analysis SoftwareK. Bromund 10:45Graphical User Interface (GUI)J. McTiernan 11:15V2.00 Software Status ReportV. Angelopoulos 11:25Summary and Action ItemsD. King ------- Break for Lunch --------- 1:00 Software / IDL Setup Team Software / IDL Command Line Demo K. Bromund Software / IDL GUI DemoJ. McTiernan 3:45 Wrap-upD. King

3. THEMIS Science Software TrainingSoftware − 3UCLA, July 25, 2007 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. THEMIS Science Software TrainingSoftware − 4UCLA, July 25, 2007 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

5. THEMIS Science Software TrainingSoftware − 5UCLA, July 25, 2007 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 Overview

6. THEMIS Science Software TrainingSoftware − 6UCLA, July 25, 2007 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

7. THEMIS Science Software TrainingSoftware − 7UCLA, July 25, 2007 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.

8. THEMIS Science Software TrainingSoftware − 8UCLA, July 25, 2007 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.

9. THEMIS Science Software TrainingSoftware − 9UCLA, July 25, 2007 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/

10. THEMIS Science Software TrainingSoftware − 10UCLA, July 25, 2007 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

11. THEMIS Science Software TrainingSoftware − 11UCLA, July 25, 2007 Data / Directory structure Data Directory structure is large! (scores of files per day) 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

12. THEMIS Science Software TrainingSoftware − 12UCLA, July 25, 2007 Primary Routines Load Routine Summary Notes: (*) calibration routine available but still under development - data reduction and analysis routines available: see crib sheet

13. THEMIS Science Software TrainingSoftware − 13UCLA, July 25, 2007 Primary Routines Usage Conventions: Use keywords to determine functionality 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', type='calibrated'

14. THEMIS Science Software TrainingSoftware − 14UCLA, July 25, 2007 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.

15. THEMIS Science Software TrainingSoftware − 15UCLA, July 25, 2007 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 –SPGSpinning Probe Geometric –SSLSpinning SunSensor L-vectorZ –DSLDespun SunSensor L-vectorZ –GEIGeocentric Equatorial Inertal –GSEGeocentric Solar Ecliptic –GSMGeocentric Solar Example –thm_load_state, /get_support_data –thm_cotrans, 'th?_fg?', out_coord='gsm'

16. THEMIS Science Software TrainingSoftware − 16UCLA, July 25, 2007 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

17. THEMIS Science Software TrainingSoftware − 17UCLA, July 25, 2007 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 f – full, r – reduced, m – moments (slow survey), b – burst FGM data. Example: tha_fgl l – low telemetry rate, h – high telemetry rate, e – engineering decimated high rate, s – slow survey spin fit. Electric Fields and SCM. Example: tha_efs ef - efi, sc – scm, fb – fbk, ff – fft s – slow survey spin fit, f – 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*

18. THEMIS Science Software TrainingSoftware − 18UCLA, July 25, 2007 Crib Sheets thm_crib_asi thm_crib_efi thm_crib_esa_da thm_crib_esa_moments thm_crib_export thm_crib_fbk thm_crib_fft 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 for Loading, Processing and Plotting.run thm_crib_asi or cut and paste or copy and modify for your own use

19. THEMIS Science Software TrainingSoftware − 19UCLA, July 25, 2007 Command Line Example 1 –To load data: »timespan,'6-10-2',2,/days »thm_load_gmag,site=’ccnv’ –To plot data: »tplot,’thg_mag_ccnv’

20. THEMIS Science Software TrainingSoftware − 20UCLA, July 25, 2007 Command Line Example 2 –Wavelet transform on an interval of interest –Define and display the interval »Tr = ['2006-10-2/16:00','2006-10-3/05'] »timebar,tr –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

21. THEMIS Science Software TrainingSoftware − 21UCLA, July 25, 2007 Command Line Example 3 thm_crib_esa_da data analysis of ESA electron spectra and distributions:

22. THEMIS Science Software TrainingSoftware − 22UCLA, July 25, 2007 Graphical User Interface The GUI is an IDL command you can run from the IDL command line: IDL> thm_gui Can select data for loading, calibration, processing, and plotting. Can save the history of processing. Data loaded with GUI can be manipulated from command line, and vice versa

23. THEMIS Science Software TrainingSoftware − 23UCLA, July 25, 2007 The THEMIS Graphical User Interface J. McTiernan 23-Jul-2007 http://ssl.berkeley.edu/~jimm/themis/http://ssl.berkeley.edu/~jimm/themis/thm_gui.ppt

24. THEMIS Science Software TrainingSoftware − 24UCLA, July 25, 2007 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 http://ssl.berkeley.edu/~jimm/themis/

25. THEMIS Science Software TrainingSoftware − 25UCLA, July 25, 2007 Main Widget:

26. THEMIS Science Software TrainingSoftware − 26UCLA, July 25, 2007 Choose Data to Load: Click here for FGM data

27. THEMIS Science Software TrainingSoftware − 27UCLA, July 25, 2007 Data choice window: Nothing will happen until you click here

28. THEMIS Science Software TrainingSoftware − 28UCLA, July 25, 2007 Choices show up in History Window: Click here to clear choices.

29. THEMIS Science Software TrainingSoftware − 29UCLA, July 25, 2007 Load Data: Click here to load.

30. THEMIS Science Software TrainingSoftware − 30UCLA, July 25, 2007 Oops, Nothing happens unless you choose a time range Click Here to choose times.

31. THEMIS Science Software TrainingSoftware − 31UCLA, July 25, 2007 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

32. THEMIS Science Software TrainingSoftware − 32UCLA, July 25, 2007 Time selection widget:

33. THEMIS Science Software TrainingSoftware − 33UCLA, July 25, 2007 Selection shows up in the History: Now you can load data.

34. THEMIS Science Software TrainingSoftware − 34UCLA, July 25, 2007 After loading, All data is “active”. State data has been loaded automatically for FGM.

35. THEMIS Science Software TrainingSoftware − 35UCLA, July 25, 2007 Setting Active Data: Type a string, or click to set data to “active”

36. THEMIS Science Software TrainingSoftware − 36UCLA, July 25, 2007 What next? Coordinate transform Data Processing Data Processing Plotting.

37. THEMIS Science Software TrainingSoftware − 37UCLA, July 25, 2007 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.

38. THEMIS Science Software TrainingSoftware − 38UCLA, July 25, 2007 Clicked on GEI, and Transform Button:

39. THEMIS Science Software TrainingSoftware − 39UCLA, July 25, 2007 Back on the main widget: New “active” data. Remember – only active data is processed.

40. THEMIS Science Software TrainingSoftware − 40UCLA, July 25, 2007 Plot Widget: If there is active data, plot pops up first.

41. THEMIS Science Software TrainingSoftware − 41UCLA, July 25, 2007 Plot Widget: Setting “PNG” Click here File shows up in working dir. Remember to click on SCREEN to return to screen plots

42. THEMIS Science Software TrainingSoftware − 42UCLA, July 25, 2007 Check History: These are the IDL commands used.

43. THEMIS Science Software TrainingSoftware − 43UCLA, July 25, 2007 Data Processing (dproc) widget:

44. THEMIS Science Software TrainingSoftware − 44UCLA, July 25, 2007 Data Processing (dproc) widget: Deletes Active Data.

45. THEMIS Science Software TrainingSoftware − 45UCLA, July 25, 2007 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.

46. THEMIS Science Software TrainingSoftware − 46UCLA, July 25, 2007 Note new “active” data: These processes reset the “active” data.

47. THEMIS Science Software TrainingSoftware − 47UCLA, July 25, 2007 Other Stuff: Click here for an overview plot:

48. THEMIS Science Software TrainingSoftware − 48UCLA, July 25, 2007 Sample Overview Plot:

49. THEMIS Science Software TrainingSoftware − 49UCLA, July 25, 2007 Other Stuff: Click here to save history. Here to clear history

50. THEMIS Science Software TrainingSoftware − 50UCLA, July 25, 2007 HELP Widget: This has descriptions of all of the buttons and windows in the widgets.

51. THEMIS Science Software TrainingSoftware − 51UCLA, July 25, 2007 Error Widget: This should pop up automatically if there is a crash. Also you can get this by clicking the ERROR button on the main widget. You can edit this form, and please save this and email it to: THEMIS_Science_Support@ss l.berkeley.edu THEMIS_Science_Support@ss l.berkeley.edu THEMIS_Science_Support@ss l.berkeley.edu Also email a saved history file and any other pertinent information that can be cut and pasted from the IDL window.

52. THEMIS Science Software TrainingSoftware − 52UCLA, July 25, 2007 Configuration Widget: Allows configuration to be changed, saved. Saves in a file. Input into every session Resets to initial state. Resets to default state in distribution, deletes any saved files. Messages: You need to be able to write to this directory if you download data.

53. THEMIS Science Software TrainingSoftware − 53UCLA, July 25, 2007 Exit Button: Click here to exit GUI. Popups are dismissed, except for Help, Error or Config. Loaded data is not deleted – will show up in Loaded Data window on restart (but not in Active Data).

54. THEMIS Science Software TrainingSoftware − 54UCLA, July 25, 2007 THM_GUI Tips: Remember to save and email your history file if you have a bug. Also feel free to include any other output messages that show up in the IDL command line. Always choose a time range before loading data. Don't load more than a couple of days at a time, or a couple of hours if you are loading full resolution all-sky imager (asf) data. The choice of "probe" in the data loading widgets is global, that is, all of the selected data will be loaded for the probe(s) chosen most recently. If, for example, you want to load EFI data from probe "A" and FGM data from probe "B", you will need to load these separately. When choosing multiple probes, data types, or whatever, hold the "control" key, and click more than one. Also, you can click on an option, then hold "shift" and the left mouse button, and drag the cursor over the others. The data names are kind of cryptic, there is a table in the User's Guide and also at the end of the text in the help widget for guidance.

55. THEMIS Science Software TrainingSoftware − 55UCLA, July 25, 2007 THM_GUI Tips: Once you've chosen data, hit the "Clear Load Queue" to clear it out if you don't want to load it. If a load fails (for a reason other than "the data isn't there"), then the data are still waiting to be loaded. Clear the load queue. Remember that all loaded data are set to "active" immediately upon loading. If you don't want all of that data to be active, then click on what you want in the Loaded Data window. If you want to delete all data, type "*" window below the Loaded Data window, click "Set Active Data to String", call up the Data Processing widget, and click "Delete". For coordinate transforms, data that have "Unknown" for a coordinate system will not be transformed. Multiple data sets with different input coordinates *can* be transformed. Data Processing and Plotting tasks are only possible when there is "active" data.

56. THEMIS Science Software TrainingSoftware − 56UCLA, July 25, 2007 THM_GUI Tips: When typing in strings for numerical input -- be careful. Strings that aren't numbers are interpreted as 0 by IDL, but strings that aren't numbers, but start with a number are set to the number, e.g., 'a14' is set to 0, but '1a4' is set to 1. When in doubt, look in the History. Sometimes data is inappropriate for a given operation (especially wavelet transforms, and power spectra). We have tried to catch as many of these situations as we can, but there probably will be more as more types of data are imported. If something looks weird, save your history, and email us. Some processes can take a while (e.g., calibrating SCM data, wavelet transforms of whole days). Currently there is no good way to stop a process except for the standard IDL "control-C" on the IDL window. This doesn't always work... For some time ranges, the "dpwrspec" button crashes in the IDL POLY_FIT routine. We have no clue why this happens. Try changing the input time range.

57. THEMIS Science Software TrainingSoftware − 57UCLA, July 25, 2007 THM_GUI Tips: The Plot Data button first issues a "tplot" call when the widget pops up. If you create a "PNG" plot, remember to reset to "SCREEN" for screen plotting. Don't try to plot more than about 10 quantities at a time, if there is spectrogram data, there will be a crash. There will undoubtedly be more of these…