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.

For the virtual signal creation procedure read the linked article, for the rule creation procedure read this other one.

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

2.1. Clarifications

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

kf(percentile(x0,25),14)

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)

kf(gradient(x0),f)

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 can follow two ways.

6.1 Eval syntax

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.

6.2 Databoom Starter Pack temporal signals

In Databoom Starter Pack device there are some time signals that can be used to calculate virtual signals on hourly basis.

If Databoom Starter Pack is not available in devices list, check device subscription in public devices list (Devices -> Public in side menu)

It's therefore possible to create a rule that uses the temporal signals as variables.

As an example, consider signals year UTC with the variable x0 and hours UTC with variable y0. A formula like:

x0 and y0>5

is verified every morning at 6UTC. Alarm shuts down when hour value turns back to 0, at midnight.

It's important to consider timezone while creating time slots, hours UTC logs the hour value in UTC timezone.

7. Rules on bits words

In some contexts, for example the industrial one, it can be useful to check the value of a specific bit inside a word of bits.

It is possible to check if a bit is positive with the corresponding power of 2:

(x0 & 1) == 1

(x0 & 2) == 2

(x0 & 4) == 4

(x0 & 8) == 8

(x0 & 16) == 16

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

kf(wma(abs(x0*y0*z0)),12)

9. F.A.Q.

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:

kf(ma(x0+y0),12)

and

kf(ema(x0+y0),12)

Finally we can create a third virtual signal with the two virtual signals v1 and v2 as input and set the formula:

v1 + v2

Virtual signals and rules syntax formulas