Formel und Zeitreihen

Formel definieren

Mithilfe von Formeln können berechnete Werte zum Beispiel auf Basis bestehender Zeitreihen ermittelt werden. Formel können in HAKOM TSM entweder einer Formelzeitreihe hinterlegt werden oder Ad Hoc ohne Formelzeitreihe evaluiert werden.

Permanente Formel

An Zeitreihen hinterlegte Formel erhalten durch die Zeitreihendefinition einen Standard-Raster und Einheit/Aggregationsregel in dem die Formelergebnisse abgefragt werden sollen, wodurch sie bei jeder Berechnung wie eine Zeitreihe agieren. Es ist daher auch möglich Formelzeitreihen in weitere Formelzeitreihen zu referenzieren.

Stichtag für Formelgültigkeit

Jede permanente Formel hat ein Anfangsdatum, ab dem diese gilt. So kann zu jedem Stichtag, wann der Logik oder bestimmte Konstanten sich in der Formel ändern sollten durch Erfassen von Stichtag - Formel Paare abgebildet werden.

Formel permanent einer Zeitreihe hinterlegen

Formel permanent einer Zeitreihe hinterlegen:

TSM App:

Klicke auf Öffnen im TSM Ribbon
Betätige die Suchen... Schaltfläche im Bereich Zeitreihe des TSM Fensters
Wähle den Reiter Bearbeiten im Fenster Zeitreihen Suche
Gebe Name, Typ, Intervall und Einheit ein
Wechsle mittels Radiobutton von Standard auf Formel
Gebe die gewünschte Formel ein
Betätige die Schaltfläche Speichern

WebTSM Services API:

Formel inklusive Stichtag für Formelgültigkeit können im Formula Eigenschaft der Zeitreihendefinition hinterlegt werden

POST /repositories/:repository/timeseries/:id|name

POST /repositories/:repository/timeseriescollections/definition

Formula:{
	"1971-12-31T23:00:00Z": "<formula>",
	"2017-04-01T00:00:00Z": "<formula>"
}

Anmerkung

Evaluierung:

Ergebnisse von Formelzeitreihen werden nicht persistiert, sondern immer live ermittelt. So sind die Ergebnisse immer aktuell und können beim Abruf der Daten unterschiedliche Rasterungen, Einheiten, Historisierungs-/Notierungszeitstempeln etc. stets berücksichtigt werden.

Performance:

Eine negative Auswirkung auf die Performance hat die "Live-Evaluierung" in der Regel nicht. Je nach Aufgabe lohnt es sich Aggregate, die öfters am Tag mit denselben Werten abgerufen werden sollen zu persistieren.

Formel validieren

Formel können durch HAKOM TSM direkt bei der Erfassung (TSM App) oder durch Ausführen der Formel validiert werden.

TSM App:

Klicke auf Öffnen im TSM Ribbon
Betätige die Suchen... Schaltfläche im Bereich Zeitreihe des TSM Fensters
Wähle den Reiter Bearbeiten im Fenster Zeitreihen Suche
Wechsle mittels Radiobutton von Standard auf Formel
Gebe die gewünschte Formel ein
Betätige die Schaltfläche Formel prüfen

WebTSM Services API:

Einzelne Zeitreihenformel können mithilfe des /calculations Pfades durch GET Request validiert werden. Dazu reicht ein fiktives from und to Parameter sowie calculationInterval mitzugeben:

GET /repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

Mehrere oder komplexere Zeitreihenformel können ebenfalls mithilfe des /calculations Pfades durch POST Reuquest validiert werden. Auch hier muss ein fiktiver from und to Parameter mitgeben werden.

POST/repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

JS

