QSAS: A Science Analysis System for Space Plasma Data

QSAS Main Window

Contents: Overview Purpose/Function Use Working List Data Objects Time Intervals Constants Temp Menu Bar File Edit Analysis Plug-Ins Plot Profiles Help Right Button Menu Option Settings Tips/FAQ

Overview

Purpose/Function

The QSAS main window is the control centre for QSAS and is opened by the QSAS start up script. Its menus provide access to QSAS functionality, and its scrolling lists hold the data objects for the user to inspect, pass to other QSAS windows, and send results back to. It is a key QSAS design to retain all data and results in memory and available for further use, rather than a single pipeline approach in which data is passed once-only down (and out of) a processing/plotting chain. This enables rapid, flexible explorative analysis.

Use

See the Introductory help page to get started. QSAS sessions invariably start with data selection via the File Menu. Selected data is returned to the top-most scrolling list, from where it may be passed for analysis, display, or export. Time Interval objects are important in space data analysis, and are provided with their own scrolling list in the middle of the window. Useful constants, to which the user may add, are held near the bottom. List management and creation of new time interval or constant objects is through either the Edit menu, right button click on an item or keyboard shortcuts. Objects may also be browsed and edited by double-clicking their names. Throughout all of QSAS, objects are referenced by their text names and path on the working list.

The main window has a toolbar which provides shortcuts to some menu items. This may be toggled on and off using the hide/show toolbar item on the File menu. It is also possible to set in a Profile whether it is on by default at startup.

Working List

Data Objects

The top-most scrolling list holds ingested data and analysis results. These are internally C++ data objects which include all the metadata (units, reference frame, etc.) associated with the object's data. Objects are referenced by text name, and may be passed by various means (see the User Interface discussion in the Introductory Pages).

The values of the data may be browsed by double clicking on the object name to open the Data Object Browser. The slider can be clicked or slid by the usual windows methods to locate any data record. The File Metadata which populates the right pane of the data browser window corresponds variable metadata. Double clicking on the name of an attribute will in turn launch an editor showing its values. Editors allow the data to be viewed and changed. If a change is made it becomes possible to save or save as a new object. All metadata is retained with the object on export. However QSAS only requires 4 entries:

• FIELDNAM identifies the data and is also used in plot labels
• UNITS provides a text string for plot labels
• Frame is a fixed format entry of the form: vector>gse_xyz which, for physical vectors and tensors identifies the coordinate frame and representation; for scalars the Frame metadata is not applicable, and Cluster data, for example, has entries scalar>na
• SI_conversion is a fixed format entry which gives the numerical factor by which to multiply the values of the variable to convert them into their base SI unit, and the resulting SI unit. The example shown is 1.0e-9>T, which means multiply the values of the magnetic field as contained in the object by 1.0e-9 to get the value of the magnetic field expressed in Teslas. QSAS arithmetic routines make extensive use of this information to ensure that operations are meaningful and the results have SI_conversion set appropriately.

Objects may be dragged and dropped within the working list to change their positions. It is also possible to create folders hierarchically to group data objects, see the Edit menu. Any objects selected at the time a folder is created will be placed in the new folder. Folders may also contain sub-folders, and folders can be dragged and dropped. Objects may also be moved using command + up arrow or Move Up/Down under the File menu.

Time Interval Objects

Time plays a central role in the analysis of space data, and the middle scrolling list on the QSAS Main Window holds Time Interval Objects, which are ordered Start-Stop pairs. QSAS uses Universal Time without leap seconds.

Event tables are also handled by QSAS. These are ordered series of time intervals. They allow the user to store and sort various time intervals, and can be imported from and exported from VO tables.

Throughout QSAS, whenever a time interval is required (e.g., to set the range on a time series plot), there are three methods for the user to specify a time interval:

• Time Interval Objects from the Main Window - Drag and Drop like any Data Object onto the appropriate drop slot.
• Time Series Objects - any time series object, such as a time series of magnetic field measurements, implicitly represents a time interval defined by the earliest and latest times contained in the object. QSAS drop slots expecting a Time Interval Object will accept a time series object.
• Time Editor - double clicking a Time Interval Object or selecting New Object->Time Interval in the Edit Menu will open a Time Editor. Some windows, such as the Hierarchical Data Selector contain an embedded time editor window. All time edit windows have an option to accept drop of a time interval (or time series) object as input.
• Event tables - reducing an event table's dimensions to a single element results in a time interval that can be used on any appropriate slot.

