06 – KPI periodici – RILHEVA Wiki

Tag specifici

Oltre ai tag @nomeTag e @nomeMetadato (vedi sezione “Tag comuni tra KPI Live e Periodici”) sono disponibili i seguenti valori per poter essere utilizzati nelle formule.

@@StartOfPeriod_UTC
@@StartOfPeriod_local

Questi tag rappresentano il timestamp di inizio periodo di calcolo, rispettivamente in UTC e nel fuso orario dell’impianto.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
CASE
WHEN DATEPART(HOUR, @@StartOfPeriod_local) = 1 THEN hstats.max(@consumoEnergia)
ELSE 0
END;

In questo esempio, l’unico periodo nel giorno in cui il KPI viene calcolato come “hstats.max(@consumoEnergia)” è quello tra le 01:00:00 e le 02:00:00 locali, in quanto @@StartOfPeriod_local vale 01:00:00 e quindi la condizione “DATEPART(HOUR, @@StartOfPeriod_local) = 1” è soddisfatta.

@@EndOfPeriod_UTC
@@EndOfPeriod_local

Questi tag rappresentano, rappresentano il timestamp di fine periodo di calcolo, rispettivamente in UTC e nel fuso orario dell’impianto.

NOTA:
La fine del periodo coincide con l’inizio del periodo successivo; ad esempio, con:
@@CALCULATE_EVERY = 1 HOUR;
quando scattano le 01:00:00 in ora locale, e viene quindi calcolato il periodo tra le 00:00:00 e le 01:00:00, @@EndOfPeriod_local è posizionato alle 01:00:00, e non alle 00:59:59.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
CASE
WHEN DATEPART(HOUR, @@EndOfPeriod_local) = 1 THEN hstats.max(@consumoEnergia)
ELSE 0
END;

In questo esempio, l’unico periodo in cui il KPI viene calcolato come “hstats.max(@consumoEnergia)” è quello tra le 00:00:00 e le 01:00:00 locali, in quanto @@EndOfPeriod_local vale 01:00:00 e quindi la condizione “DATEPART(HOUR, @@StartOfPeriod_local) = 1” è soddisfatta.

Direttive

Oltre a @@SKIP_WHEN_NULL e @@RECALCULATE_FROM (vedi la sezione “Direttive comuni tra KPI Live e Periodici”), sono disponibili le seguenti direttive.

@@CALCULATE_EVERY = N MINUTE/HOUR/DAY/WEEK/MONTH(S);

Questa direttiva indica che il KPI non è calcolato live, ma su base periodica.
Senza questa direttiva, la formula è calcolata “live”, ossia ad ogni variazione dei tag che ne fanno parte.

Esempio di KPI periodico:

@@CALCULATE_EVERY = 15 MINUTES;
(@temperatura – 32) × 5/9;

In questo caso ogni 15 minuti viene effettuato il calcolo.
In caso di formula “semplice”, senza quindi funzioni custom Rilheva, i valori di tutti i tag presenti nella formula vengono presi alla fine del periodo interessato.

@@TIMESTAMP_POSITION = START/MID/ADJUSTED_END/END;

Può essere omesso, nel cui caso l’impostazione di default è ADJUSTED_END.
Questa direttiva indica con quale regola assegnare il timestamp del KPI periodico:

START: il timestamp è posizionato all’inizio del periodo di copertura.
MID: il timestamp è posizionato a metà del periodo di copertura.
ADJUSTED_END: il timestamp è posizionato alla fine del periodo di copertura, con un aggiustamento di -1 secondo.
Se ad esempio, la copertura è di 1 ora e si sta elaborando l’ora dalle 00:00:00 alle 1:00:00, il timestamp con ADJUSTED_END viene posizionato alle 00:59:59.
END: il timestamp è posizionato alla fine del periodo di copertura.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@TIMESTAMP_POSITION = START;
hstats.avg(@temperatura);

