# 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:
### 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
### Viewing Calculated Fields in Dashboard
Calculated field visualizations appear in **Calls Live Data** and **Call Studio Live Data** under the **Calculated Fields** accordion.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://dataqueue.gitbook.io/voicehub-docs/agent-design-and-usage/calculated-fields.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.