QSAS: Calculator

# Contents

- Overview
- Calculator main window
- Creating a new operation
- Editing Calculator list of objects
- Selecting Components
- Joining Time-tagged objects
- Saving and restoring Calculations
- Summary
- Example

# Overview

The QSAS calculator allows the user to construct and chain arithmetic operations on data as well as constant values created at the calculator level. All basic arithmetic operations between two Working List objects, or an object and a scalar value, are available. Also provided are trigonometric, vector and unary operators, such as mod() or log() on an object.

Joining data objects onto the same timeline (from an object or constructed as a regular series of time tags) is done on the fly within the calculator. This removes the need to join before running the arithmetic plugins.

The result of an operation can then be used as an input for subsequent operations while it is still virtual. Circular references are, necessarily, prohibited, and are trapped by the calculator.

For instance, to compute (sin(Ax) + sin(21.1 deg) ) * B where A and B are vector and scalar time series objects on the Working List respectively, it is necessary only to...

1. Select the operation sin from the trig submenu
2. Drag the object A to the input slot for sin (this will also create an object A on the calculator list)
3. Select component x from the pulldown menu that appears on the input slot, deselect the save to WL toggle
4. Click new operation and select sin from the trig submenu in new tab that appears
5. Type 21.1 into the input slot and select deg in the pulldown that appears below the slot, deselect the save to WL toggle
6. Click new operation and select Add from the Arithmetic submenu
7. Drag objects sin(Ax) and sin(21.1) into the input slots on the add tab, deselect the save to WL toggle
8. Click new operation and select Multiply from the Arithmetic submenu
9. Drag the object sin(Ax) + sin(21.1) onto the first input slot of the add tab
10. Drag the object B into the second input slot for this add operation
11. Click the Do button and the result of this chain of operations will be placed on the Working List

Intermediary objects can also be saved as well as the result of the join operation on each input Working List object.

This calculator provides direct access to a number of unary and binary arithmetic operations and vector products. The arithmetic input slots accept any type of numeric data input. Input Arguments can be objects from the Working List or floating point constants typed directly in the input slot. If the input object type is a vector then a pulldown appears allowing the user to select a component or the object itself. If vector inputs are not valid in the operation then the object itself is not selectable. Virtual objects know their output type based on the inputs.

Most binary operations on time series data require the input objects to be joined onto the same timetags and the calculator performs a join before calculation. Binary operations involving a data/time series and a constant value will apply that constant value to each element of the data/time series.

Output objects are created and placed on the Working List with the name(s) given in the slot(s) if the save to WL toggle is on. The default for this toggle is on for each new operation and off for each data object from the Working List.

Join options are controlled independently for each input data object on the calculator list. It is possible to multijoin all input data before the operations are performed to remove any data gaps from all objects, and again afterwards to ensure all objects put on the working list are still joined (NaN results may be removed). If neither toggle is selected then join is performed as necessary before each operation.

The output objects include will have attached Units, Frame and SI_conversion attributes as appropriate after the operation.

The calculator is launched from the calculator menu of QSAS main window. The calculator can also be started by ctrl + C short cut.

Information bubbles are displayed for slots and operators if the mouse hovers over the item for a few seconds.

# Calculator main window

The main window that is shown when the calculator is stared is displayed as follows:

This window consists mainly of the:

GUI Item | Function
Menu Bar | List of pull-down menu items: File/Edit/Option/Help
List view of objects | Dropping site for the data object inputs for calculations. These objects refer to objects on the working list of QSAS main window. This list gives the name of the object and an alias which may be edited. The alias is a short name for the object to ease chaining operation as the original names are quite lengthy. The horizontal positions of the alias and name columns can be swapped by clicking on the title of one of them and dragging. In future releases the alias column will appear first as it makes reading easier.
Calculator Tabs | Each object whether data or virtual will have its own tab. It includes the joining options that are applied to an object for joining.
Time tag details | This group box displays the start, end time, number of time tags in interval, time tag spacing for the whole list of objects
Do Button | Button that starts the calculator
New Operation | Button that creates an empty operation and adds it within the current list view of object.
Dismiss Button | Button that cancels the calculator window
Log event text area | The text area where the logging information is displayed
Status bar | Main error message are displayed in red within the calculator status bar.

# Creating a new operation

When the 'New Operation' button is pressed an empty object is added to the calculator list and its tab is inserted into the calculator tab view. The label of this tab is the alias associated with the newly created operation.

