Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions skills/relational/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,36 @@ A ranking is a call per candidate and a forecast a call per step; an explanation
Endpoint support and task restrictions are described in
[`references/beyond-one-answer.md`](references/beyond-one-answer.md).

An explanation is kept out of `to_pandas()`.
The gradients are on `result.explanations.gradients`, a mapping from each row's key to its entry.
The key is the entity's `id` when IDs are unique, or `row_index` when IDs are missing or repeated.
Forecast keys add the step: `(id, forecast_step)` or `(row_index, forecast_step)`.
One entry covers the entity's own row and every related row gathered for it, each under its table's name in `related`:

```python
entry = result.explanations.gradients[1] # the entity whose id is 1
entry['outputs'] # the explained scores, in order
entry['related']['users'] # the entity's table; the entity's own row is at hop 0
block = entry['related']['orders'] # one block per related table
block['rows'] # each row's values as sent
block['keys'] # each row's key, when the table has a key of its own
block['columns'] # the model's preprocessed numerical columns
block['gradients'] # [output][row][column]
result.explanations.gradients.to_pandas() # one line per (entity, table, row, output, column)
analysis = result.explanations.columns
if analysis is not None:
cohorts = analysis.to_pandas() # one line per (table, hop, column, cohort, class)
```

Column explanations are on `result.explanations.columns`.
This client computes them from the labelled context `materialize()` gathered; the endpoint does not.
Column explanations group labelled context examples by input values and summarize their observed outcomes.
They describe associations, not how much a column contributed to an individual prediction.
See [beyond-one-answer.md](references/beyond-one-answer.md) for interpreting `mean`, `class`, and `share`.
`result.explanations.columns` is `None` unless `explanation` was asked for.
It can also be `None` when statistics are unavailable, so check it before calling `to_pandas()`.
Gradients and column explanations both need a deployment that serves `explanation`.

## Asking the same context more than once

`fit()` uploads a context once and pins it in the endpoint's memory; every
Expand Down
40 changes: 40 additions & 0 deletions skills/relational/references/beyond-one-answer.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,48 @@ Source keys can identify related rows; synthetic transport keys are not user key
Only scored rows and their sampled related rows receive gradients, not the labelled context examples.
A gradient measures sensitivity to a preprocessed feature, not a causal effect.

```python
entry = result.explanations.gradients[1] # the entity whose id is 1
block = entry['related']['orders'] # one block per table, by name
block['rows'][0] # the first row's values, as sent
block['gradients'][0][0] # first output, first row: one gradient per name in block['columns']
```

Unique prediction IDs key the collection; missing/repeated IDs use `row_index`.
Forecast keys include the step, and merging preserves distinct rows and steps.
`result.explanations.gradients.to_pandas()` flattens entries with table, hop, related-row identity, output and column.
`EXPLAIN` ranking is rejected before gathering; explanations requested later through `outputs` are checked before prediction.

```python
result.explanations.gradients[(1, 2)] # on a forecast: entity 1, step 2
result.explanations.gradients.to_pandas() # id, forecast_step on a forecast, table, hop, key, row, output, column, gradient
```

Column explanations are on `result.explanations.columns`, which is `None` unless `explanation` was asked for.
This client computes them from the labelled context `materialize()` gathered; the endpoint does not.
That context includes the rows held back from the call because they carried the answer.
Column explanations group the labelled entities into cohorts by each column of each table they reach.
Key columns and the columns a relationship joins on are left out.
Each table also gets `COUNT(*)`, how many of its rows each entity reaches.
An entity whose rows fall in several cohorts is divided among them in proportion to its rows: a user with one category-A order and nine category-B orders counts as 0.1 of an entity in cohort A and 0.9 in cohort B.
`share` and `mean` are computed over these fractional weights, so they measure how the entities' rows are associated with each cohort, not the plain rate among entities that ever touched it.
`share` is the fraction of the population included in that column analysis that belongs to the cohort; `share: 0.2` means 20%.
Comment thread
JGagacheva marked this conversation as resolved.
Resolved
Missing numerical values are excluded, so this population can differ between columns.
Consider how well each cohort is represented before interpreting differences; a small share does not necessarily mean a small absolute sample size.
For regression, `mean` is the average observed target within the cohort, in the target's units, and `class` is `None`.
For example, for an order total in dollars, `mean: 120` means an average observed total of $120.
For classification, `class` names the target label and `mean` is the proportion of the cohort with that observed label.
For example, `class: "churned"` and `mean: 0.3` means a weighted 30% of the cohort churned; it is not an individual prediction's probability.
Compare means within the same column and class, and the same table and hop.
These are associations in the context, not gradients and not causes.
A forecast gets one analysis, over the context of every step.
If the statistics cannot be computed, `result.explanations.columns` is `None` and a warning says so; the predictions still come back.

```python
analysis = result.explanations.columns
if analysis is not None:
cohorts = analysis.to_pandas() # table, hop, column, stype, cohort, class, share, mean, score
cohorts[cohorts['table'] == 'orders'] # the cohorts of each column of orders
```

See [the result contract](../../../docs/reference/prediction-output.md).
26 changes: 26 additions & 0 deletions skills/tabular/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,32 @@ The optional Python model runtime also supports them.
`EXPLAIN` adds explanation output without dropping ordinary outputs; `outputs=[]` remains invalid.
See [the result contract](../../docs/reference/prediction-output.md).

```python
# With missing or repeated IDs, keys are row_index values.
entry = result.explanations.gradients[0] # row_index 0 under that assumption
entry['outputs'] # the explained scores, in order
entry['instance']['columns'] # the model's preprocessed numerical columns
entry['instance']['gradients'] # [output][column]
result.explanations.gradients.to_pandas() # one line per (row, output, column)
analysis = result.explanations.columns
if analysis is not None:
cohorts = analysis.to_pandas() # one line per (column, cohort, class)
```

Column explanations are on `result.explanations.columns`, which is `None` unless `explanation` was asked for or when statistics are unavailable, so check it before calling `to_pandas()`.
This client computes them from the labelled rows sent with the request; the endpoint does not.
Column explanations group the labelled rows into cohorts by each column, leaving out the key, the target, and timestamps.
`share` is the fraction of the population included in that column analysis that belongs to the cohort; `share: 0.2` means 20%.
Missing numerical values are excluded, so this population can differ between columns.
Consider how well each cohort is represented before interpreting differences; a small share does not necessarily mean a small absolute sample size.
For regression, `mean` is the average observed target within the cohort, in the target's units, and `class` is `None`.
For example, for an order total in dollars, `mean: 120` means an average observed total of $120.
For classification, `class` names the target label and `mean` is the proportion of the cohort with that observed label.
For example, `class: "churned"` and `mean: 0.3` means 30% of the cohort's labelled examples churned; it is not an individual prediction's probability.
Compare means within the same column and class.
These are associations in the labelled rows, not gradients and not causes.
A session makes them once, at `fit()`, from the context it pins.

## The whole interface

```python
Expand Down