Alle 00:00:00 del 2 gennaio viene calcolata la media relativa a tutto il giorno del 1 gennaio. Il timestamp viene valorizzato come segue:
START → 1 gennaio 00:00:00
MID → 1 gennaio 12:00:00
ADJUSTED_END → 1 gennaio 23:59:59
END → 2 gennaio 00:00:00

@@DATA_COVERAGE = N MINUTE/HOUR/DAY/WEEK/MONTH(S);

Indica il periodo di copertura per l’unica o la prima serie di dati necessaria alle funzioni custom utilizzate nella formula.
La copertura ha come:

inizio = data/ora di calcolo – @@DATA_COVERAGE
fine = data/ora di calcolo

NOTA: se non esplicitamente indicato, @@DATA_COVERAGE ha come default lo stesso valore di @@CALCULATE_EVERY.

@@DATA2_COVERAGE = N MINUTE/HOUR/DAY/WEEK/MONTH(S);
@@DATA2_TIMESHIFT = N MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S);

Vedi @@DATA_COVERAGE.
Indica il periodo di copertura per la seconda serie di dati necessaria alle funzioni custom utilizzate nella formula.
Se la funzione prevede una seconda serie di dati (vedi ad esempio hstats.avgsratio), @@DATA2_COVERAGE e @@DATA2_TIMESHIFT sono obbligatori.
La copertura ha come:

inizio = data/ora di calcolo – @@DATA2_TIMESHIFT – @@DATA2_COVERAGE
fine = data/ora di calcolo – @@DATA2_TIMESHIFT.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 2 DAYS;
@@DATA2_COVERAGE = 2 DAYS;
@@DATA2_TIMESHIFT = 1 WEEK;
hstats.avgsratio(@temperatura) * 1000;

Poniamo ad esempio che si sta effettuando il calcolo giornaliero (@@CALCULATE_EVERY = 1 DAY) alle 00:00 di lunedì 10 gennaio.
La porzione di formula “hstats.avgratio(@temperature)” è calcolata in questo modo:
(media degli ultimi due giorni) / (media degli stessi giorni della settimana precedente)
che equivale a:
(media da sabato 8 ore 00:00 a domenica 9 ore 24:00) / (media da sabato 1 ore 00:00 a domenica 9 ore 24:00)

Funzioni custom

Nei KPI periodici è possibile utilizzare le seguenti funzioni custom realizzate da Rilheva, oltre ovviamente a quelle che fanno parte del linguaggio Transact SQL.

hstats.cor(arg0, arg1)

Coefficiente di correlazione lineare di Pearson.
Indica se tra i due argomenti può esserci una correlazione, che può essere positiva o negativa.
Se positiva, all’aumentare di arg0 aumenta arg1, se negativa all’aumentare di arg0 diminuisce arg1 e viceversa.
Indicativamente, un valore di 0.7 (o -0.7) o superiore indica una forte correlazione tra i due argomenti.

Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL
arg1: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL

NOTA: per effettuare la correlazione viene preso in considerazione il timestamp dei dati. Per correlare dei dati è quindi necessario che arg0 e arg1 abbiano esattamente gli stessi timestamp.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
@@DATA_COVERAGE = 1 HOUR;
hstats.cor(@temperatura, @consumo);

hstats.digitalcycles_count(arg0)

Conta il numero di passaggi di un digitale da OFF a ON.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL. Per fare in modo che il calcolo sia significativo, deve assumere esclusivamente valori 0 o 1, come ad esempio un tag digitale.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
@@DATA_COVERAGE = 1 HOUR;
hstats.digitalcycles_count(@motoreAcceso);

hstats.digitaltime_off(arg0)

Conta il tempo di permanenza in OFF di un digitale, in secondi.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL. Per fare in modo che il calcolo sia significativo, deve assumere esclusivamente valori 0 o 1, come ad esempio un tag digitale.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
@@DATA_COVERAGE = 1 HOUR;
hstats.digitaltime_off(@motoreAcceso);

hstats.digitaltime_on(arg0)

