> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.umnai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.umnai.com/_mcp/server.

# Context explanations

Context explanations enrich local explanations by adding comparison or scenario context.

A local explanation describes why a model produced a prediction for a specific query. A context explanation compares that query, prediction, or attribution pattern with another condition or another case. This can make the explanation easier to interpret, especially when the question is not only "why this prediction?" but "how would this prediction change if something were different?"

Examples include what-if analysis, control swaps, and nearest-neighbour comparisons.

## Why context explanations matter

Context explanations are comparative and contrastive.

They help explain a prediction by showing how it relates to alternatives:

| Comparison                                         | What it helps explain                                  |
| -------------------------------------------------- | ------------------------------------------------------ |
| A query compared with a modified version of itself | What changes when one input value changes.             |
| A query compared with similar cases                | Why the prediction is consistent with nearby examples. |
| A query compared with dissimilar cases             | What makes the query different from distant examples.  |
| A query compared with related cases                | What additional context helps explain the prediction.  |

## Control swap

A control swap explains how the value of a categorical feature affects a [prediction](./local-explanations/predictions-and-attributions#prediction).

It does this by comparing the original query with one or more versions of the same query where the categorical feature has been changed to another category.

For example, if a query involves a male person, the same query could be re-run with `Gender` set to `Female` to check whether the prediction changes. The prediction results can then be compared to see whether the outcome changed.

The [module attributions](./local-explanations/predictions-and-attributions#module-attributions) and [feature attributions](./local-explanations/predictions-and-attributions#feature-attributions) can also be compared to identify where the differences appear and how the swap affected the prediction.

Because attributions are additive, they can be compared side by side or subtracted to calculate deltas. For example, to see the attribution effect of moving from `Male` to `Female`, subtract the original `Male` attributions from the `Female` attributions.

## Control swap example

The example below shows a `Gender` control swap from `Male` to `Female` in a Hybrid Intelligence classification model.

In this case, the classification result did not change. The decrease in attributions shows bias favouring the `Male` class, but the final outcome was not affected.

Comparing the module and feature attributions shows that the largest attribution changes came from interactions between:

| Interaction              | Meaning                                               |
| ------------------------ | ----------------------------------------------------- |
| `Gender × Education_Num` | Gender interacting with number of years in education. |
| `Gender × Education`     | Gender interacting with education level.              |

![Control Swap: Classification and Total Attributions results](https://files.buildwithfern.com/umnai.docs.buildwithfern.com/5853cc8d71fc5552779f3280d2fef91f9ef6c57e565f8bb02144006396d5976d/assets/images/control-swap-classification-total-attributions.png)

![Control Swap: Module attribution plots for original query, swap query and differences between the two (only attributions that changed shown)](https://files.buildwithfern.com/umnai.docs.buildwithfern.com/62aca74cb163b3404f7a9538d7a7af70ae720b60851309e2803b1cd561f2c2a9/assets/images/control-swap-module-attribution-plots.png)

![Control Swap: Feature attribution plots for original query, swap query and differences between the two (only attributions that changed shown)](https://files.buildwithfern.com/umnai.docs.buildwithfern.com/719724aed45e767e798d746c092c6730af13fc98c9290d0b842f9c139e91a47d/assets/images/control-swap-feature-attribution-plots.png)

![Control Swap: Feature attribution tables for original query, swap query and differences between the two (only attributions that changed shown)](https://files.buildwithfern.com/umnai.docs.buildwithfern.com/637a755ab2b99b5fc47ea55a6d560beef85fcb31c30f7a34723c84c389df3b35/assets/images/control-swap-feature-attribution-tables.png)

## Nearest neighbour

Nearest-neighbour explanations use similarity to provide context for a [prediction](./local-explanations/predictions-and-attributions#prediction).

By examining similar, dissimilar, and related queries, they can provide insight into the model's decision-making process.

Similarity is enabled by vector embeddings. In Hybrid Intelligence, vector embeddings organise information by placing objects on a virtual map: similar objects are close together, and different objects are farther apart. This makes it easier to find patterns and relationships.

## Similarity

Similar neighbours are close to the query according to a chosen distance metric.

They can help explain a prediction by showing that the query is similar to other cases with the same or similar outcomes.

## Dissimilarity

Dissimilar neighbours are far from the query according to a chosen distance metric.

Contrasting the query with dissimilar neighbours can highlight what makes the query unusual or why it was predicted differently from distant cases.

## Relatedness

Related neighbours may not be the closest by distance, but they share characteristics or patterns that are relevant to the explanation.

They can provide context or additional insight that may not be obvious from nearest neighbours alone.