Databoom permette di creare segnali virtuali a partite da una lista di segnali (che possono essere virtuali anch'essi), per ogni segnale virtuale creato è necessario inserire una formula di trasformazione che dato in ingresso una lista di segnali restituisce un nuovo segnale.

La stessa procedura vale anche per le regole, dove la formula inserita rappresenta una condizione che, se verificata, genera un allarme.

Per la procedura di inserimento di un segnale virtuale, rimandiamo a questo articolo mentre per la creazione delle regole è possibile fare riferimento all'apposita guida.

Una volta inseriti i segnali di input è possibile passare alla scrittura della formula.

La sintassi è utilizzabile esclusivamente nelle formule, NON è possibile applicarla alla stesura delle email/sms inviati al verificarsi di allarmi.

1. Operatori matematici

Operatori di aritmetica elementare (somma, sottrazione, moltiplicazione, divisione)

 + - * /

Operatori aritmetici complessi (modulo, potenza, fattoriale)

% ^ !

2. Funzioni matematiche

abs(x) - Valore Assoluto
cbrt(x) - Radice Cubica
ceil(x) - Arrotondamento per eccesso
cube(x) - Cubo x^3
exp(x) - e^x
floor(x) - Arrotondamento per difetto
gcd(a, b) - Massimo comun divisore fra 2 numeri
hypot(a, b, …) - Ipotenusa tra lista di valori
lcm(a, b) - Minimo comun multiplo fra 2 numeri
log(x , base) - Logaritmo di un numero (base e o [base])
log10(x) - Logaritmo base 10
nthRoot(a, radice) Calcola l'ennesima radice (default 2)
sqrt(x) Radice quadrata

2.1 Precisazioni

Tutti gli operatori e le operazioni matematiche possono essere usati in maniera combinata ed a cascata.

Esempio: Abbiamo in ingresso 2 segnali x0 e y0, vogliamo creare un segnale che sia la radice quadrata della somma tra x0 e il logartimo base 10 del rapporto tra x0 e y0

sqrt(x0 + log10(x0 / y0))

3. Operatori logici

Le formule dei segnali possono contenere anche operatori logici in grado di modificare il comportamento del segnale a seconda dell'input.

3.1 Operatori disponibili

and Operatore AND, ritorna vero se entrambe le espressioni sono vere altrimenti falso
not Operatore NOT di negazione, ritorna false se l'espressione è vera e vice versa
or Operatore OR, ritorna vero se almeno una delle espressioni è vera, altrimenti falso
xor Operatore XOR, ritorna vero se le espressioni non ritornano lo stesso risultato(Vero o Falso)
? : Espressione di condizione, valuta una condizione e se è vera esegue un'operazione altrimenti ne esegue un'altra. La struttura da seguire è Condizione ? Espressione per vero : Espressione per falso (Vedi Esempi)
== Condizione di uguaglianza, ritorna vero se le espressioni sono uguali
!= Condizione di diseguaglianza, ritorna vero se le espressioni non sono uguali
< Condizioni di strettamente minore, ritorna vero se l'operatore di sinistra è strettamente minore di quello di destra
> Condizione di strettamente maggiore, ritorna vero se l'operatore di sinistra è strettamente maggiore di quello di destra
<= Condizioni di minore, ritorna vero se l'operatore di sinistra è minore od uguale a quello di destra
>= Condizione di maggiore, ritorna vero se l'operatore di sinistra è maggiore od uguale a quello di destra

3.2 Operatore speciale undefined

L'operatore undefined è utile quando si vuole scartare una serie di valori presenti nei segnali originali, questo operatore fa in modo che la serie di valori in esame venga scartata.

Esempio: Abbiamo in ingresso 2 segnali x0 e y0, vogliamo che il segnale in uscita sia la somma dei valori in entrata, vogliamo anche però che non vengano riportati quei valori la cui somma è minore di 7

x0 + y0 >= 7 ? x0 + y0 : undefined

Questa formula usa l'operatore logico >= per validare la proprietà maggiore di 7, inoltre usa l'espressione di condizione ?: per variare il risultato in funzione dell'input.

Letteralmente andrebbe letta come: se (x0 + y0 >=0) allora somma x0 + y0 altrimenti salta questi valori (undefined).

4. Variabili speciali

Quando si crea una formula, ad ogni segnali di ingresso viene assegnata una variabile riconoscitiva che ci permette di utilizzare il segnale nelle formule, tipicamente queste variabili hanno un formato del tipo x0 y0 z0 t0. Queste variabili indicano il valore esatto in ingresso. Sono presenti delle estensioni che permettono di utilizzare altri valori calcolati su tutta la serie di punti in esame.

mean_[variabile] - Restituisce il valore medio del segnale
max_[variabile] - Restituisce il valore massimo del segnale
min_[variabile] - Restituisce il valore minimo del segnale
last_[variabile] - Restituisce l'ultimo valore registrato del segnale
max_p_[variabile] - Restituisce il valore massimo della barra in esame (se il segnale ha una granularità diversa da Tutti i valori)
min_p_[variabile] - Restituisce il valore massimo della barra in esame (se il segnale ha una granularità diversa da Tutti i valori)
full_[variabile] - Restituisce il totale accumulato in caso di segnali contatori reali (segnali che di volta in volta mandano il valore totale)

La variabile last_w_[variabile] permette invece di referenziare l'ultimo valore disponibile nell'intervallo richiesto del segnale passato come variabile.

min_partial_x0, max_partial_x0, sum_partial_x0 e mean_partial_x0 permettono rispettivamente di fare riferimento al minimo, al massimo, alla somma o la media totali alla ricezione di ogni valore. Ogni valore consiste quindi nell'aggregazione di tutti i valori precedenti.

Esempio: Abbiamo in ingresso 2 segnali x0 e y0, vogliamo creare un segnale in uscita che sia la somma dei 2 in entrata diviso la somma dei valori medi

(x0 + y0) / (mean_x0 / mean_y0)

5. Funzioni con periodo

Tutte le funzioni visto fin'ora lavorano in maniera puntuale, ossia il loro output dipende solo dal valore in esame e non ha nessun riferimento con i valori precedenti della serie. Databoom offre però tutta una serie di funzioni che lavorano con una finestra mobile di n periodi in grado di estrapolare un dato statistico dipendente dai valori contenuti nella finestra mobile.

kf(percentile(f(x), rank),periodo) - Calcola l'ennesimo percentile di f(x)
kf(ma(f(x), rank),periodo) - Calcola la media lineare di f(x)
kf(wma(f(x), rank),periodo) - Calcola la media pesata di f(x)
kf(ema(f(x), rank),periodo) - Calcola la media esponenziale di f(x)
kf(ssd(f(x), rank),periodo) - Calcola la deviazione standard di f(x)
kf(gradient(f(x), rank),periodo) - Calcola il gradiente di f(x)
kf(ago(f(x), rank),periodo) - Calcola il valore di f(x) al periodo [periodo]

5.1 Note sul periodo

Il periodo indica quanto lunga è la finestra mobile di calcolo ossia quanti elementi della serie vengono presi in considerazione per il calcolo del valore, qualora si vogliano utilizzare tutti gli elementi della serie utilizzare come periodo "f".

Esempio: Abbiamo in ingresso un segnale x0, vogliamo estrarre un segnale che rappresenti il 25° percentile del segnale su una finestra mobile di 14 valori

kf(percentile(x0,25),14)

Esempio: Abbiamo in ingresso un segnale x0, vogliamo estrarre un segnale costante che rappresenti il gradiente di tutta la serie in esame (finestra fissa lunga quanto tutta la serie)

kf(gradient(x0),f)

6. Esecuzione programmata di Regole su base temporale

La valutazione delle regole normalmente avviene in base ai dati in ingresso, quando uno dei segnali/device che è collegato alla regola riceve un aggiornamento il sistema valuta la regola sui dati appena inseriti.

Qualora si volessero creare delle regole da valutare a intervalli fissi, come ad esempio una regola che imposta l'invio di un report giornaliero è possibile procedere in due modi.

6.1 Sintassi eval

Esempio: Valutare una regola ogni giorno alle 10:15 (+/- 15min)

eval(italy_date = moment.tz("Europe/Rome"); if(italy_date.hour()==10 && italy_date.minute()<=30) result=1; else result=0;)

Esempio: Valutare una regola ogni lunedì alle 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;)

