SHAP (SHapley Additive exPlanations): Computing and Reporting SHAP Values in Python

SHAP (SHapley Additive exPlanations) is an open-source Python library that assigns each input feature a contribution to a single model prediction. It is used in research to explain trained machine-learning models. This page shows how to compute SHAP values, read the standard plots, and report them in a paper so that a reader can reproduce and interpret them. It covers the machine-learning method, not the place name or slang senses of the word.

What does a SHAP value tell you?

A SHAP value tells you how much one feature moved one prediction away from the baseline. The SHAP documentation states that the values for a prediction always sum to the difference between the baseline (expected) model output and the current model output. The baseline is the expected output over the background data and is stored as base_values on the result object.

The method was introduced by Lundberg and Lee in “A Unified Approach to Interpreting Model Predictions” (NIPS 2017, arXiv:1705.07874), which frames it as an additive feature-importance measure with a unique solution under a set of desirable properties and shows that it unifies six existing methods. In practice a SHAP value is relative to a chosen background and a chosen output scale. As an editorial interpretation, a large SHAP value shows that the model relied on a feature, not that changing the feature would change the real-world outcome.

What it is used for in research

• Local explanation: why the model produced this output for this one record (waterfall plot).
• Global summary: which features drive predictions across a dataset (beeswarm and bar plots).
• Feature-effect inspection: how a single feature’s contribution varies with its value (scatter plot).

For the wider landscape of explanation methods and their regulatory context, see Explainable AI (XAI) Explained. For background on the models being explained, see What Is Machine Learning?

Install or access (official source only)

The documentation at shap.readthedocs.io gives two install routes:

pip install shap
conda install -c conda-forge shap

To keep the installation reproducible, record the installed version of the library alongside your other dependencies; see Sharing a Reproducible Conda Environment.

Step-by-step: compute and plot SHAP values

The steps below follow the official “An introduction to explainable AI with Shapley values” notebook. model is your fitted model, X is the feature table you want to explain, and X100 is a background sample of that data (the notebook names it X100).

1. Import the library. import shap
2. Build an explainer. For a tree model such as XGBoost the notebook uses explainer_xgb = shap.Explainer(model_xgb, X100). For a generic model, pass the prediction function: explainer = shap.Explainer(model.predict, X100).
3. Compute the explanations. shap_values = explainer(X). The result carries the values and base_values.
4. Explain one prediction. shap.plots.waterfall(shap_values[sample_ind], max_display=14), where sample_ind is the row index.
5. Summarise all predictions. shap.plots.beeswarm(shap_values) and shap.plots.bar(shap_values).
6. Inspect one feature. shap.plots.scatter(shap_values[:, "MedInc"]), replacing "MedInc" (a column of the notebook’s housing data) with your own column name. The notebook also colours the points with shap.plots.scatter(shap_values_xgb[:, "MedInc"], color=shap_values).

SHAP TreeExplainer

shap.TreeExplainer(model, data=None, model_output='raw', feature_perturbation='auto', ...) is the tree-specific explainer. Per its documentation page it supports XGBoost, LightGBM, CatBoost, Pyspark and most tree-based scikit-learn models. Its shap_values() method returns a NumPy array of shape (samples, features), or (samples, features, outputs) for multi-output models.

Output and how to read it

Plot	What it shows (per the SHAP documentation)
Waterfall	How each feature moves one prediction from the baseline to the model output.
Beeswarm	One point per instance for each feature, coloured by the feature’s value.
Bar	By default, the mean absolute SHAP value per feature. Other transforms, such as shap_values.abs.max(0), give a different importance view.
Scatter	One feature’s SHAP value against its value; the notebook describes this as tracing a mean-centred version of partial dependence.

Because the bar plot’s ranking depends on the transform, two papers that both say “SHAP importance” can rank features differently. Name the transform.

Reporting SHAP in a paper

The checklist below is an editorial synthesis of the settings the SHAP documentation describes as changing the numbers. For model-reporting guidelines in health AI, see AI Reporting Guidelines; for the wider practice, see computational reproducibility.

• Library and explainer. State the shap version and which explainer you used (Explainer, TreeExplainer).
• Background data. State what the background sample was and how large. The baseline is the expected output over it.
• Feature perturbation. For TreeExplainer, auto uses interventional when background data is given and tree-path-dependent otherwise. Say which applied.
• Output scale. State model_output. The probability and log_loss options are available only with interventional perturbation. XGBoost’s raw output is log-odds, so say whether values are in log-odds or probability units.
• Which samples. State whether SHAP values were computed on training, validation or test data.
• Importance transform. State mean absolute value, maximum absolute value or another summary.
• Interpretation. Describe the values as explaining the model, not the underlying mechanism.

Troubleshooting

Additivity check fails

TreeExplainer.shap_values() has check_additivity=True by default, which validates that the SHAP values sum to the model output (the margin). A failure means the values and the model output are not on the same basis. Check that the predictions and the SHAP values come from the same samples in the same order.

Values do not match predicted probabilities

For XGBoost the raw output is log-odds. To compare with probabilities, apply a logistic transform such as scipy.special.expit to the summed output.

Two arrays come back for a classifier

scikit-learn classifiers return values for both classes (shape ending in 2) and expected_value has length 2. Select the class you are reporting and say which it is.

Deprecated argument

The approximate argument on the TreeExplainer constructor is deprecated; pass it to shap_values() instead.

Free alternatives

Tool	What it is (per its repository)	License
LIME (marcotcr/lime)	Explaining the predictions of any machine learning classifier.	BSD-2-Clause
InterpretML (interpretml/interpret)	Fit interpretable models. Explain blackbox machine learning.	MIT

Descriptions and licenses as listed in each GitHub repository, checked 2026-11-07.

FAQ

What does a SHAP value tell you?

It gives one feature’s contribution to one prediction relative to the baseline; the contributions add up to the gap between the baseline and the model output. It describes the model, not causation.

What is SHAP used for in machine learning?

Explaining individual predictions and summarising which features a trained model relies on, using the waterfall, beeswarm, bar and scatter plots above.

How do I install SHAP?

Run pip install shap or conda install -c conda-forge shap, as given in the official documentation.

Sources

• SHAP documentation (checked 2026-11-07): https://shap.readthedocs.io/en/latest/
• An introduction to explainable AI with Shapley values (checked 2026-11-07): https://shap.readthedocs.io/en/latest/example_notebooks/overviews/An%20introduction%20to%20explainable%20AI%20with%20Shapley%20values.html
• shap.TreeExplainer reference (checked 2026-11-07): https://shap.readthedocs.io/en/latest/generated/shap.TreeExplainer.html
• Lundberg, S. M. and Lee, S.-I. (2017). A Unified Approach to Interpreting Model Predictions. NIPS 2017 (checked 2026-11-07): https://arxiv.org/abs/1705.07874
• LIME repository (checked 2026-11-07): https://github.com/marcotcr/lime
• InterpretML repository (checked 2026-11-07): https://github.com/interpretml/interpret