TreeSHAP is the algorithm that computes SHAP values for tree-based models exactly and fast. It is what you get from shap.TreeExplainer, and it is the reason feature attribution is routine for gradient boosted models while it remains expensive almost everywhere else. Point it at an XGBoost, LightGBM, CatBoost, random forest, or scikit-learn tree model and it returns a signed contribution per feature per prediction.
The speed comes from using the model’s structure. Computing a Shapley value by definition means evaluating the model on every subset of features, which is 2 to the power of the feature count and hopeless past 20 or so features. Sampling approximations such as Kernel SHAP get around that with many extra model evaluations and some variance. TreeSHAP instead walks the trees directly. Because a tree already encodes how the data splits and how many training samples flow down each path, each feature’s contribution can be accumulated during a traversal. Cost becomes polynomial in the size of the ensemble, roughly trees times leaves times depth squared, rather than exponential in features.
That is the whole value proposition: exact values, at a cost you can pay on every prediction in production rather than on a sample of 200 rows.
Build better agents with Arize
Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.
Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.
Key takeaways
- TreeSHAP computes exact Shapley values for tree ensembles by traversing tree structure instead of enumerating feature subsets.
- Cost is polynomial in trees, leaves, and depth, which makes per-prediction attribution affordable at production volume.
- It has two perturbation modes,
tree_path_dependentandinterventional, and they answer different questions and return different numbers. - Values are additive in the model’s raw output space, so for a classifier they sum toward log-odds and not toward a probability.
- Exact means exactly the Shapley value under the chosen assumptions. It does not mean the attribution matches how you would explain the outcome, especially with correlated features.
How the traversal works
For one input, follow the path the model would take. At every internal node, one branch is the one the input takes and one is the branch it does not. TreeSHAP tracks how much weight belongs to each branch and how many feature subsets would route down it, accumulating each feature’s marginal contribution in a single pass per tree. Sum over the ensemble for one value per feature.
The output has a fixed structure worth knowing:
- One signed value per feature per row. Positive pushed the prediction up, negative pushed it down.
- A base value, which is the expected model output over the reference data. Every explanation is stated relative to it.
- Local accuracy: the values plus the base value equal the model’s output for that row. This is a guarantee of the method, not a coincidence, and it is what makes SHAP attributions aggregate cleanly into the global and cohort views described in global, cohort, and local model explainability.
shap.TreeExplainer also exposes pairwise interaction values, which split contributions between individual features and feature pairs at considerably higher cost.
The two modes, and why your numbers changed
shap.TreeExplainer takes a feature_perturbation argument, and the choice matters more than most people realize.
tree_path_dependent uses the sample counts stored in the trees themselves to decide how missing features are handled. It needs no background dataset, which makes it fast and convenient. It also means the reference distribution is whatever the model saw at training time, encoded in the tree paths.
interventional requires a background dataset and breaks the dependence between features by drawing replacement values from that background. It answers a cleaner question about what happens if a feature’s value is intervened on, and it is the mode that supports attributing in probability space for some model types.
The two modes disagree on correlated features, sometimes substantially. Neither is wrong. If you upgraded a library version and your attributions shifted, or a colleague’s plot does not match yours, the default mode or the background data is usually the difference. Record which mode produced any explanation you ship.
Where TreeSHAP surprises people
Log-odds, not probability. For binary classifiers the default output space is log-odds, not probability.
Correlated features distribute credit oddly. Group correlated features and interpret the group.
Exact is a claim about the computation. Attribution describes the model, not the world.
TreeSHAP against the other explainers
From this page the rule is short. Tree ensembles get TreeSHAP. Other model classes use Kernel SHAP or Deep SHAP depending on access.
Why this still matters in agent systems
Gradient boosted trees did not go anywhere. They sit inside modern AI systems as rankers that order retrieval candidates, as classifiers that route a request to one tool or model, as risk scores that gate an action an agent wants to take. When an agent behaves oddly and the trace shows a routing decision that looks wrong, the routing model is usually a tree ensemble, and TreeSHAP explains that specific decision in milliseconds.
Be precise about the division of labor. Attribution explains the tabular component; it says nothing about the language model. For the rest of the run you need tracing and evaluating AI agents and the practices in the AI agent handbook. For guidance on testing agent behavior, see agent evaluation.
FAQ
Is TreeSHAP exact or approximate?
Exact, in the sense that it computes the Shapley values defined by the model and the chosen perturbation mode without sampling error. Rerun it and you get identical numbers. That exactness is about the calculation, not about whether the explanation matches your mental model of the domain.
How is TreeSHAP different from Kernel SHAP?
TreeSHAP uses the internal structure of tree models to compute values in polynomial time. Kernel SHAP treats the model as a function it can only call, perturbs inputs, and fits a weighted linear model to approximate the values. Kernel SHAP works on anything and is orders of magnitude slower with sampling variance, so use TreeSHAP whenever the model is tree based.
Which libraries does TreeSHAP support?
shap.TreeExplainer handles XGBoost, LightGBM, CatBoost, and scikit-learn tree models including decision trees, random forests, and gradient boosting. Support and defaults vary by version, so confirm which feature_perturbation mode is active in the version you have pinned.
Why do my TreeSHAP values not add up to a probability?
Because attribution happens in the model’s raw output space, which for most boosted classifiers is log-odds. The values plus the base value equal the raw margin, and the margin passes through a link function to become a probability. Some configurations support attributing directly in probability space with a background dataset.
Why does TreeSHAP give a feature credit when the model seems to ignore it?
Usually correlation. If a feature is highly correlated with one the model splits on heavily, the Shapley definition can assign it credit even though removing it would change little. Interpreting correlated features as a group, rather than individually, avoids the wrong conclusion. Every attribution method has some version of this problem.
