QSAS: The QMUL Science Analysis System

Introduction

# Contents:

- Overview
- User Interface

- Mouse Behaviour
- Data Objects and Time
- Object Drop Slots

- Getting Started

- Restore Sample Session
- Data Ingestion
- Export
- Saving
- Quitting

- Tips/FAQ
- Bugs

# Overview

The Queen Mary Science Analysis System (QSAS) is a multiplatform application tailored to the analysis and display of data from space plasma missions. It can ingest, manipulate, display, and export science data, and pays particular attention to the associated "metadata" (units, reference frames, etc.). Most space plasma measurements are made sequentially in time, and QSAS has been specifically designed with this in mind.

QSAS is based around three concepts:

- ## Data Handling

  Data ingestion is achieved either via an advanced hierarchical view of data held in a database or a simple file-oriented facility. Once ingested, data together with metadata (reference frame, units, etc.) are held in internal data objects and available to the user from the Working List on the main QSAS window. Data objects are referenced by ascii names.

  Data objects may also be exported to files in either Common Data Format (CDF) or as ASCII flat files.

- ## Data Analysis

  Data objects may be manipulated by in-built analysis routines, such as arithmetic or time series joining algorithms. Additionally, user-written plug-ins may be utilised through a dynamically-built interface allowing specialised routines to be created and made available without re-building the entire QSAS executable. Some plug-ins are distributed with QSAS by the QSAS team. The results of all analysis routines are returned to the Working List for use in further analysis or display functions.

- ## Display

  A flexible panel plot interface allows the user to construct panel plots drawing data from any object on the Working List. Interactive cursor use enables the user to expand plots and/or save time intervals which may be passed to other analysis routines or control the plotting ranges of other panels.

# User Interface

QSAS is an interactive application, and the interface conforms largely to standard graphical user interface (GUI) conventions such as the use of pull-down menus, buttons, selectable scrolling lists, pull-down option menu buttons, and such. A few key concepts and actions are worthy of note here.

## Mouse Behaviour

