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 variable name "Z" representing the ground elevation 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

• Compare Datasets
• Filter Dataset
• Map Activity

• 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.