E' importante sempre fissare un range di tempo e non una data esatta perché il processo che analizza le regole è basato su code, quindi a seconda del traffico è possibile che ci siano dei lievi ritardi nella valutazione della stessa, per questo consigliamo di mantenere uno span di un quarto d'ora.

6.2 Segnali temporali di Databoom Starter Pack

Nel dispositivo pubblico Databoom Starter Pack sono presenti dei segnali che possono essere utilizzati per il calcolo di regole su base temporale.

Se il dispositivo Databoom Starter Pack non è disponibile nella lista di dispositivi, verificare di essere sottoscritti nella lista dei dispositivi pubblici (menù laterale Dispositivi -> Pubblici)

E' quindi possibile utilizzare i segnali temporali nella propria formula, in modo da definire un intervallo di esecuzione.

Si considerino, ad esempio, i segnali year UTC con variabile x0 e il segnale hours UTC con variabile y0. Una formula del tipo

x0 and y0>5

è verificata ogni mattina alle 6UTC. L'allarme si disattiverà non appena il valore di hours UTC scenderà al di sotto di 6, ovvero a mezzanotte 0UTC.

Nella stesura delle fasce orarie è importante tenere in considerazione che il segnale hours UTC registra i valori delle ore nel fuso orario UTC. Se si vuole fare riferimento alle ore 08:00 in UTC+2, si deve fare riferimento al valore 6 del segnale.

