File Menu - SPEDAS GUI

SPEDAS File Menu

The File menu contains selections that are related to loading, saving, and managing data, as well as printing and exporting image files. The figure on the right shows the options in the File pull down menu.

Open SPEDAS Document

The SPEDAS GUI includes the capability to save the state of a GUI session to a "SPEDAS GUI Document" file (.tgd file extension). TGD files are plain ASCII text, use XML to represent properties of GUI objects and loaded data, and can be examined with any ASCII file editor. Many web browsers also include support for viewing XML documents (although one may need to change the file extension to XML to get the browser to recognize the format).

Any loaded data associated with a GUI session is NOT directly stored in the TGD file; instead, the document contains the information necessary to reconstruct the sequence of calls that were initially used to load the data. There are some pros and cons to this approach that users should be aware of:

1. TGD files are relatively small, and can be easily shared as email attachments. Because they are plain ASCII text, there are no significant file format differences between different platforms, so TGD files are portable between systems.
2. Opening a TGD file may require internet connections to data servers in order to download any data files that are not already cached in the user's local file system.
3. Since the TGD file only records operations performed within the GUI, operations performed outside the GUI or data that is imported via manage data or tplot_gui will not be recorded in the SPEDAS Document.
4. Opening a TGD file is a DESTRUCTIVE operation that wipes out the current window configuration and loaded data, replacing it with the contents of the TGD file. We recommend that users save their work before opening a new TGD file, and pay attention to any warning dialogs to avoid nasty surprises.
5. No versioning information is stored in the XML file, TGD files created under a particular version may not be readable in other versions. Although, since the GUI interfaces are more stable than they were originally, this is less of a problem in recent releases.

To open a TGD file, select "Open SPEDAS Document..." from the File pull-down menu. Navigate to the file you wish to open, and click "Open" (or perhaps "OK", depending on your platform).

This should trigger the process of loading the data specified in the TGD file you just opened; you should see progress messages scrolling by in the IDL command window. It may take several minutes to load all the data, depending on how complex a document is being loaded; SPEDAS may also need to open an internet connection to the data servers to download any data files not already cached on your local file system.

If all goes well, when the data is finished loading, the main draw window should update and show the plots for the first GUI page specified in the TGD file. Other pages saved in the TGD file should be accessible through the "Pages" drop-down menu button. Any errors detected while parsing the XML file or loading the data will be reported by a pop-up error dialog, or a message in the status area at the bottom of the main GUI window.

Save SPEDAS Document

Warning: Due to an IDL bug on Windows platforms, the condition "write permission denied" is not properly detected, and will probably crash your entire IDL session if you attempt to save to a file without write permission.

We recommend a workflow something like this:

• Use the "Load SPEDAS Data" dialog to load the all the data you want to work with
• Use the "Graph" -> "Plot/Layout Options" dialog to create some plots
• Use "Save SPEDAS Document" to save a TGD document containing the window configuration, plot properties, and loaded data call sequence information, creating a "checkpoint" that can easily be restored later
• Perform any other manipulations (e.g. non-GUI operations), and be prepared to repeat them after opening the TGD file at some later time to restore the check pointed GUI configuration.

When you're ready to save your plots and loaded data, click "Save SPEDAS Document" under the File pull-down menu. All pages, plot settings, data, and data operations will be saved. If this session has not yet been saved to a TGD file, a platform-specific file-saving dialog will appear. Navigate to the directory where you'd like to save the file, select a new filename if you don't like the default, and click "Save" (or maybe "OK", depending on your platform).

If "Save SPEDAS Document" has already been invoked, or if the current session is the result of loading a TGD file, the file picker dialog will not appear, and the filename from the most recent save or open operation will be used again.

If the save attempt fails, an error message should be displayed, either in a pop-up warning dialog, or a message in the status area at the bottom of the main GUI window. If the save succeeds, a success message will appear in the status area.

Hint: The SPEDAS document can also be used to save default plot settings. Once you have created the font, size, colors, grids, axes, etc. that you prefer, the save document option will preserve those values. Each subsequent time you start a GUI session, you simply need to open the saved document to restore your preferences.

Save SPEDAS Document As

The File->Save SPEDAS Document As... dialog also saves a TGD file. The only difference between "Save SPEDAS Document" and "Save SPEDAS Document As..." is that "Save SPEDAS Document As…" always pops up a file picker dialog, allowing one to change the filename associated with the GUI session. "Save SPEDAS Document" will reuse the last filename successfully saved to, only displaying a file picker the first time the GUI state is saved.

Template

SPEDAS templates allow the user to save settings such as font size, colors, line options, etc. SPEDAS templates are saved with the default file extension TGT.

Open Template

