Formeln und Zeitreihen

Formeln definieren

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

Permanente Formeln

An Zeitreihen hinterlegte Formeln erhalten durch die Zeitreihendefinition ein Intervall, in dem die Formeln berechnet werden sollen. Ebenso ist es möglich, eine Einheit für das Ergebnis sowie eine Aggregationsregel für Umrechnungen zu definieren. Es ist auch möglich Formelzeitreihen in weiteren Formelzeitreihen zu referenzieren.

Stichtag für Formelgültigkeit

In bestimmten Fällen müssen Teile einer gegebenen Formel im Laufe der Zeit geändert werden (z.B. Änderung von Konstanten oder Änderung der Logik nach einem bestimmten Stichtag). Solche sich ändernden Formeln können in HAKOM TSM einfach modelliert werden, indem man den Formeln Stichtage zuweist, ab denen sie gültig werden.

Formeln permanent an 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
Gib Name, Typ, Intervall und Einheit ein
Wechsle mittels der Optionsschaltfläche von Standard auf Formel
Gebe die gewünschte Formel ein
Betätige die Schaltfläche Speichern

WebTSM Services API:

Formeln inklusive Stichtag der Formelgültigkeit können in der Eigenschaft "Formula" auf der Zeitreihendefinition gesetzt 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 beim Abruf der Daten können 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.

Ad Hoc Formeln

Formeln können auch ohne eine Formelzeitreihe durch HAKOM TSM berechnet 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 Berechnungsvorlage* im Bereich Zeitreihe in der Auswahlliste Name (oder via Suchfunktion aus)
Gib die gewünschte Formel im Bereich Zeitreihe in der Auswahlliste Formel ein
1. Optional: wähle einen Berechnungsraster
Betätige die Öffnen Schaltfläche

TSM Excel Vorlage:

Wähle die gewünschte Zeitreihenspalte aus, diese wird der Berechnung als Vorlage* 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

* Berechnungsvorlage

Für die Ausführung einer Formel benötigt TSM einige Informationen, wie z.B. ein Intervall. Hierzu kann jede beliebige Zeitreihe im gewünschten Intervall ausgewählt werden.

Tipp

Der Berechnungsraster kann sich vom Darstellungsraster unterscheiden.

Der Berechnungsraster legt fest, in welchem Intervall die Berechnung stattfinden. Der Darstellungsraster legt das finale Darstellungsformat fest, indem die Ergebnisse angezeigt werden.

Wurde kein Berechnungsraster angegeben, wird die Formel im Raster der Zeitreihe berechnet und anschließend in den Darstellungsraster umgerechnet.
Wurde ein Berechnungsraster ausgewählt, wird die Berechnung in diesem Raster durchgeführt und anschließend in den Darstellungsraster umgerechnet.

WebTSM Services API:

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

Syntax

In 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 Formelsyntax im Detail beschrieben.

Zeitreihen in Formeln 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 der TSM App ist dies bei der Zeitreihenbearbeitung (Optionsschaltfläche "Zeitreihen-Name") und beim Stammdatenimport & -export (Option "Zeitreihennamen in Formel ausgeben") möglich und in der REST API unter /repositories/:repository/timeseries (Parameter "resolveFormulaReferences").
Offset: Ein optionaler, ganzzahliger Wert, welcher um die entsprechende Anzahl an Intervallschritten zusätzlich Daten aus der Vergangenheit (Negativzahl) bzw. aus der Zukunft (Positivzahl) holt, sofern dies für die jeweilige Berechnung relevant ist. Um den Parameter zu überspringen, muss dieser 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

Beispiele

[MeineZeitreihe] --> Referenziert auf "MeineZeitreihe"
[MeineZeitreihe,10] --> Referenziert auf "MeineZeitreihe" lädt zusätzlich zum gewünschten Zeitbereich 10 Intervallschritte 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")

Formeln validieren

Formeln 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 Optionsschaltfläche von Standard auf Formel
Gib die gewünschte Formel ein
Betätige die Schaltfläche Formel prüfen

WebTSM Services API:

Einzelne Zeitreihenformeln können mithilfe des /calculations Pfades durch einen GET Request validiert werden. Dazu sind fiktive 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 Zeitreihenformeln können ebenfalls mithilfe des /calculations Pfades durch einen POST Request validiert werden. Auch hier sind fiktive from- und to-Parameter sowie calculationInterval mitzugeben.

POST/repositories/:reposiory/calculations

Minimum Request Body:

JS

[
    {
        "Name": "<Name der Berechnung>",
        "Formula": "<formula>",
		"From": "<fromDate>",
		"To": "<toDate>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    }
]

Formeln und historisierte Werte bzw. Notierungen

Bei der Abfrage von Zeitreihendaten leiten Formelzeitreihen gewählte Notierungs- und Auditzeitstempel an referenzierte Zeitreihen weiter.

Mehr über Formelzeitreihen und Formelfunktionen erfahren Sie hier: Formelsyntax

Wir empfehlen folgende Videos unter Video Tutorials:

Formula Time Series
AdHoc Calculation
Standard Functions