Understand Explanations

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 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?.

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.

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.

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:

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.