Constants

For reference purposes and arithmetic conversions, QSAS provides a set of commonly used constants as data objects. These may be browsed and edited by double clicking, which invokes the Data Object Browser. Additionally, the user may create new constants from the Edit Menu, or dragging an object from the data list.

Temp

The calculator will store intermediate objects on the working list under the Temp folder, and delete them when finished. If a calculation does not complete correctly, then objects here can be inspected to help diagnose the problem.

Data and Time Interval and folders created within them are open by default so that the objects held are visible, they may be closed by clicking on their root decoration to free up visble space on the list and minimise scrolling. The Constants and Temp folders start closed to save space.

Menus

File

The File Menu covers Import (from CEF, CDF or ASCII), Export (to CEF, CDF or ASCII), Save/Restore for the main window and Save/Restore for the whole session, and Quit to close the session. There are two ingestion routes:

• (Hierarchical) Data Selector - for accessing locally configured databases. These databases allow the user to select data through customised naming hierarchies without knowledge of the file/directory location or structure, or the internal variable names. Additionally, data availability information is provided in graphical form and specific time intervals can be extracted.
• Open Data File - the View and Import Data option enables the user to open up and browse individual files. Variables can be selected (individually) for ingestion onto the Working List.
• Write Data File - exports data on a single timeline (joining if necessary) into any of the data file formats understood by QSAS (CEF, CDF, ASCII tabular, ASCII delimited).
• Load Event Table - imports an event list from a VO table.
  
• Export Event Table - exports event lists as a VO table.
  
• Save Working List - saves the current data objects and options for the main window. This stores the actual data in the save file rather than the location in the database so that a save file can be sent to another user at a different site who will then be able to restore to the same data objects, including those created by processing within QSAS.
• Save Working List As... - is the same as Save Working List, but provides a file dialog to allow the user to choose the location and name of the save file.
• Restore Working List -  provides a file dialog to allow the user to choose the location and name of the saved file to be loaded into QSAS to restore the main window settings and data.
• Include in Working List -  includes the saved Working List objects into the current list without deleting existing objects.
  
• Save Session - saves the current QSAS session. This saves files corresponding to each of the principal QSAS windows that have been created during the current session. Data on the working list is stored with the session, and all files are placed in a single folder (the default or last session folder chosen if Save Session As has been used). These filese are in ASCII XML format and the whole session directory may be tarred up and copied taken to another machine which will then be able to restore to the same session, including data.
• Save Session As... - is the same as Save Session, but provides a file dialog to allow the user to choose the location and name of the save session folder.
• Restore Session - provides a file dialog to allow the user to choose the location and name of the saved session folder to be loaded into QSAS to restore the principal QSAS window settings and data.
  
• Hide / Show Toolbar - will hide or display the toolbar shortcuts on the main window.
  

Edit

• New Object - allows creation of new constant objects. The type of object to be created can be selected from the menu dialog launched. Sequence data object types are not supported.
• New Folder - creates a new folder on the Working List. If items are selected they are placed together in the new folder. Folders may be dragged around the working list and into other folders to become sub-folders.
• Duplicate Object - creates a copy of the selected object on the Working List.
• Subsample/Extract - brings up a dialog that allows an object to be sub-sampled using a data slot, named and placed on the Working List.
• Edit Object - brings up an object data and metadata browser (double click on an object in the Working List is a shortcut to this) that permits browsing and editing an object. The edited object may be saved as a new object or replace the original.
  
• Re-Name Object - provides a dialog window to allow an object to be renamed on the Working List.
• Select All Data - selects all the objects in the Data list in the Working List.
• Delete Object - deletes the selected item from the Working List along with its associated data and metadata. Any object in another window referring to this data object will become orphaned and will show as red. Orphaned references may be relinked to a new data objects (double click on reference and type or drag and drop new name).
• Remove object's time tags - deletes the Depend_0 metadata of the object.
• Clear Working List - deletes the data objects of the Working List.
• Clear Time Interval List - deletes the time interval/event table objects.
• Move Up - moves the selected item(s) up within the Working List. 
• Move Down - moves the selected item(s) down within the Working List.
• Sort Selection - sorts the selected items according to the condition set in Set Sort Prefs.
• Sort Working List - sorts the entire Data folder of the Working List according to the condition set in Set Sort Prefs.
• Set Sort Prefs... - allows selection of the criterion and direction used for sorting (object name, start time or object type).
  

Analysis

