Reading an explanation#

Prediction contributions#

For a scalar regression prediction, a positive contribution increases the prediction relative to the chosen baseline distribution; a negative contribution decreases it. These are contributions to the fitted model’s output, not causal effects or measures of model correctness.

explanation = uig.Explainer(model, background)(X_eval)
reconstructed = explanation.base_values + explanation.values.sum(axis=1)

For tabular scalar outputs, values has shape (samples, features) and base_values has shape (samples,). Multi-output explanations add a trailing output axis: (samples, features, outputs) and (samples, outputs). Framework inputs can have additional sample dimensions; sum all feature dimensions for completeness in that case. See the exact shape contract.

data and feature_names describe the chosen attribution space. DataFrame column names are preserved for tabular inputs. output_names labels class or output coordinates; attribute_after records a selected pipeline boundary.

The path attribution in one equation#

For an observation \(x\), one baseline \(b\), and a scalar model output \(f\), define the straight-line path \(\gamma(\alpha)=b+\alpha(x-b)\). Feature \(j\) receives

\[ \mathrm{IG}_j(x;b) = (x_j-b_j)\int_0^1 \frac{\partial f}{\partial x_j}\bigl(\gamma(\alpha)\bigr)\,d\alpha. \]

The input difference multiplies the model’s sensitivity to that feature, averaged along the path. Summing across features reconstructs \(f(x)-f(b)\) when the path integral is valid and evaluated accurately. For a baseline distribution, UnifiedIG averages these complete path attributions using the baseline weights; the reference output becomes the weighted mean of \(f(b)\).

The displayed derivative formula describes smooth model paths (including piecewise-smooth paths where the usual integration conditions hold). TreeIG accounts explicitly for split-boundary jumps in discontinuous tree outputs; ordinary gradients alone would miss them. See how trees fit the path calculation.

The closing loss chapter uses the same path and adds the loss derivative inside the integral.

Classification uses scores#

UnifiedIG attributes classification scores, not probabilities. We recommend against probability attribution for explaining classification decisions because probability links compress and couple score changes. The classification guide explains why probability links change the attribution question, why multiclass scores are centered, and how to choose a reference on the correct scale.

Model output	What is reconstructed
Binary sklearn classifier	Its decision margin or logit, oriented toward `classes_[1]`
Multiclass classifier	Each score minus the mean score across classes
Two-score framework model	`score[1] - score[0]`
Framework vector with at least three class scores	The centered score vector
Probability-only supported tree classifier, explicit numerical fallback	Derived log odds or centered log probabilities

A positive binary contribution supports the second class on the score scale; it is not a percentage-point probability change. For generic differentiable functions, supply raw scores or logits rather than probabilities. The model matrix describes restrictions and exceptions.

Vector framework outputs default to classification. Set output_kind="regression" when they represent multiple regression predictions. Known sklearn and tree estimators declare their own semantics, so this override is unnecessary and rejected for those models.

Compare two classes#

A multiclass explanation preserves all centered class coordinates. To explain one class against another without recomputing paths:

contrast = explanation.contrast(0, 1)

Integer arguments select output positions; strings select output names. The result explains the first score minus the second. Use the multiclass example for a full calculation.

Check completeness#

Inspect explanation.max_abs_completeness_error. A small residual checks that the sum reconstructs the chosen output. It does not prove individual feature allocations are accurate, especially for approximate tree crossing detection. Read numerical accuracy before interpreting a warning.

Plot with SHAP#

Install unifiedig[shap], convert the result, and use SHAP’s plotting API:

import shap

plot_values = explanation.to_shap()
shap.plots.waterfall(plot_values[0])
shap.plots.beeswarm(plot_values)

Follow Plot with SHAP for a complete example, a visual gallery, plot selection, multiclass slicing, and saving labeled figures.

This snippet assumes a scalar tabular explanation. For multiclass results, convert a pairwise contrast first. Conversion supplies a plotting container; it does not turn Integrated Gradients into Shapley values.

A prediction explanation does not measure prediction quality#

A positive prediction contribution tells you that the feature raises the explained output relative to the reference. Whether that helps depends on the observed target and the loss function. The closing loss-attribution chapter uses the same reference paths to answer that second question, explaining the model composed with the loss while holding each target fixed.