Conta il tempo di permanenza in ON di un digitale, in secondi.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL. Per fare in modo che il calcolo sia significativo, deve assumere esclusivamente valori 0 o 1, come ad esempio un tag digitale.

Esempio:

@@CALCULATE_EVERY = 1 HOUR;
@@DATA_COVERAGE = 1 HOUR;
hstats.digitaltime_on(@motoreAcceso);

hstats.increment(arg0)

Calcolo dell’incremento che l’argomento ha avuto nel periodo, come differenza tra il valore di fine periodo e il valore di inizio periodo.
Se il calcolo è negativo, viene forzato a zero.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

NOTA: come valore di inizio periodo, se non c’è un datapoint con timestamp esatto sull’inizio periodo, viene preso l’ultimo valore del periodo precedente.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.increment(@energiaTotale);

Avendo a disposizione un dato sull’energia totale prodotta, che è un contatore incrementale, questa formula calcola la produzione in un giorno.

hstats.integral(arg0, seconds_for_one_unit)

Effettua il calcolo integrale.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.
seconds_for_one_unit: indica quanti secondi devono passare, con arg0 a 1, per accumulare una unità.
Ad esempio, se arg0 è in kW, e si vuole calcolare l’integrale in kWh, questo argomento deve essere valorizzato a 3600, perché devono trascorrere 3600 secondi con arg0 a 1 per accumulare 1 kWh.

NOTA: come valore di inizio periodo, se non c’è un datapoint con timestamp esatto sull’inizio periodo, viene preso l’ultimo valore del periodo precedente.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.integral(@potenzaAttiva, 3600);

Questa formula calcola la produzione di energia elettrica in un giorno, in kWh, in base a un tag di potenza attiva, espresso in kW.

hstats.last_minus_first(arg0)

Calcola la differenza tra il primo e l’ultimo datapoint all’interno del periodo.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

NOTA: per quanto riguarda i tag coinvolti nel calcolo, vengono presi in considerazione esclusivamente i data point all’interno del periodo. Si comporta quindi diversamente da altre funzioni come ad esempio hstats.increment e hstats.range.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.last_minus_first(@energiaTotale);

Avendo a disposizione un dato sull’energia totale prodotta, che è un contatore incrementale, questa formula calcola la produzione in un giorno.
In realtà in questo caso sarebbe più corretto utilizzare la funzione hstats.increment oppure hstats.range, perché hstats.increment e hstats.range prendono in considerazione anche la variazione pendente tra un periodo e quello successivo.

hstats.max(arg0)

Calcola il valore massimo all’interno del periodo.

Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.max(@potenzaAttiva);

Questa formula restituisce il picco massimo della potenza attiva durante il giorno.

hstats.avg(arg0)

Calcola la media aritmetica, non pesata, all’interno del periodo.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.avg(@potenzaAttiva);

Viene calcolata la media della potenza attiva.

hstats.avgratio(arg0)

Calcola il rapporto tra le medie di due periodi differenti.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

hstats.min(arg0)

Calcola il valore minimo all’interno del periodo.

Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.max(@potenzaAttiva);

Questa formula restituisce il picco minimo della potenza attiva durante il giorno.

hstats.range(arg0)

Calcola il range, in valore assoluto, tra il minimo e il massimo del periodo.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

NOTA: come valore di inizio periodo, se non c’è un datapoint con timestamp esatto sull’inizio periodo, viene preso l’ultimo valore del periodo precedente.
Questa funzione sembra analoga a hstats.increment, ma dal punto di vista logico operano in modo differente:

hstats.increment sottrae all’ultimo valore del periodo il valore di inizio periodo.
hstats.range sottrae il massimo nel periodo al minimo nel periodo.

Quindi, se arg0 non è un valore che continua necessariamente ad aumentare, ma può anche subire variazioni negative, il risultato delle due funzioni può essere differente.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.range(@energiaTotale);

