Template:Dataset Calculator
Dataset Calculator
The Dataset Calculator tool will perform calculations on one or more dataset data and activity. The tool will produce a new dataset with the resulting values and activity of those datasets according to the provided mathematical expression.
It should be noted that datasets at different locations (point vs. cell) cannot be used in the same expression.
Input Parameters
- Grid source selection – Select the geometry on which the dataset calculation will be performed. The geometry can be a 2D mesh, scatter set, grid or UGrid. The cells or points in the geometry define the locations where data from the dataset exists and the locations for the calculations specified in the tool.
- Data location selection – Determines the location of the calculations in the geometry. 2D meshes and scatter sets only support point datasets. UGrids supports both point and cell datasets. Cartesian grids can be of one type or the other.
- "Cells" – Calculations will be performed on the cell values of the geometry.
- "Points" – Calculations with be performed on the point values of the geometry.
- Dataset table – Can be populated with the datasets from the select Grid source selection. This table allows selecting which datasets are to be used and specify a variable name for each that will appear in the expression. The default variable names follow the pattern of d1, d2, etc., but user specified names can be specified as well. Not all datasets selected in the table need to be used in the expression.
- Dataset – The selected dataset.
- Variable Name – The name to be used to refer to the chosen dataset within the provided expression.
- Time Step – The chosen time step from which to use data from this dataset. Or select all time steps to use all values within this dataset.
- Mathematical expression – The equation or expression that will be evaluated at each location in the dataset. Parentheses can be used in the expression as in mathematical notation.
Output Parameters
- Output Dataset Name – the name of the new dataset to fill with the resulting values from the expression.
The output will be a new dataset on the chosen grid with values and activity according to the expression and chosen datasets.
Current Location in Toolbox
Datasets/ Dataset Calculator
Example Expressions
Traditional Mathematical Symbols
Includes: +, -, *, /. (addition, subtraction, multiplication, division)
Example 1 – mathematical operation:
| Dataset table: |
variable name "D" representing the water depth dataset |
| Mathematical expression: | D + Z |
| Output dataset name: | WSE (new dataset representing the water surface elevation) |
Trigonometric Operations
Includes: sin, cos, tan, arcsin, arccos, arctan, arctan2, sinh, cosh, tanh, arcsinh, arccosh, arctanh
Example 2 – trig function:
| Dataset table: | variable name "AMP" representing the amplitude dataset variable name "PHASE" representing the phase dataset |
| Mathematical expression: | AMP * sin( PHASE) |
| Output dataset name: | WSE (new dataset representing the water surface elevation) |
Mathematical Functions
Includes: log, log10, exp, sqrt, abs
Example 3 – square root:
| Dataset table: | variable name "V" representing the velocity magnitude dataset variable name "D" representing the water depth dataset |
| Mathematical expression: | V/sqrt(32.2 * D) |
| Output dataset name: | FR (new dataset representing the Froude number at the computation location) |
Example 4 – exponent:
| Dataset table: | variable name "Vx" representing the velocity in the X direction dataset
variable name "Vy" representing the velocity in the Y direction dataset |
| Mathematical expression: | sqrt(exp(Vx, 2) + exp(Vy, 2)) |
| Output dataset name: | Vmag (new dataset representing the velocity magnitude at the computation location) |
Conditional Statements
Where(bool, number1, number2)
Example 5 – Min, max or conditional:
| Dataset table: | variable name "WSE1" representing the first water surface dataset variable name "WSE2" representing the second water surface dataset |
| Mathematical expression: | where(WSE1 > WSE2, WSE1, WSE2) |
| Output dataset name: | MaxWSE (new dataset representing the maximum water surface) |
Example 6 - truncation (nested conditional):
| Dataset table: | variable name "SIZE" representing the nodal spacing (size) dataset |
| Mathematical expression: | where(SIZE < 20, 20, where(size > 50, 50, SIZE) |
| Output dataset name: | TRUNCSIZE (new dataset representing a truncated size dataset) |
Dataset Activity
One of the complicating factors that can make working with datasets confusing is the fact that individual locations can be inactive (no value) for a given dataset, or a timestep in a given dataset. This activity can be specified in multiple ways including:
- no activity specification: in this case, all locations are assumed to have a valid value.
- cell activity mask - in this case there is an additional boolean value for each cell in the dataset indicating whether this cell has a valid value. Note: this can apply to both point and cell based datasets.
- point activity mask - in this case there is an additional boolean value for each point in the dataset indicating whether this point has a valid value.
- null value specified at the location - in this case the dataset has a specific value (i.e. -999, -999999, etc) which indicates that this location has no valid value exists at this location. It is a special type of an activity mask.
When a dataset operation is performed on multiple datasets, the resulting dataset has activity specified for each location in the dataset. The type of activity depends on the activity classifications for the arguments/parameters in the expression. The following table describes the resulting activity for the new dataset.
- If no dataset being used in a calculation has activity, the resulting dataset will also not have activity.
- In calculations with multiple datasets with one timestep selected, the resulting time step will be 0.0.
- If there is a combination of activity on cells and points between the datasets being used in a calculation, before performing calculations for activity, the calculator will find the point activity from the given cell activity and use that in the activity calculations. See example #2 in the table below.
Activity Examples:
| Dataset 1 | Dataset 2 | Result | ||
|---|---|---|---|---|
| Example | Value location | Activity | Activity | Activity |
| 1 | cells | none specified | none specified | none specified |
| 2 | cells | cell activity | cell activity | cell activity |
| 3 | cells | cell activity | none specified | cell activity |
| 4 | points | none specified | none specified | none specified |
| 5 | points | point activity | point activity | point activity |
| 6 | points | cell activity | none specified | cell activity |
| 7 | points | cell activity | cell activity | cell activity |
| 8 | points | point activity | none specified | point activity |
| 9 | points | cell activity | point activity | point activity |
Transient Datasets
Transient datasets are compound datasets made of datasets for multiple values of time. These are referred to as time steps. When adding a transient dataset to an expression the use can choose a single time step from that dataset, or set a flag to evaluate the expression for "all times". In this case, the expression is evaluated separately for each time step in the dataset.
- If multiple transient datasets are included in a single expression using the "all time steps" option, they must have matching (identical) time steps.
- If single time step datasets are included in an expression that uses one or more "all time steps" arguments, the specified single time step is used in the evaluation of the expression for each time step in the "all time steps" arguments.
Related Tools
- This tool makes use of the NumExpr (numerical expressions) library from NumPy. Documentation for this package can be found at https://numexpr.readthedocs.io/en/latest/user_guide.html.
