Calculations
What is a Calculation?
A calculation is similar to a measurement, with the difference that it is computed based on other data in the Historian. It’s how you transform raw data into something more meaningful: moving averages, status maps, efficiencies, etc.
A calculation takes 1 or more input Measurements or other calculations and writes the calculation result to the Time-series databases.
Why does it matter?
Raw measurements can be too limiting to give immediate insight. Calculations help you turn that raw data into operational metrics that are easier to monitor and act on.
They can help answer questions like:
- How often did the temperature exceed the target?
- How much energy did we consume per ton of product?
- How much heat was exchanged over our heat exchanger?
How does it fit in the system?
Calculations are defined in the Historian and run on a schedule or when triggered, typically using:
- One or more measurements or calculations as input
- A calculation script, written in the Tengo language
- Depending on the type of calculation, an aggregation function to run for each input measurement or calculation, before the data is passed to the calculation script
- An interval to run the calculation (predefined, or at the same resolution as the input for the calculation)
Here’s the flow:
Calculated values are stored just like regular measurements and can be used in dashboards, alerts, or further calculations.
Similarities with Measurements
Just like with measurements, calculations have:
- A name, datatype and destination database
- A quality history
And can have:
- A description
- Engineering specifications (Units of Measurement, Min/Max, HI/LO levels)
- Metadata and labels
Differences with Measurements
In contrast with measurements, calculations have:
- One or more input measurements or calculations
- A Tengo script
- ContextContext
Example
Let’s say you collect, for an input pump feeding a mixing vessel, the following measurements:
- simulator/Line_1/M1/P1/energyUsage, aliased as _Energy with aggregation mean.
- simulator/Line_1/M1/P1/flowRate, aliased as _Flowrate with aggregation mean.
Then you could define:
- simulator/Line_1/M1/P1/calcEfficiency
With the following script, to run every minute:
return _Flowrate.Value / _Energy.ValueWhen you use it
You’ll interact with calculations when:
- You need aggregated or transformed data
- You want to monitor KPIs or performance metrics
- You're building dashboards or reports that show trends over time
You may configure calculations during system setup, but also later as users evolve their use of the system.
Common misconceptions
- A calculation does not recalculate automatically if the calculation script changes, or if historical source data is edited. You’ll need to manually reprocess it in that case.
- A calculation is not the same as a formula in a dashboard. Calculations create a persisted time series, not a one-off display value.
- Calculations don’t run in real time; they typically run at defined intervals (e.g., every minute, hourly).
Best practices
- Keep naming consistent and descriptive (e.g., Line2.Speed.Avg_5min)
- Document the calculation logic clearly, especially if it includes filters or conditions, with a description and comments in the script.
- Avoid overly complex calculations in a single script. Split the logic into multiple calculation scripts, and define outputs of calculations as inputs for other calculations.
More information
- Creating a calculationCreating a calculation
- How to use Calculation ContextHow to use Calculation Context
- Using metadata to reuse calculationsUsing metadata to reuse calculations