Questa formula restituisce il parziale dell’energia prodotta durante il giorno, come differenza tra minimo e massimo dei datapoint nel periodo.
In particolare, se non c’è un datapoint precisamente alle 00:00:00 del giorno corrente, viene considerato anche l’ultimo datapoint del periodo precedente.
– 2020-01-01 23:59:00: energia totale: 4990 kWh
– 2020-01-02 00:01:00: energia totale: 5000 kWh
…

– 2020-01-02 23:59:00: energia totale: 5200 kWh
Utilizzando il principio precedentemente descritto, per il giorno 2020-01-02 ho un range di 210. Se si usasse hstats.last_minus_first si otterrebbe invece 200 come risultato, e i 10 kWh di produzione tra le 23:59:00 del giorno precedente e le 00:01:00 del giorno corrente non verrebbero mai conteggiati, né nel KPI del 1 gennaio né in quello del 2 gennaio.

hstats.stdev(arg0)

Calcolo della deviazione standard dell’argomento, nel periodo.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.var(@consumoIstantaneo);

hstats.sum_of_differences(argValue[, argCondition])

Calcola la somma delle differenze di argValue, all’interno del periodo.
Se argCondition è definita, la differenza calcolata nei vari timestamp viene aggiunta solamente se argCondition è soddisfatta (ossia se vale 1).

Sono conteggiate sia le differenze positive che quelle negative.
Gli argomenti sono:

argValue: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.
argCondition: Opzionale. Può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL. E’ trattata come boolean e deve quindi assumere dei valori 0/1.

NOTA: come valore di inizio periodo di argValue, se non c’è un datapoint con timestamp esatto sull’inizio periodo, viene preso l’ultimo valore del periodo precedente.

Esempi:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.sum_of_differences(@energiaTotale);

In questo caso la condizione argCondition non è stata specificata, e quindi, all’interno del giorno,sono considerate valide tutte le variazioni.
– 2020-01-01 23:59:00: energia totale: 4990 kWh
valore di inizio periodo: 4990 (perché non ho un datapoint alle 00:00:00)
– 2020-01-02 00:01:00: energia totale: 5000 kWh → 5000 – 4990 = 10
– 2020-01-02 08:00:00: energia totale: 5100 kWh → 5100 – 5000 = 100
– 2020-01-02 16:00:00: energia totale: 5150 kWh → 5150 – 5100 = 50
– 2020-01-02 23:59:00: energia totale: 5220 kWh → 5220 – 5150 = 70
Il KPI del giorno 2 gennaio 2020 vale quindi 10 + 100 + 50 + 70 = 230.

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.sum_of_differences(@energiaTotale, @inverter1Acceso);

In questo caso le differenze all’interno del giorno sono considerate valide solo quando @inverter1Acceso vale 1.
– 2020-01-01 23:59:00: energia totale: 4990 kWh
valore di inizio periodo: 4990 (perché non ho un datapoint alle 00:00:00)
– 2020-01-02 00:01:00: energia totale: 5000 kWh, inverter 1 acceso → 5000 – 4990 = 10
– 2020-01-02 08:00:00: energia totale: 5100 kWh, inverter 1 spento → 5100 – 5000 = 100
– 2020-01-02 16:00:00: energia totale: 5150 kWh, inverter 1 spento → 5150 – 5100 = 50
– 2020-01-02 23:59:00: energia totale: 5220 kWh, inverter 1 acceso → 5220 – 5150 = 70
Il KPI del giorno 2 gennaio 2020 vale quindi 10 + 70 = 80.

hstats.sum_of_increments(argValue[, argCondition])

Calcola la somma degli incrementi all’interno del periodo.
Se argCondition è definita, la differenza calcolata nei vari timestamp viene aggiunta solamente se argCondition è soddisfatta (ossia se vale 1).

Le differenze negative vengono conteggiate a zero. Se abbiamo quindi un contatore incrementale che fa un auto-reset, nel momento del reset, ad esempio da 10000 a 0, non viene calcolato un “incremento” di -10000, ma viene conteggiato a zero.
Gli argomenti sono:

argValue: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.
argCondition: Opzionale. Può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL. E’ trattata come boolean e deve quindi assumere dei valori 0/1.