Once an operation has been created the operation can be selected from the drop down menu of operators, the default operation is Add.

The operands can be either typed in or dragged and dropped in to the input slots. The operand fields expect either an alias or a constant float value. As the operation and operands are edited the associated name for the operation will be updated accordingly within the list view and its tab page.

The calculations are started by pressing the 'Do' button. Dependencies for each operation are resolved before the operation is performed, so there is no significance to the order of operations in the calculator list.

## Calculation Tab

This tab is created when New Operation is invoked or a data object is placed on the calculator list. It consists of the following items:

GUI Item | Function
Object Alias | The alias of the operation or data object. The alias can be changed by altering this field. This will lead to the label of its corresponding tab to be modified and all the depending operations (using this alias) to be changed.
Save to WL | This comprises a tick box and a name field. The tick box specifies whether to save the result of the operation (or join for a data object) onto the Working List. The default is on for a calculation and off for a data object. The name box is the name that will be used to save the object on the Working List. If this name is already used at the time of saving to the WL, than an A will be appended. The name is constructed from the inputs, but can be edited directly in the name field. Deleting this typed name will allow the name to revert to being constructed on the fly.
Operator | A pulldown menu of available operations which are divided into sub-menus.
Operand Slots | Input fields for the operands to the selected operator. The Join Only operation will refer to data objects on the working list. All other operators use the alias of the input object in these slots, whether a data object or a virtual object resulting from another operation. There are as many slots visible as there are inputs to the operand, and they are placed in the same order as the arguments to the operation in the operator name (with corresponding label A, B, C ...). If a Trigonometric function is selected the choice of Degrees or radians is based on the SI_conversion attribute. If this attribute is missing or not appropriate for an angle, then an extra pulldown appears allowing choice of angle measure. This slot is always present for inverse trig functions as the angle may be saved as either degrees or radians. Note that dragging an object from the Working List makes a new copy of that object on the calculator list, while dragging a data object from the calculator list itself into these slots uses the same object on the calculator list (see join below).
Join Options | The joining options are described under Joining. They are set independently for each data object on the calculator list. Since an object on the Working List may appear more than once on the calculator list, the same object may be joined in different ways for different operations.

### Operators

The operations may be applied to numeric type QSAS data objects (if the type is appropriate for the mathematical operation selected) or a numeric value or between QSAS objects and numeric values (in which case the numeric value is applied to each object in a sequence) . The operators supported within the QSAS calculator are:

Arithmetic:

Operator | Function
A + B | Addition of 2 objects (with same dimensionality)
A - B | Substraction of 2 objects (with same dimensionality)
A * B | Multiplication of 2 objects
A / B | Division of two objects (B cannot be a vector)
mod( A ) | Absolute value of scalar, Magnitude of a vector or Norm of a matrix.
A ^ B | Value of object A raised to the power of object B (B cannot be a vector)
+/- A | Change sign of an object

Trigonometric:

Operator | Function (A cannot be a vector)
Cos( A ) | Cosine
Sin( A ) | Sine
Tan( A ) | Tangent
Cosh( A ) | Hyperbolic cosine
Sinh( A ) | Hyperbolic sine
Tanh( A ) | Hyperbolic tangent
Coth( A ) | Hyperbolic cotangent
Cot( A ) | Cotangent
ACos( A ) | Arc cosince
ASin( A) | Arc sine
ATan( A ) | Arc tangent
ATan2(A,B) | Arc tangent of A/B using sign of both inputs to determine quadrant
ACot( A ) | Arc cotangent
ACosh( A ) | Inverse hyperbolic cosine
ASinh( A ) | Inverse hyperbolic sine
ATanh( A ) | Inverse hyperbolic tangent
ACoth( A ) | Inverse hyperbolic cotangent

Vectors Operators

Operator | Function
A x B | Vector product of two vectors
A . B | Scalar product of two vectors

Filter Operators

Operator | Function (A & B cannot be vectors)
A % B | Remainder = A modulo B
| A | | Absolute value of scalar
Ln( A ) | Natural logarithm
Log( A ) | Base 10 logarithm
1 / A | Inverse of a scalar or square matrix
sqrt( A ) | Square root
exp( A ) | Value of e (base of natural logaritms) raised to the power of A
Convert Units (A, B) | Converts units of A to those of B using SI_conversion xref of B or B as an SI_conversion string input itself, e.g. 1e-3 > m s^-1 to convert to cm/sec.
Convert Fills (A, B) | Converts all fill values in object A (based on FILLVAL xref) to value B

