> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets.md).

# Benchmark and Targets

Portfolio Benchmark & Targets compares measured asset values with a modelled target derived from historical reference periods. Use it to review consumption against a baseline and identify periods above or below the target.

For a conceptual introduction, practical examples, and guidance on interpreting the results, read the Academy chapter [-> Introduction to Benchmarking and Targets](https://docs.buildings.ability.abb/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/machine-learning/introduction-to-benchmarking-and-targets.md).

## What you can use it for

### Detect unusual operation

Use a moving baseline to compare current operation with a rolling period of recent history. For example, compare a building's daily energy use with its recent operating pattern, taking selected inputs such as outdoor temperature into account. The generated difference and percentage-difference attributes can be inputs to simple rule alarms: an absolute difference identifies an excess in the source unit, while a percentage difference identifies a relative departure from the target.

An alarm can draw attention to unexpected consumption or a developing change in operation; it does not identify the cause. Choose thresholds that allow normal variation, then investigate the source history and operating conditions when a threshold is crossed. The percentage difference is smoothed, so it is more suitable for sustained departures than for identifying every short spike. See [-> operational alarms with generated deviations](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/view-a-target-in-insight-analytics.md#use-deviations-for-operational-alarms) and [-> Create a Rule](https://docs.buildings.ability.abb/collection/platform/alarms-rules-and-escalations/rules/create-a-rule.md).

A moving baseline adapts as its reference period advances. That is useful when normal operation changes, but a persistent deterioration can eventually enter the reference period and become part of the new normal. Keep a fixed baseline as well when you need to measure long-term drift or savings against an unchanged reference.

### Track an energy-reduction goal

Use a fixed historical baseline and an **Offset** to turn expected consumption into a reduction target. For example, a **Fixed** 10% offset sets an allowance 10% below the fitted model from the selected start date. A **Gradual** 10% offset introduces the reduction progressively between its start and end dates, then retains the full reduction.

This lets you check whether an improvement programme is on track rather than only comparing consumption with last year's total. The target still follows the modelled operating pattern: a gradual reduction does not mean every plotted value is lower than the preceding one. Compare measured use with the allowance for the same period.

### Find when historical operation changed

Use **Auto** when you do not know when a building's energy behaviour changed. Automatic detection analyses historical data and proposes reference periods separated by sustained changes. Review those periods alongside known events, such as a plant replacement, an occupancy change, or a revised operating schedule.

Use the detected periods as a starting point for investigation, not proof of a fault or its cause. This is retrospective analysis, not a continuously running anomaly alarm. See [-> Create a Baseline](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/create-a-baseline.md) for choosing and tuning detection.

### Check whether the comparison is meaningful

Review **Predicted vs actual** before relying on a target or alarm. Within a representative reference period, the model should broadly follow the measured operating pattern. Inspect the difference and CUSUM charts for persistent bias or a trend already present in the baseline. A baseline that already contains changing conditions can make later improvements or deterioration harder to interpret.

## B\&T configs, baselines and values <a href="#targets-and-baselines" id="targets-and-baselines"></a>

A **Benchmark and Targets (B\&T) configuration**, shortened to **B\&T config**, selects the asset and source attribute you want to evaluate. Optional **feature attributes**, such as outside temperature or occupancy, provide additional inputs for modelling its values.

A **baseline** defines the historical reference period and its modelling settings. A B\&T config can contain several baselines:

* A fixed baseline uses explicit start and end dates.
* A moving baseline uses a rolling period with a configured length and offset from today.
* Automatic detection identifies sustained changes in operating conditions and saves the detected periods as baselines.

**Actual values** are the measured values of the selected source attribute. **Target values** are calculated from a baseline's model, including any configured **Offset**. The B\&T config groups the source selection and baselines; it is not itself a target value.

{% hint style="info" %}
The current interface calls a B\&T config a **target**. Controls such as **Add Target**, **Configure target** and **Open target** retain their displayed names in these instructions. **Target attribute** selects the measured source attribute, not a generated target-value attribute.
{% endhint %}

Saving a baseline does not activate it. An active baseline generates target and deviation values through background processing. You can review its preview before activation.

{% hint style="info" %}
These target values provide a historical benchmark, not a prediction of future values. For future-value forecasting, see [-> Predictive Forecasting](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/forecast-engine.md).
{% endhint %}

## Get started

Benchmark and Targets is a platform feature; it does not require a separate Benchmark and Targets module license. The source attribute and any selected feature attributes need historical data for the reference period.

* [-> Open Benchmark and Targets](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/open-benchmark-and-targets.md)
* [-> Create a B\&T Config](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/create-a-target.md)
* [-> Create a Baseline](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/create-a-baseline.md)
* [-> Configure a Baseline](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/configure-a-baseline.md)
* [-> Review a B\&T Config](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/review-a-target.md)
* [-> Activate or Pause a Baseline](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/activate-or-pause-a-baseline.md)
* [-> View a B\&T Config in Insight Analytics](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/view-a-target-in-insight-analytics.md)

To remove saved configurations, see [-> Delete Baselines and B\&T Configs](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/delete-baselines-and-targets.md).

## Compare actual values with the target

The selected baseline's preview and [-> Insight Analytics](https://docs.buildings.ability.abb/collection/platform/insight-analytics.md) support the following comparisons:

<table><thead><tr><th width="209.59991455078125">Comparison</th><th>Meaning</th></tr></thead><tbody><tr><td>Actual and target</td><td>Measured values alongside the modelled target.</td></tr><tr><td>Difference</td><td>Actual value minus target value. Positive values are above target; negative values are below it.</td></tr><tr><td>Percentage difference</td><td>Percentage deviation between moving averages of actual and target values, rather than each individual pair of values.</td></tr><tr><td>Cumulative sum (CUSUM)</td><td>Accumulated actual-minus-target differences over time.</td></tr></tbody></table>

## Generated asset attributes

[-> Activating a baseline](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/activate-or-pause-a-baseline.md) automatically creates four normal asset attributes for its calculated outputs. You can use them throughout the platform like other attributes, including in [-> rules](https://docs.buildings.ability.abb/collection/platform/alarms-rules-and-escalations/rules/create-a-rule.md), [-> rule chains](https://docs.buildings.ability.abb/collection/platform/alarms-rules-and-escalations/rule-chains.md) and [-> dashboard widgets](https://docs.buildings.ability.abb/collection/platform/live-cockpit/add-widgets-to-the-dashboard.md). Select the source asset and the required generated attribute. The usual selector requirements apply, such as supported attribute types and whether a widget requires trend data.

### Where the attributes are added

The attribute definitions are added to the source asset's **asset type (template)**, alongside its existing attributes. You can inspect the template's attributes through [-> Asset Modeling](https://docs.buildings.ability.abb/collection/mandatory-base/platform-core/asset-core/configure-attributes.md). Look for names beginning with `[B&T]`; you do not need to add these attributes manually.

Definitions are shared by assets of that type, but calculated current values and trend history are written to the source asset selected in the B\&T config. Another asset using the same template can therefore have the same attribute definitions without having that baseline's calculated values.

### Names and values

The generated attributes use the source attribute's subtype and attribute type, and are enabled, viewable and trended when created. In the names below:

* `<attribute>` is the source attribute's technical name, not its translated display label or the asset name.
* `<schema-number>` is the output schema number assigned to the baseline on activation. It distinguishes active baselines within the same B\&T config; it is not the source subtype or the baseline ID. Pausing releases this number, so reactivation can produce a different suffix.

| Attribute name                                                  | Quantity and unit                                                                                      | Interpretation                                                                                                                                                            |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[B&T]target_<attribute>_<schema-number>`                       | Modelled target for each interval, including the configured **Offset**. Source unit.                   | Compare the measured value with the allowance for the same interval.                                                                                                      |
| `[B&T]target_difference_<attribute>_<schema-number>`            | Actual minus offset-adjusted target for each interval. Source unit.                                    | Positive means above target; negative means below target; zero means a match.                                                                                             |
| `[B&T]target_difference_percentage_<attribute>_<schema-number>` | `100 × (moving average of actual − moving average of target) / moving average of target`. Percent (%). | Uses trailing moving averages, not the percentage of each individual interval. For positive target averages, positive means above target and negative means below target. |
| `[B&T]target_difference_cusum_<attribute>_<schema-number>`      | Cumulative sum (CUSUM) of the raw interval differences. Source unit.                                   | A rising curve accumulates above-target differences; a falling curve accumulates below-target differences. Values are already cumulative: do not add them together again. |

For example, if the source attribute's technical name is `energy` and the baseline is assigned output schema number `1`, the generated names are:

* `[B&T]target_energy_1`
* `[B&T]target_difference_energy_1`
* `[B&T]target_difference_percentage_energy_1`
* `[B&T]target_difference_cusum_energy_1`

The absolute difference and CUSUM are raw source-unit outputs, not percentages normalized to a baseline mean. Do not substitute a baseline-normalized chart value for one of these attributes when choosing a rule threshold. For example, with an energy source in kWh, an actual interval value of 110 kWh and a target of 100 kWh produce a difference of +10 kWh. Whether above or below target is desirable depends on what you measure: lower energy use can be desirable, while lower production output may not be.

{% hint style="info" %}
When the moving-average target is zero or very close to zero, the percentage output is set to zero to avoid division by zero. In that case, zero does not establish that the target is met. Check the absolute difference and underlying values instead.
{% endhint %}

### Why attributes can remain after deletion

Deleting a baseline does not necessarily remove its `[B&T]` attribute definitions. Within the same tenant, a definition remains while another active baseline uses the same source attribute, subtype and output schema number for that asset type. The other baseline can belong to a different asset.

For example, two meters with the same template and source attribute `energy` can each have an active baseline with output schema number `1`. Both use the shared definition `[B&T]target_energy_1`, but each meter has its own calculated values. Deleting the first meter's baseline leaves the definition in place for the second meter. Background cleanup can still remove the first meter's generated values and history; the second meter's values and history remain available. Definitions are removed only when no active baseline still needs them.

A remaining definition is not evidence that the deleted baseline is still running or that its generated history has been preserved. Before pausing or deleting, check the [-> generated-output dependency caution](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/activate-or-pause-a-baseline.md#pause-a-baseline). For the deletion procedures, see [-> Delete Baselines and B\&T Configs](https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets/delete-baselines-and-targets.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.buildings.ability.abb/collection/platform/platform-core/baseline-and-factors/portfolio-benchmark-and-targets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
