TreeIG documentation#

TreeIG is a Python package for Integrated Gradients feature attribution on supported numeric tree models. Install and import it as treeig. Given a fitted model, a baseline point or weighted background, and evaluation rows, TreeIG returns feature contributions and completeness diagnostics.

TreeIG computes exact Integrated Gradients for supported numeric tree models. A tree’s gradient is zero almost everywhere; its integrated gradient is not.

Check supported models before choosing an interface. TreeIG uses exact structural split crossings; TreeIGNumeric is a separately selected numerical fallback. Exact classification explains raw margins or logits. Exact parsing requires finite numeric inputs and does not support categorical splits or missing-value routing. Installing the CatBoost extra does not add an exact CatBoost backend.

Tree ensembles are piecewise constant, so \(\nabla F = 0\) except on a measure-zero set of split boundaries. Numerical Integrated Gradients therefore recovers approximately nothing, which is why IG has largely been confined to differentiable models.

The pointwise gradient is not the full derivative. In the distributional sense, \(F'\) carries an impulse at each split boundary whose integral equals the prediction jump there.

A prediction step, its derivative impulse, and its integrated contribution

The top panel shows a single prediction step; the middle shows its derivative as an impulse at the split; the bottom shows the accumulated contribution. Integrating across the split recovers the prediction change.

TreeIG enumerates the boundaries crossed by the straight-line path from baseline to observation, assigns each jump to its split feature, and sums across trees. No quadrature and no sampling are involved, and completeness

\[\sum_j \phi_j = F(x) - F(x_0)\]

holds to the floating-point precision of the fitted model’s own arithmetic. Weighted baseline distributions are supported directly.

The CPU TreeIG class is the main interface. Start with a runnable example, then choose the baseline distribution and output scale that express the comparison you want to explain.

The method is developed in Ludger Hentschel’s TreeIG: Exact Integrated Gradients for Tree-Based Models. It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in Axiomatic Attribution for Deep Networks (ICML 2017).

Explore the guide#

For automated readers, llms.txt maps the guides, complete examples, and rendered API reference.

Read getting started, baselines, supported models, and worked examples first. For more detail, see results and plotting, loss attribution, numerical conventions, TreeIGNumeric, and performance.