---
title: Calculations
slug: concepts/calculations
docTags: 5fJw2a1qRamk_WQBiogL7
createdAt: 2025-07-17T09:19:25.399Z
---

## 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](docId\:XQWLEmDcNfff3-0H-GMmS) or other calculations and writes the calculation result to the [Time-series databases](docId\:h4jS6GCABOg53kbawGyUa).

## 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](https://github.com/d5/tengo)
- 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:

:::BlockQuote
Machines → Collector → Historian (as measurements) → **Historian (as calculations)** → Visualizations / Reports
:::

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
- [Context](docId\:LaPhNBuHRbKOJlq5cIt-r) 

## 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:

```javascript
return _Flowrate.Value / _Energy.Value
```

## When 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 calculation](docId:5ko0eadY3X_O-y1Jxd8Cp) 
- [How to use Calculation Context](docId:9vedQPMTtHzwUy1cLKaVh) 
- [Using metadata to reuse calculations](docId\:VmElwzGf3OvtOToKgJ61Q)