QSAS: The QMUL Science Analysis System
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 theEdit
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 ASCII names and path on the working list.
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 ASCII 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.
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,
following the algorithms (but not quite the same internal representation)
as that employed by Common Data Format libraries.
Since v2.2.09, event tables are also handled by QSAS. These are basically ordered series of time intervals. They are not used for analysis yet,
but they allow 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.
All three lists 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.
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).
-
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.
-
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 machine independent
XDR 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 sane
session, including data.
-
Save Session As...
- is the same as Save Sessiont, 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. Active plug-in windows are
saved by the save Session command, but must be restored individually from
the session folder as the plug-ins are created dynamically when used -
launch the plugin and use its own restore option under File.
Edit
-
New Object - allows
creation of new objects. The type of object to be created can be selected
from the menu dialog launched. Not all data object types are yet
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.
-
Re-Name Object - provides a dialog window to allow an object
to be renamed on the Working List.
-
Select All - 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 - self-explanatory.
-
Clear Working List - deletes the data objects of the Working List.
-
Clear Time Interval List - deletes the time interval/event table objects.
-
Clear Selected Cache - to avoid doing too much computationnally intensive processings, QSAS holds a cache of the dimensionnally-reduced objects.
As this consumes memory, you can free some by clearing specific objects' caches or by freeing all the caches, with the Clear Cache option.
Analysis
-
Calculator - allows the user to construct and chain
arithmetic operations on data as well as constant values created at the
calculator level.
-
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...
-
Join -
resamples time series data to put them onto a common set of time tags.
It also can be used to resample data onto regularly spaced time tags.
-
IRM_TS_onboard_tags - converts the AMPTE-IRM instrument's ground-receipt timetags to UT on board the spacecraft.
-
TimeSeriesSubset - Filters the data of a time series that fits in a given interval (or a given data object's time range).
-
TimeShift - Shifts time tags by a given number of seconds.
-
TimeStretch - Shifts and stretches an object's time interval to fit another input time interval.
-
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.
-
Statistics - simple statistics.
-
Event Tables - simple utilities to sort event tables, or to perform set operations.
-
Sub-sample - a simple utility to reduce an object's dimensions.
-
Array to vector - allows to add the required frame and representation field to make an array into a valid QSAS vector.
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 subdirectories 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
(but only after restarting QSAS).
Plot
The Plot Specification option opens up the Plot
User Interface, from which panel plots (on screen or postscript files)
may be specified in a flexible way.
Profiles
You can either select a predefined user-profile or manage yours 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 arror 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.
Bugs
None known
Page created by Steve Schwartz, csc-support-dl@imperial.ac.uk
Last up-dated: October 2008 A Rochel