- Selection (highlighting of a Working List Data Object) is performed by a single click of the left mouse button
- Information/Action is sometimes performed by a double click. For example, double click on objects held in the working list on the main QSAS window will result in a browse and edit window on the object contents and properties. Alternatively, in other scrolling lists of QSAS objects it will open an editable information window showing the "Working List context", that is the path and name of the object it refers to in the Working List.
- Drag and Drop is used extensively throughout QSAS. This is accomplished by a "down" left button over the desired object (which doesn't actually need to be selected first), dragging it keeping the button depressed until it is over a drop site and then releasing the mouse button. This works also on groups of objects selected with multiple selection. QSAS will bring the underlying window to the top when any visible part of it is under the mouse during drag, so to access a drop site not immediately visible, first drag across another part of the target window, then back to the newly revealed drop site. List views within windows do not at present register for a drop until after the mouse has passed over another part of the window containing it.
- Multiple Selection A selection may be extended within any of the lists of QSAS objects. Holding down the shift key while making further selections will select all objects between the original and final selections, while control clicking will add (delete if already selected) from the selection. Only object lists accept drop from a multiple selection. Drag on a multiple selection is initiated with a single left "down" exactly as for single selections.
- Copy and Paste can usually be used as an alternative to Drag and Drop. Depending on the keyboard and window manager (and window) Copy can be accomplished by one or more of: Copy key, Ctrl+C, right click and select copy, with matching Paste functions performed by Paste key, Ctrl+V, right click and select paste. Most fields also accept the typing of text directly by the user. The last drag operation is normally stored in the copy register and the drop operation may be repeated using paste.
- Right Mouse Button brings up a context sensitive menu of operations that may be performed on the selected object, such as move, copy, delete etc.
- Interactive Graphics Cursor selection is done by dragging a rectangle using the left mouse button.

## Data Objects and Time

- Data Objects form the underpinning of all QSAS functionality. They include ingested variables, the results of analysis routines, time intervals, and constants. Internally, QSAS data objects are C++ objects which include metadata (descriptions, names, cross-references to other objects or timetags, units, etc.). For efficiency, all data objects are held in active memory.
- Management of data objects is accomplished from the scrolling lists on the Main QSAS window using either right click and selecting an option from the pop up menu, Ctrl+up/down arrow to move (and other shortcuts), drag and drop and double click to pop up a browse and edit window. Management includes ordering the lists for convenience, creating subfolders and deleting objects to free up memory.
- Names of data objects (and the path if they are in folders) are used to pass the objects from one window to another, by "drag and drop", "copy/paste" or direct text entry. Names are resolved to the underlying object only when some analysis/action is instigated, but each object on a list of objects knows the full path and name of the object it refers to on the Working List. Therefore, replacing an object on the main window "Working List" with another of the same name will result in the second object being accessed by all other GUIs which have that object in a Drop slot. This behaviour minimises confusion and enables previously used analysis or display configurations to be re-used on similar data, e.g., from another time period.
- Time Interval objects can be created and edited in many ways, and hold a pair of ordered Start-Stop times. QSAS handles time as Universal Time without leap seconds. Apart from slight internal represenations, QSAS essentially handles time in an indentical fashion to NSSDC's Common Data Format (CDF).
- Event Table objects are edited as sequences of Time Intervals. They can be converted from/to VO table files. At the moment, the support for event tables is still basic.

## Object Drop Slots

See QSAS Array Reduction.

# Getting Started

QSAS is run from a script which ensures that the appropriate local paths and environment variables are set. User-specific parameters are stored in profile files, which can also be edited easily manually (~/.qsasrc on Unix, Documents and Settings\User\qsas.ini on Windows).

On launching the QSAS (or QSAS.bat) script the QSAS Main Window, containing a Working List of Data Objects, will appear. This is the centre of all QSAS operations.

## Restore Sample Session

As a very brief introduction, pull-down the File Menu and select Restore Session. The resulting File Selection widget should be navigated to the /tmp directory of the QSAS installation. Select the SampleSession.qss directory and click OK. This will restore a session with some Cluster Summary Parameter data, and particle counts arrays, placing the data objects on the QSAS Working List.

Double click one of the Data objects on the Working List to browse the data and metadata attributes. The same Data Browser is used throughout QSAS. This Browser also allows you to edit both the data and metadata associated with the object.

Pull down the Plot menu and open up the Plot Layout. You will see the layout which was saved in the Sample Session. Pushing the Plot button will give you an on-screen plot. The plot Window can be resized, but the aspect ratio of the plot is constant to reflect the page format.

Note that the spectrogram at the bottom was plotted from the 3D ion distribution (for a different time period with its own T-axis) using the pulldown menu on the input data slot. For this plot the array was summed over both angle dimensions to give a 1D array time sequence for a spectrogram binned in energy. The same array reduction pulldown could have sliced the data at a specified bin or taken a subset by selecting only certain bins for inclusion.

You can modify many aspects of the Plot. Try multiple-selection of the the first three Traces by clicking on Data/B1_xyz_gse__C1_PP_FGM [x], then Ctrl-Click on Data/B1_xyz_gse__C1_PP_FGM [y] and Ctrl-Click again on Data/B1_xyz_gse__C1_PP_FGM [z]. The Right-hand side of the Plot GUI now shows you options for the selected items, some of which will be grey to indicate either that the selected items have different entries in that field. Select the Trace Tab and choose a new colour for the traces by pushing the Colour button, then Plot.

Frame 1 shows the use of the plot legend, which is normally used for multiple traces in a single plot, while frames 2 and 3 show use of rotated axis labels.

Now select Frame 1 in the list on the left, which will select everything underneath it in the hierarchy. The Tabs on the right provide control over various aspects of the Time Series Frame (a vertical collection of panels which share a common time axis). Select the T Axis tab. Now, from the Working List on the QSAS Main Window, Drag the "shock period" Time Interval onto the White Drop Slot called "From Object". Pushing Plot will then restrict your plot to the time interval specified by "shock period". By double clicking "shock period" on the Working List, you can edit the time interval to which it refers, and then push plot to investigate other time intervals. You can also change the plot time interval, and/or the time interval associated with a Time Interval object on the Working List, interactively. To do so, select the Value Return tab. Pushing the "Get Values" button will launch the Interactive Value Return GUI. Select a time interval by dragging a selection rectangle within a panel. Return to the Value Return GUI, uncheck "Rescale Y axis" and press "RePlot" to check your time range. Pushing "Save X T interval" will save this to the Working List with a specified name. Drop that new object into a T Axis drop slot (or several) to interactively select various time intervals of interest. Such Time Intervals can also later be used by Analysis routines.

Selecting Frame 1 again, T axis tab, and selecting "Autoscale" from the "Use" combobox box will return you to the full time range.

Now Delete the entire Page. Multiply select several objects on the Working List and drop them onto the blank hierarchy. QSAS will create a separate frame or for each which depending on where they are dropped. The Panels can be moved to occupy the same frame, and the empty frames then deleted. If first you create a new Frame and then drop objects onto it, QSAS will put the new panels onto the same Frame.

QSAS can perform simple analysis. There are two principle routes for performing analysis, the Calculator and externally written plugins.

The Calculator menu on the "Analysis" menu launches an unified join and calculate window. The sample Session shows this being used to calculate a normalised B field (dividing B by Bmag) and also calculating Vp x B. The calculator can chain operations together, with outputs from some operations forming the inputs to others. In this example the Vp x B object is then passed through a filter to convert it into different units (using SI_conversion). Note that the user does not need to know the units of the original objects since QSAS will take these from the SI_conversion attributes of the input objects, even if they are themselves the result of an operation (QSAS keeps the correct resultant SI_conversion and other attributes with data objects it creates whenever possible.).

Objects created in the calculator are automatically saved back to the working list, while, by default, inputs are not (even though they are joined), however this can be controlled by a toggle on the object tab.

You may also like to play with the Cluster Configuration Plugin under Plugins->Geophysics->QClusterConfig. Drop the 4 spacecraft dr's in the corresponding drop-slots, and the "shock period" time interval into the Time Interval. Run this Plugin and follow the subsequent instructions. QSAS comes with a range of Time, Maths, Geophysics, and Analysis tools/plugins; you can also write your own by following the guidelines given in separate documentation.

At any/all stages, you may save either a single GUI or the entire session for later use, or to protect against mistakes or crashes. This is described more fully in the Save/Restore Help Pages.

## Data Ingestion

There are other ways to get data onto the Working List in addition to simply restoring a previous session. The user should pull-down the Files menu at the top of the Main Window. Choose the Data Selector to access a local database or Open Data File to open a single data file.

Choosing Data Selection causes the data selection interface to appear. Pull down the Database menu, and select Open..., which should bring up a standard file selection widget pointing to the config directory within the QSAS home directory. A sample dataset is supplied with QSAS, and at installation a 'data contents map', SP.dcm, should have been created (see QSAS Installation Notes). Other datasets, identified by their ".dcm" name extension, may also be present. Select a dcm file and push the Open/OK button. The Data Selection window will now show the available variables in the database and the availability of data for the last day present in the database. The Time Interval edit window at the bottom can be used to change the time interval selected and this is reflected in the data availability display next to each variable (dark means data is available). Select (left-click) a variable and press the >>Add>> button to add it to the selection window (or just double click on the variable). Push the GetData button at the bottom and a data object containing data for the variable(s) selected for the interval specified will appear on the working list in the Main Window. Then Dismiss this GUI using the button provided.

If there is no database available yet, choose Open Data File, which will pop up a file selection window. Navigate to the SampleClusterData directory in the QSAS home directory, or to another data file you wish to open. Select a data file and click OK (or double click on the file). In the resulting data selection window select a variable and push GetData. Dismiss this window when you are done. You may browse (but not edit) the file's data or metadata using the Browse Data button or by double clicking on an item.

The Working List will now show the data object(s) loaded in the top section, labeled "Data". Double-clicking on one of these objects will pop-open an edit window in which you can browse and edit values in individual records, view the global file metadata, and also view/edit the QSAS metadata associated with that data object. Dismiss this window after you have familiarised yourself with the information contained.

## Export

You may save any data object, especially those you create using analysis tools, such as the Ratio we created above. Choose the File menu from the the QSAS Main Window, and select Write Data File. Drag the Ratio data object on the QSAS Main Window Working List to the Object list in Export window. Push the Export button to save Product to a file. Note that if multiple objects are saved to the same file they will be joined onto the same time line, and the right hand panel controls the associated join options.

On pushing the Export button a file selection window will pop up. This allows choice of data file format and the location for saving it. The default is the Cluster Exchange format (ASCII) file type. It is also possible to save in the NSSDC CDF format used for Cluster PP and SP data. Saving in ASCII format can often be useful to make data/analysis results available to other applications.

## Saving

The whole QSAS session can be saved at any time using the Save Session option under the File Menu. This may then be restored through the corresponding Restore Session option. All windows that support save/restore will be restored to the state they were in when the session was saved with the exception of plug-ins which must be restored individually from the saved session folder since they are dynamically loaded. The data on the working list is also saved and restored, and is not retrieved from the data base afresh. This allows the session file to be transferred to another machine or site and for QSAS to restore complete with data.

Similarly, some windows support save and restore individually, and the default locations are different for the session and the individual windows so that a session save does not overwrite an individual window's save file. The Save As... and Save Session As... options allow for any number of different save files to be created by choice of location and file name. File extensions identifying the window involved are mandatory and will be appended in not provided. When a window is saved individually, it is possible to choose to save it with the data or with the window settings alone. If save with data is selected, then restore will place the data on the working list, and this will become renamed if it duplicates an object already present. In this instance the object in the window will refer to the restored object on the Working List, not the original.

## Quitting

To quit QSAS, choose Quit from the File menu of the QSAS Main Window. A dialog pops up with the option to save the session, quit or cancel. Only the Quit option will actually close QSAS.

# Tips/FAQ

- Any time series object can be used when a "Time Interval" object is required. That is to say, if a drop box is expecting a Time Interval Object, a Time Series Object can be dropped there. The resulting time interval corresponds to the earliest and latest times of the time series.

# Bugs

- Drag and drop behaviour is dependent on the platform being used, the cursor does not always show correctly during a drag.

Page created by Steve Schwartz, csc-support-dl@imperial.ac.uk

Last up-dated: October 2008 A Rochel