QSAS: The QMUL Science Analysis System
Introduction
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 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 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.
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.
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.
See QSAS Array Reduction.
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.
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.
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.
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.
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.
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.
Page created by Steve Schwartz, csc-support-dl@imperial.ac.uk
Last up-dated: October 2008 A Rochel