# Calculation

**Category:** Control

**Version:** 1.0

**Last Updated:** April 7, 2026

**Author:** Any2Info

***

### Description

The Calculation control is a helper control used to perform mathematical computations on numerical data retrieved from a dataclip.

Unlike visual controls, the Calculation control does not render any UI element on the dashboard. Instead, it produces a computed value that can be consumed by other controls, such as Gauge or Delta controls, for visualization purposes.

The control operates on a selected dataset and applies a chosen mathematical operation to produce a single aggregated result.

***

### Configuration Options

| Setting          | Required    | Description                                                                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Calculation type | Yes         | Defines the mathematical operation to apply. Supported values: **Sum, Min, Max, Average, Count**.                                                       |
| Mapping          | Yes         | Defines how data is selected. Options: **Datapoints** or **Reference**.                                                                                 |
| Datapoints       | Conditional | Allows selecting one or more columns from a dataclip. All values across the selected columns will be used in the calculation. Values must be numerical. |
| Reference        | Conditional | Allows selecting a single column from a dataclip. All values within that column will be used in the calculation.                                        |

> Either **Datapoints** or **Reference** must be configured for the control to function.

***

### Input / Output

#### Input

| Type          | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| Dataclip data | Numerical values retrieved via Datapoints or Reference mapping. |

#### Output

| Type   | Description                                                             |
| ------ | ----------------------------------------------------------------------- |
| Number | A single aggregated value resulting from the selected calculation type. |

***

### Behavior

* The control applies the selected mathematical operation across the resolved dataset.
* When using **Datapoints**:
  * Multiple columns can be selected.
  * All numerical values across these columns are included in the calculation.
* When using **Reference**:
  * A single column is selected.
  * All values within that column are included in the calculation.
* The result is recalculated whenever the underlying dataclip data changes.
* The control does not require any user interaction and does not render visually.

***

### Usage

Use the Calculation control when a derived numerical value is required for visualization.

Typical use cases include:

* Providing aggregated values (e.g., total, average) for a Gauge control
* Calculating target or threshold values
* Supplying comparison values for a Delta control

Example:

* Calculate the **total revenue** across multiple columns and display it in a Gauge against a target value.
* Calculate the **average value of a single column** using Reference mapping.

***

### Tips & Best Practices

* Ensure all selected fields contain **numerical values** to prevent invalid results.
* Use **Datapoints** when combining multiple columns into a single calculation.
* Use **Reference** when calculating across all rows of a single column.
* Choose the mapping type carefully, as it directly affects the dataset being aggregated.
* Use this control to centralize calculations instead of duplicating logic in multiple visual controls.

***

### Limitations

* The control does not render visually on the dashboard.
* Only basic aggregation operations are supported (Sum, Min, Max, Average, Count).
* No support for custom formulas or advanced expressions.
* No event handling or user interaction is supported.
* Incorrect mapping or non-numerical data may lead to invalid results.

***

### Changelog

| Version | Date          | Change                               |
| ------- | ------------- | ------------------------------------ |
| 1.0     | April 7, 2026 | Initial documentation version added. |