Doing Calculations with Leaves
The data in the leaf nodes can be manipulated via Python commands by using the calculate utility. To launch it, simply go to “Datasets → Calculate…” You will then be presented with the something similar to the following window
The three key fields are the "Statements," the "Expression," and the "Results table."
The statements field is where you place the bulk of your instructions.
According to the tool tip, this is a "[s]et of python statements that
will be executed before the expression is evaluated. This can be used to
import additional modules or do preliminary calculations to simplify the
expression." These statements are executed and the resultant global
namespace is then used to execute the given expression. For reference,
from numpy import * is executed in the namespace prior to the
statements to potentially simplify your expressions.
The expression field contains a single logical line of Python code that
returns a PyTables array, a NumPy array, a list, a tuple, or a scalar.
The result of this expression is then placed in a table named using
"Results table" (see below for more details). The values of the results
must not be None, Unicode (str), or Object. This is an
underlying restriction from PyTables. If you do return one of these
types, you will get an error saying so, and the result table name you
used will be invisibly bound to the targeted group for the remainder of
the session. It is not truly added to your HDF5 file; however, you will
not be able to reuse that name until you close and reopen ViTables.
You can reference a dataset (not a file or a group) from an open file in
the expression using the path to the dataset prepended with '$'. If the
dataset 'mydata' is in the currently selected group, you can use the
relative path '$mydata' to reference it. Otherwise, you must give the
full path to the dataset '$filename.h5.group.mydata'. This replacement
is only done in the expression and not in the statements. This is how
you pass datasets to functions defined in the statements. You can use
array slicing to pass in a portion of the dataset (i.e
$example.h5.group.mydata[0,:] works).
The results table is the full path to the destination for the result of
the expression. The path may be relative to the currently selected
group as in the expression field, or it can be a full path. The only
difference is that it is not prepended by '$'. For example, to create a
temporary group output in the "Query results" group, simply type
Query group.output into the results table field. The Query group
points to a temporary file that is released at the end of the session.
If you wish to save the results, you can simply place it back into your
main HDF5 file using the standard tools of ViTables. To prevent
accidental data corruption, the results table must not exist.
If you have an exceptionally useful or complex expression, you can save it between sessions of ViTables. This is done by simply clicking the save button and assigning a name to the expression. The expressions are stored in system specific locations and formats. To find these, simply look for a path with some variation on the capitalization of ViTables in that location. However, the easiest way to share the expressions is to place as much as possible into a function that can be imported in the statements field and simply called from the expression field. This removes the hassle of dealing with the system specific storage format.
- One way to improve the response would be to parse the statements and expression for valid syntax. This would provide the user more direct feed back. This would also allow to check for a single logical line in the expression field.
- The calculation window could be made a top level item and to allow the user keep is open and do more manipulations. This would prevent having to constantly open the window after every use.