The formula functionality allows you to create calculated tags using simple mathematics and functions. They can be used to define derived quantities, such as differential pressures, temperature deltas, total flows, KPIs, etc.
A more general overview on Tags can be found here.
The formula tags can be found in the tag builder menu.
Formula Submenu
Formula-field: In this field you can enter your desired formula using variables. Any entered variable will show up as a "Map Variable"-field in the section below.
Next to variables the field also accepts pre-defined functions you can use, see "Functions" below for more details. Autocompletion of functions are also supported. Pressing the "tab"-key on your keyboard will fill out the selected function.
Note: You can use any variable-name if it has not been assigned to a predefined function.
The formula field supports the formating of your formula like a code editor. This allows you to indent and even add comments to your formula.
Clicking a variable, function, will also highlight other occurrences inside the formula. For parentheses, only the matching parenthesis is highlighted.
Color highlights are as followed:
* variable: blue
* comment: green
* function: purple
* parentheses: alternating coloration. Colored red if a parenthesis is missing.
Note: decimals should be entered with a point (.) separator, a comma (,) is already reserved for the formula-functions.
Note: Scientific notation using the E-notation is supported if there is no space included between the coefficient and exponent. When a space is included, the letter E will be interpreted as a variable.
Map Variable: As soon as a variable is entered in the formula-field, you can map the variable to any existing tag in TrendMiner. The mapping-field allows you to quickly select a tag from your active list or to search for any tag.
Currently a maximum of 10 variables can be mapped.
Timeshifts: This checkbox allows you to include timeshifts for any mapped value. The default behaviour of the formula computation is to take values at the same timestamp for all mapped values.
Formula Functions
You can enter certain keywords in the formula-field that act as a predefined function. Click the "?” spot to open the documentation of the built-in functions. Here you can see all the available functions and learn how to use them.
From the function details documentation, you can automatically add the function to the formula field by clicking the syntax example.
When adding a function from the documentation, the input parameters and expressions for the function are included as a placeholder. These placeholders can be replaced by directly typing in the desired info and pressing "tab" via the keyboard to switch between the different parameters and expressions.
Note: For functions that accept two or more inputs, only the first two parameters and expressions placeholder are added. For example: the max () function can accept up to 10 different inputs, but only two placeholders will be shown.
Example 1: For this example, you want to return a different calculation depending on the temperature. You want to return the measurement with a correction-factor of 0.789 if the temperature is below 30 degC and a factor of 1.345 when the temperature is above. For this case you could make use of the "if" function.
From the help-menu you can see that the syntax for the "if" function is:
if(condition,value_if_true,value_if_false)
Here we have to define our condition (temperature above 30 degC) and what it should return if this condition is true (factor 1.345) or false (factor 0.789). The formula we need to enter would become:
if(temp>30, 1.345 * tagA, 0.789 * tagA)
Using this formula we could then map the temperature-measurement to the variable "temp" and the measurement we want to correct for to "tagA".
Example 2: In this example, you want to calculate a sum if at least 1 out of 3 valves is open. If all of them are closed, we want to display 0. We will use a combination of an "if" and "or" function to accomplish this.
From the help-menu you can see that the syntax for the "or"-function is:
or(expression1,expression2,…,expression10)
Note that the "or"-function returns TRUE if one of the expressions is evaluated as true. This is what we can feed directly into the "if" function as condition:
if(or(valve1="open", valve2="open", valve3=1), A+B, 0)
This formula will return a value of zero if all valves are closed and returns the calculation of the tags mapped to "A+B" if at least one of the valves is open.
Formula Output
Output of a formula tag is always an analog (linearly interpolated) tag.
Tag Type & Input conversions
Discrete, Digital and Sting tags will first be converted to linear analog values when used in mathematical operations.
Computation
The computation of the formula tags is done on the basis of all existing indexation points of the mapped variables. An interpolated value between two points is used when no indexation point exists for other mapped variables at that specific timestamp.
When looking at smaller time windows (smaller than 300 times the index resolution), TrendMiner directly fetches data from the historian instead of using indexed values. In this scenario an ad hoc calculation is made based on the visualized data instead of the indexed values, which might be more fine-grained than the indexed values.
Note: Other TrendMiner functionalities always use the stored index values of the formula tags for further computations.
Restrictions
The general restrictions as mentioned in the Tag Builder overview document are applicable to formula tags.
Variables
A maximum of 10 variables can be included for mapping of each formula.
Input and Output
- Discrete, Digital and Sting tags will first be converted to linear analog values when used in mathematical operations.
- Output of a formula tag is always an analog (linear interpolated) tag.