File->Template->Open Template allows you to open a previously saved SPEDAS template (see the sections that follow for how to create a saved SPEDAS template). Choosing Open Template will bring up a standard file picker dialog. The exact appearance and functionality will depend on your platform. Once a template has been loaded the settings saved in the template will be applied to any new work in the GUI. For example, saved settings such as the page title and background color will be applied if you create a new page, saved settings including panel options such as grid lines will be applied to any new panels, and so on.

Note: to set a default template that will be opened whenever the GUI is run, see the Configuration Settings section.

Save Template

SPEDAS templates allow you to save page, panel, line, axis, and variable settings. For example, to save page settings first use the Page Options to format the page title, footer and layout. Then, in the Page Options window, select “Save as Default”, then “OK”. From the File menu select Template->Save Template. This will bring up a file dialog. Navigate to the directory where you wish to save the template, and change the file name if you wish and select Save.

The process for saving panel, line, axis, and variable settings is the same as for the page settings. First open the relevant options window, choose your settings, and select “Save as Default”. Then choose File->Template->Save Template to save the template. Note that page, panel, line, axis, and variable settings can all be saved within a single template file. For example, to save both page and panel settings, apply and “Save as Default” both the page and panel settings before choosing File->Template->Save Template.

Selecting Save as Default in the Panel Options window will save only the currently selected panel’s settings. Similarly Save as Default in the Line Options window saves the settings from the currently selected trace.

If “Save Template” has already been invoked in the GUI session, or a template has been loaded, the file picker dialog will not appear and you will instead be prompted as to whether you wish to overwrite the existing template file. If you have, for example, loaded a template containing page settings and now wish to save panel settings, choosing “Save Template” and selecting “Yes” to overwrite the existing template will create a template with the new panel settings that also retains the page settings.

Save Template As

“Save Template As” also saves a SPEDAS template TGT file. Unlike “Save Template”, “Save Template As” will always bring up a file picker dialog allowing you to change the filename of the SPEDAS template you are saving.

Reset Template

File->Template->Reset Template allows you to reset to the SPEDAS default template. For example, selecting Template->Reset Page Template will reset the page settings (e.g. title, background color) to the SPEDAS defaults for any new pages you create, while retaining any panel, line, axis, and variable settings saved in the template.

Load Data

The SPEDAS GUI can be used to load data from a number of missions, including THEMIS, GOES, FAST, WIND, ACE, IUGONET and OMNI. The GUI can also be used to load data from SPDF CDAWeb. To learn more on loading data in the SPEDAS GUI, see Loading Data in SPEDAS and Loading CDAWeb Data in SPEDAS.

Save Data As

The "Save Data As…" dialog allows the user to select a set of variables, and save the data as ASCII (with various formatting options) or as a set of files in the UCLA binary "upper flat file" format. Unlike "Save SPEDAS Document" or "Save As…", "Save Data As…" does not attempt to save any GUI objects or plotting parameters.

Click "File->Save Data As…" to bring up the dialog. On Windows XP, it will look something like this, assuming some data has already been loaded: image of save data as

The left hand "Loaded Data" pane is a "tree widget" representing the data variables currently available. In the above screen shot, many of the nodes are fully expanded. Click any box showing "+" to expand that node, or click a box showing "-" to collapse that node.

To the right of the "Loaded Data" pane are some additional controls. If the "Restrict Time Range" box is checked, only the data with timestamps in the given time range will be saved. For now, the start and end times must be typed into the text box in YYYY-MM-DD/HH:MM:SS format.

If the "Save as Flat file" box is checked, the data will be saved in (binary) UCLA flat file format. For further information about this format, please consult the UCLA documentation.

If the "Save as ASCII data file" box is checked, the data will be saved as ASCII, one line per record. If this format is selected, there are additional choices for how the ASCII data is formatted. The "Time Format" drop-down menu brings up a list of different formats for representing timestamps with varying degrees of precision. The "Floating Point Format" drop-down menu specifies the precision and format of floating point quantities that are not internally marked as timestamps.

The "Header Style" drop-down menu offers a few options for including header lines in the ASCII output. If "None" is selected, no header will be produced; for "Field Names Only", a single header line will be included, listing the field names associated with each data column; for "Tecplot", a Tecplot-compatible header will be produced with one line of field names, and another line with a sample count and some other information.

The "Item Separator" drop-down menu allows the user to select whether columns are to be separated by commas, tabs, or spaces. This option also applies to the header, if one is requested.

As an example, if "Header Style" is set to "Field Names Only" and "Item Separator" is set to "Comma", the resulting ASCII file should be readable by Excel or other utilities that understand CSV ("comma separated value") formatted files.

