UnifiedIG documentation#
UnifiedIG is a Python package for Integrated Gradients feature attribution
across supported scikit-learn, tree, PyTorch, JAX, and TensorFlow/Keras models.
Install and import it as unifiedig. Given a fitted model, a reference baseline
or background distribution, and observations, it returns feature contributions,
baseline outputs, and completeness diagnostics.
Integrated Gradients is the Aumann–Shapley value. UnifiedIG computes it across the model families used in practice.
UnifiedIG computes one estimand across linear models, pipelines, SVMs, MLPs, gradient-boosted trees, random forests, PyTorch, JAX, and TensorFlow. It selects an exact route wherever model structure permits, avoiding both sampling and quadrature; reports the completeness residual per sample wherever it does not; and explains every model against an explicit, auditable reference distribution.
Other attribution libraries typically dispatch to a different algorithm per model family. In SHAP, tree models use TreeSHAP, neural networks use DeepSHAP, and the remainder use KernelSHAP. These estimate different quantities under different assumptions, so attributions from different explainers are not directly comparable: an apparent disagreement between two models may reflect the explainers rather than the models.
Give UnifiedIG a fitted model and a reference background:
import unifiedig as uig
explanation = uig.Explainer(model, background)(X)
Check the model/backend matrix before choosing a route. Classification explains scores or logits; multiclass scores are centered. Exactness depends on model structure, and numerical fallbacks require explicit opt-in. See classification conventions and accuracy checks. A small completeness residual checks reconstruction; it does not by itself establish accurate individual allocations.
The result contains feature contributions, baseline outputs, and completeness
diagnostics. Convert it with explanation.to_shap() to use
SHAP’s waterfall, beeswarm, bar, and scatter plots.
Read how the computation works for the tree and gradient machinery, and baselines and CBaseline for the reference distribution. The same prediction-attribution interface brings them together.
Discrete and continuous value theory#
The Shapley value is the unique attribution satisfying efficiency, symmetry, dummy, and additivity for cooperative games with a finite player set. Continuous features are not a finite player set. Applying the discrete theory to them requires a value function \(v(S)\) specifying the model output when a subset of features is absent — a modeling choice the axioms do not determine, with conditional and interventional conventions yielding different answers — followed by an approximation over \(2^p\) coalitions.
The corresponding theory for non-atomic games yields the Aumann–Shapley value, which for differentiable \(F\) is the integral of \(\nabla F\) along the straight-line path (Aumann and Shapley, 1974; Sundararajan, Taly and Yan, 2017). Read distributionally, that integral is defined for piecewise-constant \(F\) as well, where \(\nabla F\) carries an impulse at each split boundary (Hentschel, 2026b). Tree ensembles therefore belong inside the same theory rather than requiring a separate method.
The construction requires a reference distribution and a path. Both are stated explicitly — the reference constructed from observed data to a chosen output \(f_0\) (Hentschel, 2026a), the path fixed by symmetry (Friedman, 2004) — and the cost is linear in the number of path nodes rather than exponential in the number of features.
Explain your first model#
Start with installation and a complete example. Then learn how to choose a baseline and interpret the feature contributions.
What you need |
Where to go |
|---|---|
Check whether your model is supported |
|
Explain original or transformed pipeline features |
|
Use PyTorch, JAX, or TensorFlow |
|
Turn contributions into familiar SHAP plots |
|
Follow a complete calculation |
|
Assess accuracy or investigate a warning |
The examples are included from executable files and checked during documentation builds. For more detail, read the methodology, output semantics, or API reference.
UnifiedIG also supports loss attribution when observed targets are available. This additional capability is covered at the end of the user guide.
User guide
Reference and development