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
		
		