Minimum Request Body:
[
    {
        "Name": "<Name der Berechnung>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    },
    {
        "Name": "<Name der Berechnung>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    }
]

Ad Hoc Formel

Formel können auch ohne eine Formelzeitreihe an HAKOM TSM zur Evaluation gesendet werden.

TSM App:

Klicke auf Öffnen im TSM Ribbon
Wähle Raster, Einheit und gegebenenfalls weitere Parameter (absteigend und / oder Fehlende leer) aus
Wähle eine Zeitreihe als Berechnungsstemplate* im Bereich Zeitreihe in der Auswahlliste Name (oder via Suchfunktion aus)
Gebe den gewünschten Formel im Bereich Zeitreihe in der Auswahlliste Formel ein
1. Optional: wähle einen Berechnungsraster
Betätige die Öffnen Schaltfläche

TSM App im geöffneten TSM Excel Template:

Wähle die gewünschte Zeitreihenspalte aus, diese wird der Berechnung als Template* dienen
Gebe in Zeile 14 die gewünschte Formel ein
1. Optional: am Ende der Formel mit Semikolon getrennt gebe einen Berechnungsraster (analog zur Liste der Raster in TSM App) ein
Betätige die Aktualisieren Schaltfläche

Siehe auch Lesen in Excel → Zeile 14

Berechnungstemplate

Für die Ausführung eines Formels benötigt TSM einige Informationen, wie Intervall der Daten. Hierzu kann jede beliebige Zeitreihe im gewünschten Intervall ausgewählt werden.

Tipp

Berechnungsraster kann sich vom Berechnungsintervall und vom Darstellungsraster unterscheiden.

Das Berechnungsintervall legt fest, in welchem Intervall die Berechnung statt finden. Der Berechnungsraster legt fest, in welchem Raster die Ergebnisse vom Berechnungsengine ausgegeben werden. Der Darstellungsraster gibt den finalen Darstellungsformat fest indem die Ergebnisse ausgerollt und angezeigt werden.

Wurde kein Berechnungsraster angegeben, wird im selben Raster ausgegeben wie berechnet, also im Intervall der Zeitreihe, anschließend auf den Darstellungsraster ausgerollt.
Wurde ein Berechnungsraster ausgewählt, wird die Berechnung im Berechnungsintervall berechnet, auf den Berechnungsraster aggregiert, anschließend auf den Darstellungsraster aggregiert / ausgerollt.

WebTSM Services API:

Via /repositories/:repository/calculations können eine oder mehrere Formel zur Berechnung übermittelt werden. Siehe oben Formel validieren mittels WebTSM Services API.

Formelreferenzsyntax

In HAKOM TSM Formeln können alle üblichen Operatoren und Funktionen aus der Microsoft Math Bibliothek und weitere von HAKOM bereitgestellte Funktionen verwendet werden.

Die Syntax für Formeln ist unter Formelzeitreihen in Detail beschrieben.

Zeitreihen in Formel referenzieren

Um eine Zeitreihe in einer Formel zu referenzieren muss folgendes Muster befolgt werden:

[Zeitreihenname oder ID, Optional: Offset, Optional: Einheit, Optional: Aggregation]

Zeitreihenname oder ID: Pflichtparameter: entweder der Name oder die ID der Zeitreihe. Der Name wird beim Speichern automatisch als ID aufgelöst. Es ist möglich beim Abruf der jeweiligen Zeitreihendefinition den Namen der jeweiligen Zeitreihe wieder auszulesen. (In TSM App siehe: Formelzeitreihen - Zeitreihen-Name Radiobutton unterhalb der Formeleditor, Stammdatenimport & -export - Zeitreihennamen in Formel ausgeben, bzw. in der REST API /repositories/:repository/timeseries - Parameter resolveFormulaReferences)
Offset: Ein optionales Integerwert, welche um die entsprechende Anzahl an Rastern zusätzlich Daten aus der Vergangenheit (Negativzahl) bzw. aus der Zukunft (Positivzahl) holt, sofern dies für die jeweilige Berechnung relevant ist. Um das Parameter zu überspringen, muss diese mit 0 belegt werden
Einheit: die Einheit in der die Daten der referenzierten Zeitreihe abgerufen werden sollen
Aggregation: Aggregationsregel, welche für die referenzierte Zeitreihe im Rahmen der Formel angewendet werden soll

Formelreferenzsyntax Beispiele

[MeineZeitreihe] --> Referenziert auf "MeineZeitreihe"
[MeineZeitreihe,10] --> Referenziert auf "MeineZeitreihe" lädt zusätzlich zum aktuellen Raster 10 Rasterpunkte aus der Zukunft
[MeineZeitreihe,0,KWh] --> Lädt "MeineZeitreihe" in Einheit "KWh"
[MeineZeitreihe,0,KWh,Average] --> Lädt "MeineZeitreihe" in Einheit "KWh", aggregiert mit der Regel "Average" (statt "Sum")

Eigene Funktionen definieren

Eine Liste der bestehenden Formelfunktionen und deren Funktionsweisen ist in der TSM App Dokumentation zu finden: Formelzeitreihen

Eigene Formelfunktionen können in VB.NET Skripte umgesetzt und mit den Namenspräfix "EvalComponent" im \bin Folder der jeweiligen HAKOM Applikation oder wahlweise in einem zentralen EvalComponent Repository bereitgestellt werden. Mehr zur Konfiguration der EvalComponent Pfade ist hier zu finden: Configuration → Eintrag "EvalComponentPath".

Neue Funktionen bzw. neue Formeln werden bei deren ersten Anwendung sowie bei jeder Änderung neu kompiliert und bei Bedarf auch gecached. Siehe auch "AssemblyCache" Eintrag in Configuration

Wichtigste Variablen in EvalComponents

Die meistgenutzten Objekte in HAKOM Formelfunktionen sind unter EvalComponentHAKOM.vb vordefiniert. Exemplarisch hier einige relevante Variablen und Typen:

aktLine: Aktuelle Datenzeile (Zeitstempel, Wert und Flag) im Verarbeitungsraster - Verwendungsbeispiel: mCalculationTSData(aktLine)
mSourceTSData: Daten der referenzierten Zeitreihe - Verwendung: mSourceTSData(Zeitreihen-Index)
mCalculationTSData: Daten des aktuellen Berechnungsvorganges - Verwendung: mCalculationTSData(Daten-Zeile)
mFormulaTimeSeriesDefinition: Zeitreihendefinitionsobjekt der darunterliegenden Formelzeitreihe - Verwendungsbeispiel: mFormulaTimeSeriesDefinition.Interval
Data: Typ für Daten bestehend aus (Zeitreihen-Index, FromDate, ToDate, Value und Flag)

Formeln und Historisierte Werte bzw. Notierungen

Formelzeitreihen selbst haben keine Persistenz, bei der Abfrage von Zeitreihendaten leiten Formeln aber etwaige Notierungs- und Historiezeitstempel (Auditzeitstempel) an die jeweilige referenzierte Zeitreihen weiter.

Mehr über Formelzeitreihen und Formelfunkionen erfahren Sie hier: Formelzeitreihen

Wir empfehlen folgende Video Tutorials:

Formula Time Series

AdHoc Calculation