7. Regole su word di bit

In alcuni contesti, ad esempio quello industriale, può essere utile verificare il valore di un particolare bit all'interno di una word.

E' possibile controllare se un bit è valorizzato utilizzando la potenza di 2 corrispondente:

(x0 & 1) == 1

(x0 & 2) == 2

(x0 & 4) == 4

(x0 & 8) == 8

(x0 & 16) == 16

8. Esempi Pratici

8.1 Abbiamo in ingresso 2 segnali x0 y0, vogliamo poter estrarre un segnale che rappresenti la media dei 2 segnali pesati per la differenza tra max e min del singolo segnale

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 Abbiamo in ingresso 3 segnali x0 y0 z0, vogliamo poter estrarre un segnale che rappresenti la media pesata del prodotto assoluto dei 3 segnali con una finestra mobile di 12 periodi

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

9. F.A.Q.

Q. E' possibile avere più di una funzione con periodo all'interno dello stesso segnale virtuale?

No, al momento un segnale virtuale può contenere solo una singola funzione con periodo, è comunque possibile dividere il segnale virtuale in più segnali e comporlo come derivazione di parti.

Esempio: Abbiamo in ingresso 2 segnali x0 e y0, vogliamo calcolare la somma della media mobile e della media esponenziale mobile dei 2 segnali, 12 periodi

kf(ma(x0+y0),12) + kf(ema(x0+y0),12)

Questa non è una formula valida perchè è composta da più funzioni a finestra. La soluzione per ovviare a questo problema è creare 2 segnali virtuali v1 e v2 con gli stessi ingressi x0 e y0, rispettivamente con formule:

kf(ma(x0+y0),12)

kf(ema(x0+y0),12)

Infine si crea un terzo segnale virtuale con i 2 segnali v1 e v2 in ingresso e si applica la formula

v1 + v2

Sintassi formule segnali virtuali e regole