> This page is for Structured Data Models Client.

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

# Understand Explanations

> Interpret Kumo Relational gradient sensitivity and column cohort statistics

Use column cohorts to explore patterns in labelled examples and gradients to investigate one prediction's sensitivity to its inputs.
These answer different questions; neither establishes causality.
Start with [Prediction Explainability](/sdgm/kumo-relational/user-guide/explain-predictions/prediction-explainability) for availability and a request that produces `result`.

## Cohort analysis

`result.explanations.columns` groups labelled context examples by value range or category for each input column and summarizes the observed outcomes in each group.
These summaries do not measure how much a column contributed to an individual prediction.
For related categorical and timestamp columns, the proportions and averages below are weighted because an entity can contribute to several cohorts; see [Which examples are included?](#which-examples-are-included).

For regression, `mean` is the average observed target within the group, expressed in the target's units, and `class` is `None`.
For example, when predicting next month's order total in dollars, `mean: 120` means the group's context examples had an average observed order total of \$120.

For classification, `class` identifies the target label being summarized, and `mean` is the proportion of examples in the group whose observed label matches that class.
For example, `class: "churned"` and `mean: 0.3` means 30% of the group's context examples churned.
This is the group's observed churn rate, not a churn probability for an individual prediction.

```python
analysis = result.explanations.columns
if analysis is not None:
    cohorts = analysis.to_pandas()
    order_amount = cohorts[
        (cohorts["table"] == "orders")
        & (cohorts["hop"] == 1)
        & (cohorts["column"] == "amount")
    ]
    print(order_amount[["cohort", "class", "share", "mean"]])
```

`share` is the fraction of the analysed population in the cohort.
For example, `share: 0.2` means the cohort contains 20% of that population.
Compare `mean` across cohorts of the same column, hop, and class, and consider how well each cohort is represented before interpreting differences.
A small share does not necessarily mean a small absolute sample size.

### Which examples are included?

For a one-shot relational request, the analysis uses the gathered labelled context before leakage checks remove the scored entities from individual payloads.
It is computed once for the request, rather than separately for each batch, and can include examples not sent in a particular batch.
The entity's own table is included at hop 0; the question rows containing the anchor and target are excluded.
Related-table columns are analysed by hop, excluding keys, with an additional `COUNT(*)` for the number of linked rows.
Numerical values from related rows at the same hop are averaged per entity before grouping entities into cohorts.
For categorical and timestamp columns, an entity contributes fractional weight to each cohort according to the share of its related rows in that cohort.
The reported `share` and `mean` use those weights, so one entity can contribute to several cohorts.

| Column type    | Cohorts                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Numerical      | Up to 10 quantile bins                                                                                                                           |
| Categorical    | Up to ten cohorts; if there are more, the tenth and later cohorts are combined into `OTHER(*)`                                                   |
| Timestamp      | Ranges of age before the anchor time                                                                                                             |
| Missing values | Categorical values use `N/A`, which can be folded into `OTHER(*)` when cohorts are combined; missing numerical and timestamp values are excluded |

Read the printed interval boundaries when assigning values to numerical or time cohorts.
Time intervals include the lower bound and exclude the upper bound, except the final interval includes both bounds.
For classification, the analysis includes at most 30 classes, ordered by frequency.
For regression, the DataFrame's `class` is `None`; `stype` is `None` for `COUNT(*)`.

## Local subgraph sensitivity

`result.explanations.gradients` describes local sensitivity: how much an output would change per unit change in a preprocessed numerical input near its current value.
A positive gradient means that a small increase in that preprocessed input would locally increase the selected output; a negative gradient means it would decrease the output.
For classification, select the class probability you want to investigate.
For regression, select the prediction or a quantile in the response.

For the regression example on the preceding page, inspect customer 42's prediction gradients:

```python
gradients = result.explanations.gradients.to_pandas()
customer_gradients = gradients[
    (gradients["id"] == 42)
    & (gradients["output"] == "prediction")
]
print(customer_gradients)
```

`column` names the model's preprocessed numerical input, which may differ from the source column.
Categorical and datetime values can produce derived numerical columns.
A table with no numerical features has no gradient columns.
Gradient magnitudes depend on input scale, so sorting their absolute values does not produce a feature-importance ranking.

Gradients cover the scored entity and related rows in its sampled subgraph, not the labelled context examples.
A row reached by several paths appears once, with its combined sensitivity through those paths; the model does not split that value by path.
Use the returned table, key when present, row values, and anchor time to trace a suspicious input to its source.
Correct a source value only when the source record supports the correction, then rerun the prediction to measure the effect.

## Context examples

Column cohorts summarize the labelled context population analysed for the request.
They do not rank individual context examples by their influence on a prediction, and gradient records do not attribute the prediction to those examples.
For fitted sessions, the cohorts describe the pinned context rather than a newly sampled population on each scoring call.

## Interpretation checklist

* Compare cohorts for the same column, hop, and class.
* Inspect group sizes and missing-value groups alongside outcome means.
* Keep the output and preprocessed input scale visible when comparing gradients.
* Check whether a pattern persists across anchor times and related samples.
* Preserve source identity and protect sensitive values when sharing returned rows.

## Use explanations responsibly

Cohort differences describe associations in the examples, while gradients describe model sensitivity.
Neither identifies an intervention that will change a real-world outcome.
Use both alongside the schema, query, prediction time, and domain knowledge when investigating predictions.