• Calculator - Launches the Calculator window that allows the user to construct and chain arithmetic operations and plugins.
• Particle Tools (PSD) - Launches the tool to slice and create moments etc from Phase Space Densities.
  
• Simple Maths

  Basic mathematical operations are provided. These work between any data objects conformal for the selected operation. In binary operations, if two time lines are selected then they must have the same time tags, and the operation is applied between corresponding entries. If one object is a constant (which may be typed into the value filed as a numeric value) then this value is applied to each of the entries in the data series. If the objects are not conformal for the selected operation then the operation is rejected.

  The metadata associated with each object in a binary operator is checked to ensure that the operation is safe. If the metadata is missing then a warning is issued but the operation proceeds. For example, addition of two objects with different units (from the SI_conversion attribute) or vector multiplication of two vectors with different reference frames (from the Frame attribute) would be rejected.

  The essential metadata (Fieldnam, SI_conversion and Frame) for the resulting object are created from the input values. An attempt is made to construct the Units attribute, but this may need editing to reduce it to its simplest form for plot labels.

• Change Units - a set of basic units converters. Units can be converted to SI (ToBaseSI), to the same units as another object's (ToObjUnits) or to arbitratry units (ToUnits).
• Time Ops... - a collection of operations on the time tags of an object, including joining data series.
• Filtering - A set of utilities to remove values over or below a given value (FilterGT, FilterLT), or to remove fill and Not A Number values (RemoveFills, RemoveNaN). If a component of an array or vector is removed, then the entire array or vector and associated time tag are removed.
• Vector Methods - specific operations on vector objects.
• Array Methods - specific operations on array objects.
• Statistics - simple statistics.
• Event Tables - simple utilities to sort event tables, or to perform set operations.
• Angle Methods - trigonometric and other operations on data that represent angles (mostly for metadata manipulation).
  
• Sub-sample - a simple utility to reduce an object's dimensions.
• Derivative - launches a window to take a numerical derivative of a time series.
• Integral - launches a window to form an integral over an inerval of a time series object.
• Merge TS Objects  - concatenate two time series objects on time, removing duplicates overlap.
• Create Regular - create a series of data based on data type, start value, number of records required and spacing.
  

Plug-Ins

Plug-ins are separately compiled routines, which may be written by the user or others, typically taking inputs from data objects on the Working List and returning result objects to the Working list.

A set of useful plugins are shipped with QSAS and are separated into two broad categories - Geophysics and Analysis.

• The Geophysics plugins cover operations such as determining boundary normals, rotating coordinate frames, changing vector representations or extracting single components from vectors, magnetic field models and a Cluster configuration viewer.
• The Analysis plugins cover operations such as power spectral analysis, wavelet analysis and minimum variance.

The Browse option from the Plug-Ins menu will pop up a file dialog window which can be used to load a third party plug-in compiled separately from QSAS. This is used to select the template file (.qtpl) for a locally developed plug-in that has not been added to the QSAS installation. Selecting this template file will then enable QSAS to read it and construct the appropriate GUI and run the associated shareable object file (.so) containing the executable code. A more detailed explanation is provided in these help pages, but a separate document, Writing QSAS Plugins, provides more detailed information for programmers.

To add a new plug-in into the local QSAS distribution it is necessary to place the new template file in one of the sub-directories of QSAS_HOME/qtpl and the .so/.dll library associated with it into QSAS_HOME/lib.

The sub-directories of QSAS_HOME/qtpl are Analysis, Geophysics, Arithmetic, EventTables, Filtering, UnitOperations and TimeOperations.  The Refresh Menu option under Plug-Ins will then cause the new plug-in to show up under Geophysics or Analysis if it was placed in one of these directories. Alternatively it will appear under the top level menu Analysis if placed in the appropriate directory after restarting QSAS.

Batch Processing

Run Batch File also appears under Plug-Ins. This is a distinct utility that opens a batch processing window. Batch processing is controlled by a script.

Plot

• Plot Layout  opens up the main  Plot User Interface, from which panel plots (on screen or postscript files) may be specified in a flexible way.
• 2D Polar View opens an independent plot interface for plotting 2D data in polar plots.
• Surface View opens an independent plot interface for plotting 2D data in cartesian or polar plots displayed in 3D with data value as height.
• 3D View opens an independent plot interface for visualising 3D data.

Profiles

Allows the user to either select a predefined user-profile or manage a customised profile using the Edit profiles interface. Profiles contain user-defined parameters specifying the behaviour and look of QSAS.

Help