# Editing Calculator items

Editing of data object and operation items on the calculator list is possible in several ways, accessed both via the edit menu of the calculator main window and the item tab.

## Rename Object Alias

The alias of an item on the calculator list can be changed into a convenient mnemonic. All the operation objects that include this item will have their corresponding list of operand(s) updated. The user can change the alias of the operation objects in their corresponding tab page or through the popup from the Edit menu or right click menu.

## Changing Data Object

The working list objects included in the calculator list can be changed to point to a different Working List object. Draging a new object from the working list into the input slot, or editing the slot text directly will change the data object used for this item and all operations dependent on it.

## Copy / Apply Join Settings

The Copy and Apply Join Settings menu items in the Edit menu and the Right Click menu will make a Copy of all the join options set for the visible tab (selected item) and can then Apply them to all selected items on the calculator list. These settings are remembered until another Copy Join Settings operation, and are independent of the regular copy/paste operations on the calculator list.

## Copy / Paste

A data item from the calculator list view can be copied to clipboard and pasted into an input slot or the calculator list itself as a new manifestation of that data object. Calculations cannot be copied at present.

## Select All

Select all command selects all the items within the calculator list view.

## Delete Item

This command allows deleting a selected item within the calculator list view.

## Clear List

Deletes all the contents of the current list view of the calculator. A new default operation is created as the list cannot remain empty.

## Double clicking an item

Double clicking an item of the calculator list will bring the object editor window if the item selected is an working list object. If the item is an operation (constructed at the calculator level), then a double click command

- Will edit the alias of the operation if the calculation has not occurred before or has not been successful
- Or bring the object editor window for the object resulted from this operation if the calculation has occurred and has been successful.

# Selecting Components

Object input slots will display a pulldown button to permit selection of components whenever there is an option to use either the object or a component in an operation. Furthermore, if a vector is not permitted, the pulldown will not permit the object itself to be selected, and the magnitude will be selected as default. The selected component is indicated by the name shown in the slot. Components are also shown in a slightly different colour.

If a component is selected in the input slot to an operation, then the requested component is passed to the operation, while other components can be selected in other slots. Thus the same data object can be dropped into two slots on the same operation and different components selected for the two operands.

If a component is selected in the slot on the tab for a data object itself, then this component is used every time that alias is dropped into a slot. Selection of a component at this data object level propogates down to all operations depending on that object, and can thus be used to repeat a set of operations using on other components for the same object without changing the inputs into each operation input slot.

Note that dropping a new data object from the WL or calculator list into the input slot for a data object on the calculator list will replace the data object with the new data object. This too can be used to propogate data inputs changes through all dependent operations.

Pulldowns will be present to allow access to:

- Xrefs of an object (metadata such as DEPEND_1)
- Components of a vector (if the vector itself is not acceptable for this slot, the magnitude is chosen by default but can be changed via the pulldown).
- Arrays of lower dimensionality (via sum, slice or subset on element indices)
- 'This Object' will be present if the object itself is also an acceptable input for this slot.

# Joining time-tagged objects

Analysis of time-ordered datasets often requires data to be placed onto a common set of time tags prior to further analysis, and for time series data objects this is also essential within the calculator. Since data may come from different sources they must be interpolated or averaged onto a common set of time tags. This matter is critical and complex, and the interested reader may wish to consult Chapter 2 (Time Series Resampling Methods by Harvey and Schwartz) in the ISSI book Analysis Methods for Multi-spacecraft Data published by ESA/ISSI and available in electronic form at the ISSI web-site. Generally, when the target timetags are widely spaced with respect to the original set, simple boxcar averaging (with a boxcar twice as wide as the target timetag spacing) is appropriate. For closely-spaced target timetags, linear interpolation is often as good as more sophisticated techniques. In all cases, gaps in the time series need to be trapped and either filled or entries removed.

The calculator also provides the option joining of data onto regular time tags to permit further analysis by QSAS plugins, some of which demand regularly spaced data points.

Target Time Tags

A single set of target time tags and a time interval (to permit subsetting) are specified for all the objects and operations on the calculator list. This set of target time tags will be used for all inputs that are time tagged. Constants and non-time series data objects are held to be valid at each time tag.

The default time interval is the union of the data intervals of the input data series. This may be changed using the pulldown menu to take the interval from an object dropped into the Interval Object slot. Valid objects are time interval objects from the Time Intervals section of the Working List, or any data object with accompanying time tags (when the interval covered by the time tags will be used).

