Template:Dataset Calculator: Difference between revisions

From XMS Wiki
Jump to navigationJump to search
 
(12 intermediate revisions by the same user not shown)
Line 21: Line 21:
The output will be a new dataset on the chosen grid with values and activity according to the expression and chosen datasets.
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====
====Current Location in Toolbox====
Datasets/ Dataset Calculator
Datasets/ Dataset Calculator
<!--
<!--
Line 27: Line 27:
{{Dataset Calculator Table}}
{{Dataset Calculator Table}}
{{Dataset Calculator Table Examples}}-->
{{Dataset Calculator Table Examples}}-->
===Example expressions===                   
===Example Expressions===                   
====Traditional mathematical symbols====
====Traditional Mathematical Symbols====
Includes:  +, -, *, /.  (addition, subtraction, multiplication, division)
Includes:  +, -, *, /.  (addition, subtraction, multiplication, division)
=====Example 1 &ndash; mathematical operation:=====
=====Example 1 &ndash; mathematical operation:=====
Line 43: Line 43:
|            WSE  (new dataset representing the water surface elevation)
|            WSE  (new dataset representing the water surface elevation)
|}
|}
====Trigonometric operations====
====Trigonometric Operations====
Includes: sin, cos, tan, arcsin, arccos, arctan, arctan2, sinh, cosh, tanh, arcsinh, arccosh, arctanh
Includes: sin, cos, tan, arcsin, arccos, arctan, arctan2, sinh, cosh, tanh, arcsinh, arccosh, arctanh
=====Example 2 &ndash; trig function:=====
=====Example 2 &ndash; trig function:=====
Line 50: Line 50:
|  ''Dataset table:''                               
|  ''Dataset table:''                               
|variable name "AMP" representing the amplitude dataset<br>
|variable name "AMP" representing the amplitude dataset<br>
variable name "PHASE" representing the phase dataset
variable name "PHASE" representing the phase dataset
|-
|-
|    ''Mathematical  expression:''         
|    ''Mathematical  expression:''         
Line 59: Line 59:
|}
|}


====Mathematical functions====
====Mathematical Functions====
Includes: log, log10, exp, sqrt, abs
Includes: log, log10, exp, sqrt, abs
=====Example 3 &ndash; square root:======
=====Example 3 &ndash; 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)
| ''Dataset table:''                                
:    Output dataset name:                   FR (new dataset representing the Froude number at the computation location)
|variable name "V" representing the velocity magnitude dataset<br>
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 &ndash; exponent:=====
=====Example 4 &ndash; 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))
| '' Dataset table:''                             
:    Output dataset name:                   Vmag (new dataset representing the velocity magnitude at the computation location)  
| variable name "Vx" representing the velocity in the X direction dataset
====Conditional statements====
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)
Where(bool, number1, number2)
===== Example 5 &ndash; Min, max or conditional:=====
===== Example 5 &ndash; 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)
| ''Dataset table:''                 
:    Output dataset name:                   MaxWSE (new dataset representing the maximum water surface)  
| variable name "WSE1" representing the first water surface dataset<br>
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):=====
=====  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 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:====
{|- border="1"
|-
!
!
!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 Tool|Compare Datasets]]
* [[Filter Dataset Tool|Filter Dataset]]
* [[Map Activity Tool|Map Activity]]


<small>
*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 https://numexpr.readthedocs.io/en/latest/user_guide.html].</small>
<noinclude>[[Category:Toolbox Datasets]]</noinclude>
<noinclude>[[Category:Toolbox Datasets]]</noinclude>

Latest revision as of 14:39, 10 July 2024


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