NOTA: come valore di inizio periodo di argValue, se non c’è un datapoint con timestamp esatto sull’inizio periodo, viene preso l’ultimo valore del periodo precedente.

Esempi:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.sum_of_increments(@energiaTotale);

In questo caso la condizione argCondition non è stata specificata, e quindi, all’interno del giorno, sono considerate valide tutte le variazioni positive.
– 2020-01-01 23:59:00: energia totale: 4990 kWh
valore di inizio periodo: 4990 (perché non ho un datapoint alle 00:00:00)
– 2020-01-02 00:01:00: energia totale: 5000 kWh → 5000 – 4990 = 10
– 2020-01-02 08:00:00: energia totale: 0 kWh → 0 – 5000 = forzato a 0
– 2020-01-02 16:00:00: energia totale: 50 kWh → 50 – 0 = 50
– 2020-01-02 23:59:00: energia totale: 120 kWh → 120 – 50 = 70
Il KPI del giorno 2 gennaio 2020 vale quindi 10 +50 + 70 = 130.

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.sum_of_increments(@energiaTotale, @inverter1Acceso);

In questo caso le variazioni positive all’interno del giorno sono considerate valide solo quando @inverter1Acceso vale 1.
– 2020-01-01 23:59:00: energia totale: 4990 kWh
valore di inizio periodo: 4990 (perché non ho un datapoint alle 00:00:00)
– 2020-01-02 00:01:00: energia totale: 5000 kWh, inverter 1 acceso → 5000 – 4990 = 10
– 2020-01-02 08:00:00: energia totale: 0 kWh → 0 – 5000 = forzato a 0
– 2020-01-02 16:00:00: energia totale: 50 kWh, inverter 1 acceso → 50 – 0 = 50
– 2020-01-02 23:59:00: energia totale: 120 kWh, inverter 1 spento → 120 – 50 = 70
Il KPI del giorno 2 gennaio 2020 vale quindi 10 + 70 = 80.

hstats.var(arg0)

Calcolo della varianza dell’argomento, nel periodo.
Gli argomenti sono:

arg0: può essere una semplice variabile, o anche una formula direttamente calcolabile in Transact SQL.

Esempio:

@@CALCULATE_EVERY = 1 DAY;
@@DATA_COVERAGE = 1 DAY;
hstats.var(@consumoIstantaneo);

Was this helpful?

0 / 0

06 – KPI periodici

Tag specifici

@@StartOfPeriod_UTC@@StartOfPeriod_local

@@EndOfPeriod_UTC@@EndOfPeriod_local

Direttive

@@CALCULATE_EVERY = N MINUTE/HOUR/DAY/WEEK/MONTH(S);

@@TIMESTAMP_POSITION = START/MID/ADJUSTED_END/END;

@@DATA_COVERAGE = N MINUTE/HOUR/DAY/WEEK/MONTH(S);

@@DATA2_COVERAGE = N MINUTE/HOUR/DAY/WEEK/MONTH(S);@@DATA2_TIMESHIFT = N MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S);

Funzioni custom

hstats.cor(arg0, arg1)

hstats.digitalcycles_count(arg0)

hstats.digitaltime_off(arg0)

hstats.digitaltime_on(arg0)

hstats.increment(arg0)

hstats.integral(arg0, seconds_for_one_unit)

hstats.last_minus_first(arg0)

hstats.max(arg0)

hstats.avg(arg0)

hstats.avgratio(arg0)

hstats.min(arg0)

hstats.range(arg0)

hstats.stdev(arg0)

hstats.sum_of_differences(argValue[, argCondition])

hstats.sum_of_increments(argValue[, argCondition])

hstats.var(arg0)

@@StartOfPeriod_UTC
@@StartOfPeriod_local

@@EndOfPeriod_UTC
@@EndOfPeriod_local

@@DATA2_COVERAGE = N MINUTE/HOUR/DAY/WEEK/MONTH(S);
@@DATA2_TIMESHIFT = N MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S);