• This Manual can be accessed as the first item in all Help menus in the principal QSAS windows. The manual is launched in a QSAS browse window; it does not launch a separate browser, but any html browser can be used to open this manual separately.
• Specific pages of the manual relevant to the current window can be accessed. From these pages there is an arrow to return to the QSAS Manual Index page, and a back button when applicable.
• Each Help menu has an option to display the version number of QSAS and the specific module for the active window.

Right Button Menu

Context sensitive right button option menus are available for some functionality within QSAS. These are provided as short cuts, and the same functions are available through the main Menu Bar or as keyboard shortcuts.

When the right mouse button is clicked with the cursor over an entry on the Working list, a menu is popped up with the following operations, which apply to the selected (single) item on the working list...

• New Folder - this works like the Edit->New Folder menu item except that it places the single selected item inside the new folder.
• Re-Name - this pops up a dialog box allowing the user to rename the object.
• Edit Object - this opens the browse and edit window for the appropriate object. Double click on the object has the same effect.
• New Object - opens a list of blank object templates to choose from. After choosing a template, a windows pops up to edit the object.
• Duplicate - creates a copy of the selected object in the Working List, appending "_copy" to its name.
• Slice Object - Generic dimension reduction tool: allows to take slices of multidimensional objects, but also to extract coordinates or norms in vectors.
• Make Array into Vector - allows to add the required frame and representation field to make an array into a valid QSAS vector.
• Time Interval Folder to Event Table and Event Table to Time Interval Folder - A folder containing time intervals is converted to an event table with the same name, appended with (evt table), containing the same time intervals, in the same order. The reverse operation is possible.
• Export Event Table - exports a selected event table to a simple VO table file, after specifying a name and destination folder in a file dialog.
• Copy - copies the name and directory path within the Working List for the selected object. This is kept on the clip board until another copy or a successful drag and drop operation (which replaces the clipboard with the drop text). This may be pasted into other windows that take a Working List object as an input.
• Move up/down - moves the selected object up or down one place in the Working List. This can also be achieved using the Ctrl key in combination with the up and down arrows.
• Delete - will remove the item from the Working List and delet the associated data object inside QSAS. This is the same as pressing the Ctrl key and backspace together.
• Remove time tags - removes the time tags of a time series object.

Option Settings

There are two toggle selection boxes between the menu bar and the Working List. When selected these control what records are stripped from data objects when they are placed on the Working List. These selections apply to any object placed on the working list irrespective of whether the object is imported from a database, read in from a file or produced internally by operations within QSAS. They are applied at the point of placing the object on the Working list, and stripped records are permanently removed from the QSAS object. If all records in an object are stripped out as the object is transferred to the working list, then the object is empty and will be rejected by the Working List.

• The Strip NaN option removes any data point and associated time tag from the object if any value in that entry is a non-valid value, such as resulting from divide by zero. If a component of an array or vector is removed, then the entire array or vector and associated time tag are removed.
• The Strip Fill Values option removes any data point and associated time tag from the object if any value in that entry is the fill value (taken from the object's fillval metadata). If a component of an array or vector is removed, then the entire array or vector and associated time tag are removed.

Tips/FAQ

• Keyboard Shortcuts are available for many operations, but availability may depend on the platform being used to run QSAS. An object may be deleted from the working list using Ctrl+backspace, and deletion of a non-empty folder will pop up a confirmation dialog. Double clicking on an item in the working list will open an editor window that allows the data to be browsed and edited. Other menu operations can be performed using Ctrl+ the character shown in bold in the menu list for that operation, for example, Ctrl+N will create a new Folder in the working list. Other shortcuts on the Working List and other lists are:
  
• Up and Down arrows move the item selection on the working list up or down one entry
• Ctrl + Up and Down arrows move the single selected item itself up or down one entry on the working list
  
• Left arrow hides the children of an item
• Right arrow shows the children of a folder
• Asterisk expands the selected folder and all its children
  
  
• Empty Objects and null objects are rejected by the working list. This can occur if all records are stripped out by Strip NaN or Strip Fill Values (see above) or an analysis module has returned an empty object. If this is suspected, turn off the Strip NaN and Strip Fill Values toggles and repeat the operation. If an object is created this time it may be browsed (double click on it to launch editor) to see the problem. If the object is still rejected or no item appears on the Working List, then the operation that should be creating an object is unable to do so.

Page created by Steve Schwartz, qsassupp@gmail.com

Last up-dated: October 2016 Tony Allen