> For the complete documentation index, see [llms.txt](https://dataqueue.gitbook.io/voicehub-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dataqueue.gitbook.io/voicehub-docs/agent-design-and-usage/calculated-fields.md).

# Calculated Fields

Calculated Fields allow you to define custom math expressions that are evaluated **after** all other analysis fields, so they can reference extracted variables, call context, and custom analysis fields as inputs.

You can use them to track things like:

* A **total quality score** computed from multiple analysis factors
* A **weighted average** of different performance metrics
* **String manipulation** of context variables (e.g. extracting digits from a phone number)

### Creating a Calculated Field

Calculated fields can be configured in **Call Analysis settings** or **Call Studio Analysis settings**, under the **Calculated Fields** section.

Each field requires the following properties:

| Field                       | Description                                                                                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                    | The unique identifier for the field. Must start with a letter or underscore and contain only letters, numbers, and underscores (e.g. `totalScore`, `avg_rating`) |
| **Expression**              | A [math.js](https://mathjs.org/docs/expressions/syntax.html) expression that computes the field value                                                            |
| **Result Type**             | The type of value the expression returns (`number`, `string`, or `boolean`)                                                                                      |
| **Dashboard Visualization** | How the field is displayed in the dashboard (`Average`, `Sum`, `Min`, `Max`, `Count`, `Latest`, or `Distribution`)                                               |

### Example:

<figure><img src="/files/Cw7EJYqvO0fqsr0KnP8r" alt=""><figcaption></figcaption></figure>

### Writing Expressions

Expressions are evaluated using [math.js](https://mathjs.org/docs/expressions/syntax.html). You can reference any non-PII variable from:

* **Call context** — variables like `phoneNumber`, `direction`, `callType`
* **Extracted variables** — variables extracted during the call
* **Custom analysis fields** — fields defined in your analysis settings

Calculated fields are evaluated **in order**, so a later field can reference an earlier calculated field.

> **Note:** Variables tagged as PII are automatically excluded from the expression scope for privacy.

**Examples**

**Total quality score from 4 criteria:**

```
criteriaA + criteriaB + criteriaC + criteriaD
```

**Weighted average of two scores:**

```
(satisfactionScore * 0.7) + (effortScore * 0.3)
```

**Check if score meets a threshold:**

```
totalScore >= 8
```

**String concatenation:**

```
agentName + " - " + region
```

**String length:**

```
size(customerFeedback)
```

### Dashboard Visualizations

The visualization type determines how the field's aggregated results are displayed in the dashboard.

| Visualization    | Best for                          | Display                                    |
| ---------------- | --------------------------------- | ------------------------------------------ |
| **Average**      | Numeric scores averaged over time | Single number card showing the mean value  |
| **Sum**          | Totals across all calls           | Single number card showing the total       |
| **Min**          | Lowest recorded value             | Single number card showing the minimum     |
| **Max**          | Highest recorded value            | Single number card showing the maximum     |
| **Count**        | Exact number of calls/records     | Single number card showing the total count |
| **Latest**       | Most recent value                 | Single number or text card                 |
| **Distribution** | Frequency of each value           | Bar chart showing how many calls per value |

> **Tip:** For `boolean` result types, use **Distribution** to see a breakdown of `true` vs `false` across calls.

### Viewing Calculated Fields in Call Analysis

Calculated fields appear in the **Call Analysis modal** for each call or call studio record, under the **Calculated Fields** section. For every field you will see:

* Field name
* Computed value

<figure><img src="/files/WLExeb29rhYOauYEcMrL" alt=""><figcaption></figcaption></figure>

### Viewing Calculated Fields in Dashboard

Calculated field visualizations appear in **Calls Live Data** and **Call Studio Live Data** under the **Calculated Fields** accordion.

<figure><img src="/files/KaxUexQKm14S5sdhi14i" alt=""><figcaption></figcaption></figure>