shap.readthedocs.io

The SHAP documentation at shap.readthedocs.io organizes examples by data type and puts the full API reference in a dedicated Reference section. If you want to see working code for a specific task, start with the Examples section and pick the category that matches your data (tabular, text, image, or genomic). If you need function signatures, class definitions, and parameter details, go to Reference → API reference. The site also provides topical overviews for conceptual background, API examples for migration and usage patterns, and benchmarks for performance comparisons.

Documentation structure at a glance

The site's navigation follows this layout:

• Introduction – conceptual material
• Topical overviews – explainable AI with Shapley values, causal interpretation cautions, fairness measures
• Examples – organized by data modality
• Reference – API reference and API examples
• Benchmarks – image, tabular, text, and others
• Development – release notes and contributing guide

Finding examples for your task

The Examples section is split by data type, so you can go directly to the relevant page:

If you're unsure which explainer fits your model, the tabular examples cover the most common cases (tree-based, linear, neural, model-agnostic) and are a reasonable starting point even for non-tabular work, since the explainer API is consistent across modalities.

Finding the API reference

The Reference section contains two parts:

• API reference – organized into Explanation, explainers, plots, maskers, models, utils, and datasets
• API examples – practical usage for explainers, maskers, models, and plots, plus a guide on migrating to the new "Explanation" API

Use the API reference when you need exact parameter names, return types, or available methods. Use the API examples when you want to see how those objects are used together in a workflow.

Conceptual background before you code

The Topical overviews section covers three topics worth reading before applying SHAP:

• An introduction to explainable AI with Shapley values
• A caution about interpreting predictive models for causal insights
• Explaining quantitative measures of fairness

These give the theoretical grounding for why SHAP values behave the way they do and where interpretation can go wrong.

Installation

SHAP installs from either PyPI or conda-forge:

pip install shap

or

conda install -c conda-forge shap

When to use which section

• New to SHAP → Topical overviews, then a tabular example
• Have a specific model type → the matching Examples subpage
• Need exact function signatures → Reference → API reference
• Migrating existing code → Reference → API examples → migrating to the new "Explanation" API
• Comparing performance → Benchmarks
• Checking version changes → Development → Release notes

shap.readthedocs.io is the official documentation site for SHAP (SHapley Additive exPlanations), a game-theoretic method for explaining the output of machine learning models. It is the reference point for installing the library, understanding the method, and finding runnable examples across tabular, text, image, and genomic data. Use it when you need to interpret model predictions, choose an explainer, or look up the API.

What SHAP actually is

SHAP connects optimal credit allocation with local explanations using the classic Shapley values from game theory and their related extensions. In practice, that means it assigns each input feature a contribution to a specific prediction, so you can see which features pushed a model's output up or down.

The documentation frames this as a way to explain the output of any machine learning model, not just one family of algorithms.

What the site contains

The navigation is organized into a few clear sections:

• Introduction — conceptual material, including an introduction to explainable AI with Shapley values.
• Topical overviews — guidance on interpreting predictive models in search of causal insights, and on explaining quantitative measures of fairness.
• Examples — worked examples grouped by data type (see below).
• Reference — API reference, API examples, and benchmarks.
• Development — release notes and a contributing guide.

Examples by data type

Reference material

The API reference is split into Explanation, explainers, plots, maskers, models, utils, and datasets. There is also a dedicated page on migrating to the new "Explanation" API, plus API examples for explainers, maskers, models, and plots.

Installation

SHAP can be installed from either PyPI or conda-forge:

pip install shap

or

conda install -c conda-forge shap

Who maintains it and how it is built

The site is copyrighted by Scott Lundberg (© Copyright 2018, Scott Lundberg). It is built with Sphinx using a theme provided by Read the Docs, which is why it lives on the readthedocs.io domain.

When to use this site

• You want to install SHAP or confirm the install command.
• You need to pick an explainer for a specific model or data type.
• You want a runnable example before writing your own code.
• You are migrating existing code to the new Explanation API.
• You want to check benchmark results or read release notes.