The default time tags are from the first data object dropped onto the calculator list. This may be changed by dropping any data objet into the Tme Tag Object slot. The Time Tags pulldown menu can also be used to select Create Regular, and a tag spacing specified as a real number of seconds typed into the Spacing slot that replaces the Time Tag Object slot.

Two tick boxes are also provided that modify joining for the whole calculator list:

- Multi-join Before calculation
- Multi-join After calculation

If the Multi-join Before calculation box is ticked, then joining is performed on all the input data objects before any other operations are performed. Gaps are removed or filled where appropriate across all inputs. The output series will all be on the same set of input time tags unless an operation has generated invalid numbers.

The Multi-join After tick box allows all the output data series to be joined onto a common time line after all operations have been performed.

If neither box is ticked, then the join operations are performed for each set of inputs to each calculation as needed.

Note that in all cases, if the operation creates fill value data or invalid numeric values (e.g. NaN from divide by zero) then these data will be removed from the output series as they are placed on the working list if the 'Strip Fill Values' or 'Strip NaN' boxes are ticked on the main window. In this instance output data series can have different time tags from each other.

Joining options that are set on item tabs:

- Join Algorithm
- Ave width (sec)
- Gap Handling
- Gap threshold

The options chosen apply to items selected, and different options may be set for different input objects or groups of objects. If multiple items are selected, then editing the visible tab will also change the settings in the other, hidden, selected tabs.

Note that selecting the Fill Value option for filling gaps may result in data series of different lengths if the 'Strip Fill Values' toggle is set on in the QSAS main window. Objects joined with this gap handling choice may therefore fail future tests on whether the data are joined.

Similar behaviour will result if a zero fill is selected for gap handling if the fill value (held in the Fillval attribute for the object) is also set to zero.

The following figure shows the join tab page.

# Saving and restoring Calculations

The File menu of the calculator window allows the current calculation to be saved as a default file (saveSet.qs_calc) using the Save menu item, or a user named file using the Save As... menu item. If data objects are set for the various operations then these object names will be saved.

The Restore menu item on the File menu will add the set of operations stored in the calculator file to the List view. Selecting Restore will result in a standard file selection window to allow selection of the calculator file to be opened.

The Save with Data and Save with Data As... menu items are equivalent to Save and Save As... except that the data object on the Working List associated with each operation is saved with the calculator file, and restoring one of these files will place the data object on the Working List. In the case that a data object of the same name already exists on the Working List, the restored data object name will be modified (an 'A' will be added until a unique name is found) . In this way the restored calculations are still valid and any pre-existing calculations and data are not destroyed or modified by the restore action.

Restoring a calculation appends the saved operations and input objects without removing any operations currently on the calculator list to assist in assembling chains of operations from previously saved elements. Duplicate alias names will have an 'A' appended in the calculator list.

# Summary

The calculator is used as follows:

1. The user drags and drops the required objects from the working list to the calculator list view
2. New operations can be created by pressing 'New Operation' button
3. Edit each operation tabs to set the operator, operand(s) for the newly created operation
4. To save the output objects onto the working list tick the 'Save to WL as' box
5. Select Join options for each data object, and also for virtual objects if the 'Join after calculation' check box is ticked.
6. The calculator can be started by pressing the 'Do' button. Incomplete operations are ignored (e.g. missing inputs).
7. A float constant can be typed directly in an operand slot.
8. If the calculator has been successful, the resulting objects will be added in the working list of QSAS main window (if the user requires so see(4)).

# Example

A set of QSAS calculations might appear thus...

In this example the operations are:

- Alias d takes the cross product of the electron velocity with the magnetic field joined onto the time tags from the magnetic field.
- Alias a subtracts the magnetic field from itself boxcar averaged over 600 seconds to show fluctuations around the time averaged field.

Note that the magnetic field appears twice on the calculator list as it is joined onto its own time tags in two different ways. The boxcar average produces a smoothed average field, while the linear join does nothing since it is joining onto its own time tags. The remove gaps means that there will be no data point in the output series for any object where a gap is found in any of the input objects. If Join First had not been selected then gaps in the velocity data would be removed from the VxB output, but not the B-<B> output. Note also that the save to working list box has been ticked for the time averaged magnetic field for use later.

To repeat these calculations for different time intervals it is necessary only to drop new data objects into the data items on the calculator list (aliases b, c and e).

This family of calculations may be saved as a named save set using the File->Save As menu item for re-use later.

Last up-dated: October 2008