Introduction
A calculation can be used to operate on existing time series data and store the output as new separate time series data. In essence, a calculation is a script that runs periodically or against the incoming time series data stream, i.e. another measurement or asset property. The output of the calculation is stored as a separate measurement (= the name of the calculation).
Calculation types
- A raw calculation has one input data reference and runs for each value of this underlying input data reference ( raw mode ).
- A sampled calculation can use the aggregated values of multiple input data references and returns one value for each indicated time interval ( sampled mode ).
- A simulated calculation has no input data references and returns a simulated value for each indicated time interval ( simulation mode ).
Creating a calculation
Creating a calculation is similar as creating a measurement .
- Configure the basic measurement properties
- Choose a calculation type
- Specify the calculation settings, which depend on the calculation type:
- Setup the calculation script
_A) instead of the reference’s name.
Calculation lifecycle
A calculation can either be Paused or Active.
Paused
When clicking the pause button on an active calculation, the calculation will stop its operation until it is resumed.
A paused calculation will not output any new time series data.
Active
To resume the calculation, click the Resume button. When resuming a calculation, processing will restart at the beginning of the next interval.
Consequently, no new time series data will have been processed while the calculation was paused!
Calculation context
Every calculation keeps a stateful context, which retains the last result and timestamp of the calculation along with other information and the local context (see below for a full list).
Editing the calculation context
The context of a calculation can only be changed if the calculation is paused.
The calculation context will always contain the Context itself under the Context key. The
local context
is at the top level.
The calculation context contains the following fields:
<local context field 1><local context field 2>ContextPreviousResult: the last result of the calculationValue: The value returned by the last run of the calculationTags: A map of tags set which can be set in the scriptStatus: The status set in the script, will only be visible if set inside the script
IntervalMs: The interval at which the calculation is executedOffsetMs: The offset at which the calculation is executedTimestamp: The timestamp of the current calculationPreviousTimestamp: The timestamp of the previous calculationPreviousInput: The previous value of the input data reference(s)- Input data reference alias: Example _A
- Tags: The time series tags of the input data reference, example “status”
- Datatype: The datatype of the input data reference
- Data reference: The name of the input data reference
- Timestamp: The timestamp of the input data reference
- Value: The value of the input data reference
- Input data reference alias: Example _A
You can edit/add anything inside the context.
The following variable types are available:
- string
- int
- float
- bool
- time
- map
- array
Look at some examples on how to use the calculation context here .
Recalculation of time series data
It is possible to recalculate time series data for a calculation. This can be used to calculate missing time series data of when the calculation was paused or did not exist yet.
This can be achieved by either restarting the calculation at a point in time or by recalculating a specific time period.
To recalculate time series data for a calculation, follow these steps:
- Press recalculate on a selected calculation
- Choose whether to restart the calculation at a specific time or recalculate a specific period.
When you restart a calculation that is Paused, it will only generate new time series data after it has been resumed - Set a start time, and a stop time (if required) for the calculation
- Optionally provide a context for the calculation.
By enabling ‘Recalculate with context’, the existing calculation context will be used, additionally it is possible to modify the context before starting the recalculation