If you only need the conceptual definition of Shapley values, the Introduction and topical overviews are the shortest path. If you already know what you want to compute, go straight to the API reference or the matching example category.

SHAP can be installed from either PyPI or conda-forge. If you use pip, run pip install shap. If you use conda, run conda install -c conda-forge shap. Both commands install the same core library; the right choice depends on how you manage your Python environment.

Install with pip

Use this when you are working in a standard Python environment or virtual environment.

pip install shap

Expected result: pip resolves and downloads the SHAP package and its dependencies, then reports a successful installation.

Install with conda

Use this when you manage packages and environments with conda.

conda install -c conda-forge shap

Expected result: conda solves the environment, installs SHAP from the conda-forge channel, and reports the packages it added or changed.

Before you install

• Confirm you have a working Python environment. SHAP is a Python package, so it needs one.
• Decide which package manager owns that environment. Mixing pip and conda in the same environment can cause dependency conflicts, so prefer the manager you already use.
• If you are unsure which environment is active, check it before installing so SHAP lands where you expect.

After installing

Once installation succeeds, the documentation points you to several ways to start using SHAP:

• Introduction and topical overviews — background on explainable AI with Shapley values, plus notes on interpreting predictive models and explaining fairness measures.
• Examples — worked examples grouped by data type: tabular (tree-based models, linear models, neural networks, model-agnostic), text (sentiment analysis, translation, text generation, summarization, question answering, language modelling, text entailment), image (classification, captioning), and genomic (DeepExplainer genomics).
• Reference — the API reference, API examples, and the guide to migrating to the new "Explanation" API.

A practical first step is to pick the example category that matches your model and data, then follow it against your own inputs.

Common installation issues

• Wrong environment: the install succeeds but import shap fails in your notebook or script. This usually means the package went into a different environment than the one running your code.
• Manager conflicts: installing with pip into a conda-managed environment (or the reverse) can produce dependency mismatches. Stick to one manager per environment.
• Missing dependencies: if the install reports unresolved dependencies, resolve those first rather than forcing the install.

Quick reference

Both routes are documented on the SHAP documentation site under Install.

SHAP explanations tell you how a model behaves, not how the world works. The documentation explicitly warns readers to "be careful when interpreting predictive models in search of causal insights," so treat any SHAP value as a statement about the model's output given its inputs — not as evidence that a feature causes the outcome. This matters most when you plan to act on an explanation: changing a feature that SHAP flags as important will only change the prediction if the model actually learned that relationship, and even then the real-world effect may differ.

The core distinction: model behavior vs. causality

SHAP (SHapley Additive exPlanations) is described as "a game theoretic approach to explain the output of any machine learning model." It "connects optimal credit allocation with local explanations using the classic Shapley values from game theory."

That framing is the source of both its strength and its main pitfall:

• What it does: fairly distributes credit for a single prediction among the input features, based on how the model responds when features are present or absent.
• What it does not do: reveal whether a feature causes the outcome, whether intervening on it would change anything, or whether the model has captured a real mechanism.

A high SHAP value for a feature means the model relied on it heavily for that prediction. It says nothing about whether that reliance is justified.

Why explanations can mislead

The explanation inherits the model's flaws

If the model learned a spurious correlation, SHAP will faithfully attribute importance to that spurious feature. The explanation is only as trustworthy as the model it describes.

Results depend on choices you make

The same model can produce different-looking explanations depending on:

• The explainer you pick — the documentation separates explainers for tree-based models, linear models, neural networks, and model-agnostic use, and each makes different assumptions.
• The background or reference data used to define "absence" of a feature.
• The data sample you explain — a pattern in one subset may not hold in another.

Because of this, an explanation is a property of the model plus the explanation setup, not a standalone fact.

Local explanations are not global rules

A single prediction's SHAP values describe that one case. Aggregating them can suggest overall trends, but a feature that dominates one prediction may be irrelevant across the dataset, and vice versa.

