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 against the incoming time series data stream, i.e. a measurement. If an input measurement receives a new value, the calculation script runs and the output is stored as a separate measurement (= the name of the calculation).
Input measurements
A calculation can run against one or more input measurements. When there is more than one input measurement, the calculation will execute the script whenever all the input measurements have new unprocessed data available.
Calculation types
- A raw calculation has one input measurement and runs for each value of this underlying input measurement ( raw mode ).
- A sampled calculation can use the aggregated values of multiple input measurements and returns one value for each indicated time interval ( sampled mode ).
- A simulated calculation has no input measurements 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 measurement name.
Calculation lifecycle
A calculation has a paused and an active state.
Paused
When clicking the pause button on an active calculation, the calculation will stop it’s operation until it is resumed.
Thus, A paused calculation will not output any new time series data.
Active
To resume the calculation click the same button, which is now indicating Resume instead of Pause. When resuming a calculation, time series data will be processed from the time at which you hit the resume button. Consequently, during the paused state, no new time series data for this time period will have been processed!
Calculation context
Every calculation keeps a stateful context, which retains the last result and timestamp of the calculation and other information, see below for a full list.
It will contain the current state of the
local context
as well.
Editing the calculation context
The context of a calculation can only be changed if the calculation is paused.
It will always contain the context itself, which has the following fields:
PreviousResult: 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 measurement(s)- Input measurement alias: Example _A
- Tags: The time series tags of the input measurement, example “status”
- Datatype: The datatype of the input measurement
- Measurement: The measurement name of the input measurement
- Timestamp: The timestamp of the input measurement
- Value: The value of the input measurement
- Input measurement alias: Example _A
All these will be under Context, everything else from the
local context
will be at the top level.
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
A calculation can be recalculated over a historic time period. For historic time series data or missing time series data (when calculation was paused), one is able to recalculate using a given time period. To recalculate time series data for a particular calculation:
- Press recalculate on a selected calculation
- Indicate a start time
- Optionally set a stop time
- Optionally provide a context for the calculation, enabling this will use the current calculation context but can be updated
Not setting a stop time restarts the running calculation at the start time, with a stop time a separate task is created to recalculate the specified period.