The "Indicate flags with:" text box allows the user to choose what gets printed if an IEEE-754 "NaN", "Inf", or other non-numeric floating point value is encountered during the conversion to ASCII. We suggest keeping the default text "NaN". (The term "flag" is used because in some situations, TDAS inserts NaN values to "flag" missing or invalid data samples.)

"Update document with location of data" is not yet implemented in this release (and perhaps never will be), and should be disregarded for now.

The suggested workflow for this dialog is to first use the tree widget in the "Loaded Data" pane to select some subset of the currently loaded variables, then use the controls on the right hand side to select a file format, an optional time range, and any additional style settings (if ASCII format is selected). Clicking the "Save" button will perform a few checks on the selected data variables, and if the selection is valid, the GUI will pop up a file picker dialog to specify the filename and directory to save.

Caveats:

This dialog does not permit saving arbitrary collections of variables. Owing to the record-oriented structure of these file formats, all selected variables must contain the same number of samples. For UCLA upper flat file format, the only valid data types are 4-byte integers, and 4- and 8-byte floating-point values. THEMIS data represented as bytes or 16-bit integers (for example, ASK) cannot be saved as UCLA upper flat files. These restrictions are enforced at the very end of the workflow, when the user clicks "Save". The first variable name with an incompatible sample count or data type will be mentioned in the error message; try removing that variable from the selection, and repeat the process until a valid ensemble of variables remains.

ASCII files generated from large data sets (e.g. several hours of ASK keogram data) are potentially enormous, and may appear to lock up IDL for a long time while the file is being written. Even modest ASCII data sets may require several minutes to be saved. These operations are somewhat inefficient; due to the need for column-by-column checking, formatting, and output of data fields.

Manage Data and Import/Export Tplot

SPEDAS verify data

The Manage Data Window allows you to import TPLOT variables into the GUI, export TPLOT variables from the GUI, delete GUI variables, and view/edit the meta-data associated with various GUI variables.

To import TPLOT variables you can select one or many (ctrl/shift-click) tplot variables in the left TPLOT Data area, then press the right arrow button to move data into the GUI. The data will then be moved into the GUI and attempt to detect the variable meta-data that includes name, mission, observatory, instrument, units, and coordinate system.

When the right arrow is clicked to import tplot data, the Verify Data Window will be displayed allowing you to verify that this data was correctly detected. Click the OK button if it is or 'Cancel' if you change your mind about importing. After you press 'OK' on the Verify Data panel, the data will be loaded. The figure to the right shows the Verify Data window.

To export GUI variables to TPLOT, select the GUI quantities that you would like to export from the tree at the right and select the left arrow button to export them.

To delete GUI variables, select the GUI quantities that you would like to delete from the tree at the right, then select the trash can button to delete them.

To examine the meta-data (name, mission, observatory, instrument, units, coordinate system, and file name) associated with particular GUI variables. Select the variable to be examined in the tree at the right and select the magnifying glass button to examine the meta-data. A menu like the verify menu will pop-up and you can view or edit the meta-data for the selected quantities.

Export To Image File

Export to Image File

The Export to Image Menu allows you to generate an image file of your currently active page. The SPEDAS GUI supports the following file types: Portable Network Graphics (.png), Encapsulated Postscript (.eps), Windows Meta-File (.emf, Windows Only), Windows Bitmap (.bmp), Graphics Interchange Format (.gif), Joint Photographic Experts Format/JPEG (.jpg), JPEG 2000 (.jp2), Apple PICT format (.pic).

The EPS export uses the routine ssl_general/misc/fancompress.pro to decrease the size of line plots when exported to EPS. EPS files without compression can be tens or even hundreds of MB large. Fan Compression should generally keep the EPS size down to less than 1 MB. Fan Compression removes redundant data points using an IDL implementation of the algorithm described in the paper: Fowell, Richard A. and McNeil, David D. , “Faster Plots by Fan Data-Compression,” IEEE Computer Graphics & Applications, Vol. 9, No. 2,Mar. 1989, pp. 58-66.

EPS files created by the GUI with large line resolution percentages may take a long time to read in postscript readers.

Figure 3.3.9 shows the Save Image window. The directory to which you will output is listed at the top. The 'Arrow' button will allow you to move up one directory. You can also edit the directory by typing directly into the directory field, or selecting the desired directory from the directory list below.

The file name for output is listed in the text box at the bottom. Change the output format by selecting a different type from the 'Save As' dropdown menu at the bottom. The 'Options' button will show the graphics output options for the selected file type. These options will change depending on the file type. They involve things like the size and resolution of the output file.

When you are ready to actually save the file, select the 'Save' button, and the requested file will be saved to the selected directory. If you change your mind select the 'Cancel' button or the 'X' in the corner.

NOTES:

1. .EPS and .EMF both support vector output. A file produced with vector output can be resized without pixelation, and can be edited in Illustrator (or similar programs) e.g. text (labels, titles) that appear in the document can be edited directly as text objects, fonts can be changed, line color can be edited. To turn on vector output for either of these format types, press the 'Options' button and select 'Vector'.
2. If vector output is selected for .EPS or .EMF format, text that runs of the edge of the page will not appear in the saved image file e.g. if part of a y axis label is cut off the left hand side of the active page, the entire label will not appear in the saved file. Page margins can be easily changed under Graph->Page Options, Layout tab, to ensure all labels are visible on the page.
3. Setting line plot resolution at or past 70% can make the file unreadable due to the size of the file.

Print

When the Print option is selected under the File pull down menu an IDL print dialog window will be displayed. The default print device will be displayed and you can choose the number of copies you would like printed out. If you do not wish to use the default printer listed, please see Section 3.3.11, Printer Setup, which allows you to select from all printers that are recognized by your system. In addition, the Printer Setup window allows the user to control additional print parameters.

Figure 3.3.10 shows an example of the print dialog window.

NOTE Printing in IDL can be unreliable depending on your combination of Printer and OS. If you have any problems printing, you should export your document to an Image (EPS or PNG) and print directly using your an OS specific image viewer.

Printer Setup

The Printer Setup option available under the File pull down menu allows the user to set up print parameters, select print devices, and print. The Print Setup option displays the standard IDL print dialog window. All print devices that your system can detect are listed in the Select Printer box. In addition, you can control the number of copies, page range, collating details, and preferences associated with the print device you selected. For detailed information about this dialog box and the preferences you can set, please refer to the IDL User’s Guide.

Configuration Settings

SPEDAS Configuration Settings

This button pops up a window that allows access to the system variables that control the automatic downloading process. You can type in values for the different options in the window. Tabs at the top of screen allow selection of configuration parameters for the different missions that the GUI supports loading data from. New tabs can be added (of removed) in the future, depending on the number of missions that the GUI supports directly.

The first tab contains general SPEDAS configuration settings, such as the temporary directory that can be used for downloading files, the verbose level for tplot messages (warnings and general information messages) and the name and path of the preferred browser executable (which is especially useful for Unix-type machines).

The next tab contains information for the THEMIS mission files. The top text box gives the local data directory. THEMIS data that are downloaded are written to this directory. The default value for users who are logged on to an ssl.berkeley.edu machine is "/disks/data/themis/". For windows users, the default value is "C:\data\themis\". It can be set to any directory for which the user has write permission.

The second text box shows the remote data directory. The default is http://themis.ssl.berkeley.edu/data/themis/

Next is the control for automatic downloads. (This should be set to "Use Local Data Only" for local SSL users, or anybody who has the entire database stored locally).

Next is the control for file updates. If turned on, a file will be re-downloaded if a file with a newer timestamp is found in the remote data directory. If turned off, files will only be downloaded if they are not stored locally.

The verbose flag controls the number of messages that will be displayed. Set this to a number from 0 to 10. The higher the number, the more messages you get during processing.

The graphics mode allows you to select whether the graphics rendered are done with hardware or software. Rendering of graphics varies based on your system and platform. If your graphics are slow to display, you might want to switch your graphics mode. Our testing has found that software rendering generally provides faster graphics with fewer artifacts.

The template check box gives you the option of choosing a previously saved SPEDAS template to load whenever the GUI is run. This lets you set default plot and axis options e.g. font sizes, colors, grids etc. See Section 3.3.4 for general information about SPEDAS templates. Note that when a default template has been loaded from the configuration settings it is still possible to change the template in use in the GUI session by choosing File -> Template -> Open Template.

The Configuration Settings window is show in the figure to the right.

RESET

If you press this button, configuration settings are returned to their original state prior to opening this window.

RESET TO DEFAULT

If you press this button, the configuration is returned to the default state in THM_CONFIG.pro, and any saved configuration file is deleted. This means that if you want to go back to a configuration that you have saved previously, you need to reset the values and then save the configuration. Alternatively, you can locate the previously saved file and copy it to the appropriate location in the APP_USER_DIR shown below.

SAVE

If this button is pressed, then the current configuration is saved in a file. This file ends up in a directory created by the IDL APP_USER_DIR routine, on a windows system the path looks like this: "C:\usernme\.idl\themis\thm_config-4-win32\thm_config.txt". On a Linux machine, it looks like: "$HOME/.idl/themis/thm_config-4-linux/thm_config.txt"

Important

Once you have saved this file, it will always be read when you run any SPEDAS routines -- you should only need to do this once for each operating system that you are using. Whenever you save a new file, the old file is copied to a file tagged with the current date and time.

Exit

The Exit option under the File pull down menu will terminate the SPEDAS GUI session. All windows will be closed and control returned to the command line.