Databoom lets the user create virtual signals starting from a signals list (that can be virtual signals themself). For each created virtual signal you need to write a transformation formula that takes a signals list as input and returns a new signal.
The same procedure applies to the rules, where the inserted formula represents a condition that when is verified generates an alarm.
Once the input signals have been added you can proceed writing down the formula.
Syntax exclusively applies to formulas, it's NOT possible to use it in email/sms fields in the rule view.
1. Math operators
Basic arithmetic operators (sum, subtratction, multiplication, division)
+ - * /
Complex arithmetic operators (module, exponentiation, factorial)
% ^ !
2. Mathematical formulas
- abs(x) - Absolute value
- cbrt(x) - Cubic root
- ceil(x) - Round numbers up to the nearest integer
- cube(x) - Cube x^3
- exp(x) - e^x
- floor(x) - Round a number downward to its nearest integer
- gcd(a, b) - Calculates the greatest common divisor between 2 numbers
- hypot(a, b, …) - Hypotenuse among a values list
- lcm(a, b) - Least common multiple
- log(x , base) - Logarithm of a number (e base or [base])
- log10(x) - Logarithm to base 10
- nthRoot(a, radice) n-th root (default 2)
- sqrt(x) Square root
All the operators and the mathematical operations can be used in a combined way and cascade.
Example: We have 2 input signals x0 and y0, we want to create a signal that represents the square root of the sum between x0 and the logarithm to base 10 of the ratio x0 to y0
sqrt(x0 + log10(x0 / y0))
3. Logical operators
Signals formulas may contain logical operators that can change the behavior of the signal depending on the input.
3.1 Available operators
- and AND operator, returns true if the evaluated expressions are true, false otherwise
- not NOT operator, returns false if the evaluated espression is true and vice versa
- or OR operator, returns true if at least an expression is verified, false otherwise
- xor XOR operator, returns true if the evaluated expressions don't return the same result (true or false)
- ? : Conditional expression, evaluates a condition, if it's true executes an expression, if it's false executes another one. The structure to follow is Condition ? Expression when true : Expression when false (See Examples)
- == Equality, returns true if expressions are equal
- != Inequality, returns true if expressions aren't equal
- < Strictly minor, returns true if the operator on the left is strictly minor of the operator on the right
- > Strictly greater, returns true if the operator on the left is strictly greater than thee operator on the right
- <= Minor, returns true if the operator on the left is minor or equal to the operator on the right
- >= Greater, returns true if the operator on the left is greater or equal to the operator on the right
3.2 Special operator undefined
undefined operator can be used when you want to omit a series of values from the source signals. This operator allows to discard this series of values.
Example: We have 2 input signals x0 and y0, we want the output signal to be the sum of the input values, we also want the values which sum is lower than 7 to be discarded
x0 + y0 >= 7 ? x0 + y0 : undefined
This formula uses the logical operator >= to validate the 'greater than 7' condition, in addition it uses the conditional expression ?: to change the result depending on the input.
The formula can be literally read as: if (x0 + y0 >=0) then return the sum x0 + y0 otherwise drop these values (undefined).
4. Special variables
While creating a formula, a variable is assigned to each signal so it can be easily referred into the formula, variables tipically use the format x0 y0 z0 t0. These variables represent the exact input value. A set of extensions is available to use value calculated on the entire points series under exam.
- mean_[variable] - Returns the mean value of the signal
- max_[variable] - Returns the maximum value of the signal
- min_[variable] - Returns the minimum value of the signal
- last_[variable] - Returns the last recorded value of the signal
- max_p_[variable] - Returns the maximum value of the bar under exam (if the granularity isn't All values)
- min_p_[variabile] - Returns the minimum value of the bar under exam (if the granularity isn't All values)
- full_[variable] - Returns signal full value in case of counter signal (only if it is a real signal that sends the total value from time to time)
The last_w_[variable] allows to refer the last available value in the requested range of the signal used as variable.
min_partial_x0, max_partial_x0, sum_partial_x0, mean_partial_x0 allow, respectively, to refer the minumum, the maximum, the total sum or average at the reception of each value. Each value consists of the aggregation of the previous values.
Example: We have 2 input signals x0 and y0, we want to create an output signal that represents the sum of the two input signals divided by the sum of the mean values
(x0 + y0) / (mean_x0 / mean_y0)
5. Functions with period
All the functions examined up to now work in a punctual manner, which means their output depends only on the value under exam and doesn't have any reference with the previous values in the series. Databoom offers a set of functions that work with a sliding window of n periods which can extrapolate a statistical data dependent from the values in the window.
- kf(percentile(f(x), rank),periodo) - Calculates n-quantile of f(x)
- kf(ma(f(x), rank),periodo) - Calculates the linear average of f(x)
- kf(wma(f(x), rank),periodo) - Calculates the weighted average of f(x)
- kf(ema(f(x), rank),periodo) - Calculates the exponential average of f(x)
- kf(ssd(f(x), rank),periodo) - Calculates the standard deviation of f(x)
- kf(gradient(f(x), rank),periodo) - Calculates the gradient of f(x)
- kf(ago(f(x), rank),periodo) - Calculates the value of f(x) in the period [period]
5.1 Notes on the period
The period indicates how wide the sliding window is, which represents the quantity of elements of the series considered in the calculation of the value. If you want to use all the elements of the series use "f" as a period.
Example: We have an input signale x0, we want to extract a signal that represents the 25° quantile of the signal on a sliding window of 14 values
Example: We have an input signale x0, we want to extract a constant signal that represents the gradient of all the series under exam (window wide as all the series)
6. Scheduled execution of Rules on a temporal basis
Rules are normally evaluated when one of the referred devices or signals updates, the system evaluates the rule with the new received values. If you need to evaluate a rule at regular fixed intervals, as for example a rule that sends a daily report, you need to use a specific syntax that declares a time interval in which the rule has to be evaluated. This is possible thanks to the special operator eval.
Example: Evaluating a rule every day at 10:15 (+/- 15min)
eval(italy_date = moment.tz("Europe/Rome"); if(italy_date.hour()==10 && italy_date.minute()<=30) result=1; else result=0;)
Example: Evaluating a rule every Monday at 8:00
eval(italy_date = moment.tz("Europe/Rome"); if(italy_date.hour()==8 && italy_date.minute()<=15 && italy_date.day()==1) result=1; else result=0;)
It is important to always set a time interval rather than an exact date because the process that analyzes the rules is queue based so the evaluation time varies depending on the traffic and could miss the specific date. We recommend to use at least a 15 minutes time span.
7. Use of Apply to all data option (Virtual signals)
Databoom allows to visualize data with different granularities, as for example it is possible to aggregate per hour an input signal sampled every 5 minutes, this is accomplished (with no counter signals) by taking all the values of the hour and madiating them resulting in a single value per hour.
This operation is the first executed in the virtual signal generation flow, which means that the formula is applied on the already aggregated signal. This mode is the most appropriate for the most cases but sometimes you may need to apply the formula before creating the aggregation.
For example, if we have an input signal between 1 and 100 and we want a signal between 0 and 1 as output using the following formula:
x0 > 30 ? 1 : 0
this has to be always calculated on the original signal, not on the elaborated one with different granularity. In these cases you can use the Apply to all data option, by selecting this option we assure that the formula is the first evaluated thing during the visualization process of the virtual signal.
8. Practical examples
8.1 We have 2 input signals x0 y0, we want to extract a signal representing the average of the input signals weighted on the difference between max and min of the single signal
x0*((max_x0 - min_x0)/((max_x0 - min_x0) + (max_y0 - min_y0)) + y0*((max_y0 - min_y0)/((max_x0 - min_x0) + (max_y0 - min_y0))
8.2 We have 3 input signals x0 y0 z0, we wanto to extract a signal representing th weighted average of the absolute product of the 3 signals with a sliding window of 12 periods
Q. Is it possible to have more functions with period in the same virtual signal?
No, at the moment a virtual signal can only contain a single function with period, however, it's still possible to divide the virtual signal in more signals and compose it as derivation of parts.
Example: We have 2 input signals x0 and y0, we want to calculate the sum of the linear average and the exponential average of the signals, with 12 periods
kf(ma(x0+y0),12) + kf(ema(x0+y0),12)
This formula isn't valid because it contains more functions with periods. The solution to this problem is to create 2 virtual signals v1 and v2 with the same inputs x0 and y0, respectively with formulas:
Finally we can create a third virtual signal with the two virtual signals v1 and v2 as input and set the formula:
v1 + v2