Derived metrics can be used to compute new values by using an expression based on the value of other metrics. The expression can be used to compute a numeric, a boolean or a string value.
Creating a Derived metric
To add a new Derived metric to a Thing Definition, you should:
- Enter the Computed Data page.
- Select the Thing Definitions tab.
- Select the Thing Definition to edit.
- Press the Add Metric button.
- Select the Derived type and provide the required information.
- Press the Save button and edit the additional information, if needed.
Editing a Derived metric
The configuration of a Derived metric is subdivided into several sections:
General
- Label: the metric label shown within the widget.
- Name: the name of the metric, also used to reference it within the dashboard's templates.
- Description: the text describing the metric.
The description is displayed as a tooltip within the dashboard widgets. - Unit: the unit of measurement (e.g. Kg, °C, pieces, liters...etc.)
- Group: the group the metric belongs to (e.g. Temperatures, System).
- Privatizable by customer: allow the customer to define whether the metric is private or not.
For more details, refer to this Privatizable date article.
Computation
You can configure whether the computation is to be Continuous or Sampled. The Continuous computation takes into account all input values and can generate the same number of output values, while the Sampled computation is just based on the last available value and generates only one output value per sampling period (e.g. 1h, 1d).
Both Sampled and Continuous computations are periodically evaluated at a fixed time interval.
By using the Sample computation, you can reduce the number of consumed DPH, and, in addition, you can reference more input variables than with Continuous computation.
For old metrics with sampling period defined, a warning inform you to choose to clear the sampling period or change the computation to Sampled.
Suppose you have a derived metric that sums two other metrics, here we resume the different behaviors in the case of continuous and sampled (1 hour) computation.
Output = Metric1 + Metric2
The Timestamp column represent the time when the value comes available.
OUTPUT |
||||
---|---|---|---|---|
Timestamp | Metric1 | Metric2 |
Continuous |
Sampled (1h) |
10:00 | 10 | 20 | 30 | 30 |
10:10 | 20 | 20 | 40 | - |
10:20 | 20 | 10 | 30 | - |
10:40 | 20 | 30 | 50 | - |
11:00 | - |
50 (10:40) |
||
11:10 | 15 | 20 | 35 | - |
Note that the Sampled computation is performed every sampling period with a few seconds delay; using the last received values the new value is computed, and stored using the last received timestamp. So, for example, at 11:00, the computation is performed, but the resulting value "50" is stored using the 10:40 timestamp corresponding to the last value of Metric2.
In either case, the computed values might come available with a few seconds delay from the input values. This delay could depend on the complexity of the derivation to be processed for each thing:
- Number of computed metrics.
- Number of DPH input to each computed metric (in case of Continuous evaluation).
- Computed metrics uses as input into other computed metrics, and so on.
Derivation
In the derivation panel, it is possible to select one or more metrics or properties to use within the expression. In addition, you can refer to the previous value calculated for the metric.
Note that, the number of selectable metrics depends on the computation policy. In case of Continuous computation, you can select up to 3 metrics.
Once the metrics/properties have been selected, it is possible to configure the derivation expression, here are some examples:
// total weight in kg
(unitWeight * quantity)/1000
// milliseconds to hour
#floor(time / 3600000)
// substring
alertCode.#substring(3,6)
// energy increment in kWh
(energy / 1000) - previousValue
By pressing the Add Condition button, it is possible to add multiple result conditions to implement the IF, ELSE, OTHERWISE pattern.
Previous Input Metric Value
When referring to a metric, you can access not only its current value but also its previous value. In this way you can use the difference of consecutive values into your derivation logic.
outputPieces - outputPieces.PREVIOUS
Null Result
- IF metric1 > 100 → left the result empty to do nothing
- ELSE RETURN (metric1 + metric2) → save new value
Functions
The expression language used to define Derived Metric expressions is based on the following operators.
OPERATOR |
NOTATION |
SAMPLE |
---|---|---|
Mathematical |
+ - * / % ^ |
(x + y^2)/4 |
Logical |
or and true/false |
x==y && (b==true || b==c) |
Relational |
= != < ⇐ > > |
a != b |
Elvis |
Ternary operator |
condition ? foo : bar |
MATH |
DESCRIPTION |
SAMPLE |
---|---|---|
cos |
Returns the trigonometric cosine of an angle, in radians. |
#cos(x) |
sen |
Returns the trigonometric sine of an angle, in radians. |
#sen(x) |
abs |
Returns the absolute value of a numeric value. |
#abs(x) |
sqrt |
Returns the rounded positive square root of a numeric value. |
#sqrt(x) |
pi |
The PI value (3.14159…). |
#pi |
ceil |
Returns the smallest integer value greater than or equal to the float argument. |
#ceil(x) |
floor |
Returns the largest integer value that is less than or equal to the float argument. |
#floor(x) |
log |
Returns the natural logarithm (base e) of the argument. |
#log(x) |
log10 |
Returns the base 10 logarithm of the argument. |
#log(x) |
max |
Returns the greater of two values. |
#max(x, y) |
min |
Returns the smallest of two values. |
#min(x, y) |
pow |
Returns the value of the first argument raised to the power of the second argument. |
#pow(x, exp) |
CONVERSION |
DESCRIPTION |
SAMPLE |
parseInt |
Converts the string argument to integer using the given radix (optional). |
#parseInt('12') or #parseInt('BF123', 16) |
intToString |
Converts an integer to string using a radix. |
#intToString(x, 16) |
parseFloat |
Converts the string argument to float using the given radix (optional). |
#parseFloat('12') or #parseFloat('BF123', 16) |
floatToString |
Converts a float to string using a radix. |
#floatToString(x, 16) |
toString |
Converts the source value to string. |
var.#toString() |
STRING |
DESCRIPTION |
SAMPLE |
substring |
Returns a substring considering the start (inclusive) and end (exclusive) zero based indexes. |
str.#substring(startIndex) or str.#substring(startIndex, endIndex) |
length |
Returns the length of the string. |
str.#length() |
charAt |
Returns the character at the specified index. |
str.#charAt(index) |
indexOf |
Returns the index (zero-based) of the first occurrence of the argument string. |
str.#indexOf('foo') |
lastIndexOf |
Returns the index (zero-based) of the last occurrence of the argument string. |
str.#lastIndexOf('foo') |
split |
Returns the arrays of tokens splitting by the argument string. |
str.#split(',') |
upperCase |
Converts the source string to upper-case. |
str.#toUpperCase() |
lowerCase |
Converts the source string to lower case. |
str.#toLowerCase() |
Data
In case of numeric metrics, the Data Type allows you to define whether the metric values are DISCRETE or CONTINUOUS, and then you can also define Dictionary or Thresholds.
Comments
0 comments
Please sign in to leave a comment.