Practical checks before you act on an explanation

1. Ask what question you are answering. If it is "why did the model output this?" SHAP is appropriate. If it is "what will happen if we change this input?" you need causal methods, not SHAP.
2. Confirm the feature is meaningful. A feature can be important to the model yet impossible or undesirable to intervene on.
3. Check stability. Re-run the explanation with a different background sample or explainer and see whether the ranking holds.
4. Look beyond accuracy. The documentation includes topical overviews on fairness, including "Explaining quantitative measures of fairness," which is relevant when explanations inform decisions about people.

Where the documentation addresses this

The SHAP docs group guidance under Topical overviews, which include:

• An introduction to explainable AI with Shapley values
• A caution about interpreting predictive models in search of causal insights
• Explaining quantitative measures of fairness

These sit alongside Examples (tabular, text, image, genomic), an API reference, and Benchmarks. If your concern is interpretation rather than implementation, the topical overviews are the place to start; the examples show how explanations are generated, not how far they can be trusted.

Bottom line

Use SHAP to understand and debug what a model is doing. Do not use it, on its own, to claim that a feature causes an outcome or to predict the effect of changing one. When explanations feed into decisions about people, pair them with the fairness guidance and validate that the patterns you see are stable across explainers and data.

SHAP (SHapley Additive exPlanations) is described in its documentation as "a game theoretic approach to explain the output of any machine learning model." That "any" is the key claim: SHAP is not tied to one algorithm family. It connects optimal credit allocation with local explanations using Shapley values from game theory and their extensions. In practice, the documentation organizes support along two axes — model type and data type — and the explainer you choose depends on where your model falls on those axes.

Models SHAP can explain

The documentation lists example categories that map directly to model families:

The "model agnostic" category matters most for the "any model" claim. When no specialized explainer fits, a model-agnostic approach can still produce explanations, at the cost of speed and, in some cases, precision compared with a tailored explainer.

Choosing an explainer by model

The documentation's API reference groups explainers separately, and the genomic examples specifically reference DeepExplainer. This reflects the general pattern: specialized explainers exist for particular model structures, and the right one depends on your model.

• Tree ensembles (e.g., gradient-boosted trees, random forests): use a tree-specific explainer.
• Neural networks: use DeepExplainer, as shown in the genomics example.
• Linear models: covered under the tabular linear-model examples.
• Anything else: fall back to a model-agnostic explainer.

The exact class names and signatures are in the API reference; check there before assuming a specific explainer name.

Data types SHAP covers

Beyond model architecture, the documentation organizes examples by data modality:

• Tabular — tree-based, linear, neural network, and model-agnostic examples.
• Text — sentiment analysis, translation, text generation, summarization, question answering, language modelling, and text entailment.
• Image — image classification and image captioning.
• Genomic — a DeepExplainer genomics example.

So the answer to "what data can SHAP explain?" is broad: tabular rows, text sequences, image inputs, and genomic data all appear as documented examples. The constraint is not the data type itself but whether an appropriate explainer and model interface exist for your setup.

What to check before assuming support

Three practical conditions determine whether SHAP will work for your case:

1. Your model exposes outputs SHAP can wrap. Model-agnostic explainers need a callable prediction function; specialized explainers need the model in a compatible form.
2. An explainer matches your model structure. If a specialized explainer exists, it is usually the better choice; otherwise use the model-agnostic path.
3. Your data fits a documented modality. Tabular, text, image, and genomic are covered; unusual modalities may still work through the model-agnostic route but are not shown as examples.

Where to start

The documentation's Topical overviews section includes "An introduction to explainable AI with Shapley values," which is the natural entry point for understanding the mechanism before picking an explainer. From there, the Examples section lets you find the category closest to your model and data, and the API reference gives the concrete explainer, plot, masker, and model utilities.

One caution the documentation itself raises: there is a topical overview titled "Be careful when interpreting predictive models in search of causal insights." SHAP explains a model's output, not causal relationships in the world — keep that distinction in mind when acting on any explanation.