QSAS: A Science Analysis System for Space Plasma Data
QSAS Main Window

Contents:
|
|
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.

The Working List Data Object Browser
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.
The Time Interval Object list is managed in the same way as the data list.
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 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. The up and down arrows
move item selection on the working list up or down one entry, while Ctrl+arrow
will move a single selected item itself up and down the list. 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.
-
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, csc-support-dl@imperial.ac.uk
Last up-dated: October 2016 Tony Allen
