:orphan:

Examples & Tutorials
====================

A collection of examples and tutorials demonstrating how to use ``shapiq``
for computing and visualizing Shapley interactions.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Approximators
=============

Examples demonstrating each approximator in ``shapiq`` on the same
synthetic cooperative game. All examples use a lightweight callable
game with 8 players so they execute in under a second.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Stratified SVARM for Shapley value approximation using SVARM :footciteKolpaczki.2024a.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_svarm_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_svarm`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SVARM</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Regression-based Shapley value approximation using KernelSHAP :footciteLundberg.2017.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_kernelshap_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_kernelshap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">KernelSHAP</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Owen sampling for Shapley value approximation using OwenSamplingSV.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_owen_sampling_sv_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_owen_sampling_sv`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">OwenSamplingSV</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Unbiased Monte Carlo variant of KernelSHAP using UnbiasedKernelSHAP.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_unbiased_kernelshap_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_unbiased_kernelshap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">UnbiasedKernelSHAP</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Stratified sampling for Shapley value approximation using StratifiedSamplingSV.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_stratified_sampling_sv_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_stratified_sampling_sv`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">StratifiedSamplingSV</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Permutation-based Shapley value approximation using PermutationSamplingSV.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_permutation_sampling_sv_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_permutation_sampling_sv`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PermutationSamplingSV</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="k-additive SHAP approximation using kADDSHAP :footcitePelegrina.2023.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_kadd_shap_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_kadd_shap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">kADDSHAP</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Proxy-based SPEX approximation using ProxySPEX :footciteButler.2025.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_proxyspex_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_proxyspex`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ProxySPEX</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Regression-based k-SII approximation using KernelSHAPIQ :footciteFumagalli.2024.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_kernelshapiq_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_kernelshapiq`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">KernelSHAPIQ</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Faithful Banzhaf Interaction Index via regression using RegressionFBII.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_regression_fbii_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_regression_fbii`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">RegressionFBII</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Faithful Shapley Interaction Index via regression using RegressionFSII :footciteFumagalli.2023.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_regression_fsii_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_regression_fsii`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">RegressionFSII</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Permutation-based SII/k-SII approximation using PermutationSamplingSII.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_permutation_sampling_sii_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_permutation_sampling_sii`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PermutationSamplingSII</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="General Monte Carlo approximator for any-order interactions using SHAPIQ :footciteMuschalik.2024a.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_shapiq_approximator_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_shapiq_approximator`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SHAPIQ Approximator</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Permutation-based STII approximation using PermutationSamplingSTII.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_permutation_sampling_stii_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_permutation_sampling_stii`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PermutationSamplingSTII</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Stratified Monte Carlo with coalition-size and intersection stratification using SVARMIQ :footciteKolpaczki.2024a.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_svarmiq_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_svarmiq`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SVARMIQ</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Faster variant of KernelSHAPIQ that does not converge to true SII, using InconsistentKernelSHAPIQ.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_inconsistent_kernelshapiq_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_inconsistent_kernelshapiq`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">InconsistentKernelSHAPIQ</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Proxy model-based interaction approximation using ProxySHAP.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_proxyshap_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_proxyshap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ProxySHAP</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Sparse Explainer via Fourier transforms using SPEX :footciteKang.2025.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_spex_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_spex`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SPEX</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Proxy model-based Shapley value approximation using RegressionMSR.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_regression_msr_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_regression_msr`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">RegressionMSR</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Exact computation of Shapley values and interaction indices for small games using ExactComputer.">

.. only:: html

  .. image:: /auto_examples/approximators/images/thumb/sphx_glr_plot_exact_computer_thumb.png
    :alt:

  :doc:`/auto_examples/approximators/plot_exact_computer`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">ExactComputer</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Basics
======

Introductory examples covering core ``shapiq`` concepts: Shapley value computation,
custom cooperative games, and parallel computation.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to speed up shapiq explanations using parallel computation via joblib. We use a simple synthetic game to keep runtime short.">

.. only:: html

  .. image:: /auto_examples/basics/images/thumb/sphx_glr_plot_parallel_computation_thumb.png
    :alt:

  :doc:`/auto_examples/basics/plot_parallel_computation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Parallel Computation with joblib</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to define custom cooperative games and use them with shapiq. We model a simple cooking game and show how to query the value function, precompute all coalition values, and save/load them.">

.. only:: html

  .. image:: /auto_examples/basics/images/thumb/sphx_glr_plot_custom_games_thumb.png
    :alt:

  :doc:`/auto_examples/basics/plot_custom_games`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Defining Custom Games</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example introduces cooperative game theory and shows how to compute Shapley values with shapiq -- both exactly and via approximation -- and how to apply them for explainable AI (XAI).">

.. only:: html

  .. image:: /auto_examples/basics/images/thumb/sphx_glr_plot_sv_calculation_thumb.png
    :alt:

  :doc:`/auto_examples/basics/plot_sv_calculation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Computing Shapley Values</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Game Theoretic Concepts
=======================

Examples exploring game-theoretic concepts beyond Shapley values,
such as the Core and the Egalitarian Least Core.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example introduces the game-theoretic concept of the core and the egalitarian least core (ELC), and shows how to compute them with ExactComputer.">

.. only:: html

  .. image:: /auto_examples/game_theory/images/thumb/sphx_glr_plot_core_thumb.png
    :alt:

  :doc:`/auto_examples/game_theory/plot_core`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Core: A Different View on Explanation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Language Models
===============

Examples demonstrating how to explain language model predictions
using ``shapiq`` with token-based cooperative games.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to explain a sentiment classifier using shapiq. Each token in the input text becomes a player in a cooperative game, and Shapley values quantify each token&#x27;s contribution to the predicted sentiment.">

.. only:: html

  .. image:: /auto_examples/language/images/thumb/sphx_glr_plot_sentiment_analysis_thumb.png
    :alt:

  :doc:`/auto_examples/language/plot_sentiment_analysis`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Explaining Sentiment Analysis</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Nearest Neighbor Models
=======================

Examples for data valuation using efficient explanations of nearest-neighbor models.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This notebook shows how explainers of nearest-neighbor (NN) models can be used for Data Valuation, the task of evaluating the usefulness of individual training data points in classification problems. When explaining NN models, a game is defined by first choosing an explanation point x_\text{explain} and class y_\text{explain}; the training data points \mathcal{D} := \mathcal{X} \times \mathcal{Y} are the game&#x27;s players, and the definition of the utility \nu(S) of a coalition S \subseteq \mathcal{D} is based on the probability of the model predicting class y_\text{explain} on x_\text{explain} if it&#x27;s training data were limited to S.">

.. only:: html

  .. image:: /auto_examples/nearest_neighbor/images/thumb/sphx_glr_plot_nn_data_valuation_thumb.png
    :alt:

  :doc:`/auto_examples/nearest_neighbor/plot_nn_data_valuation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Data Valuation with Nearest Neighbor Explainers</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Tabular Models
==============

Examples for explaining tabular machine-learning models with ``shapiq``,
including scikit-learn, XGBoost, and TabPFN models.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use ConditionalImputer for conditional (observational) imputation when computing Shapley interactions. Conditional imputation respects feature dependencies, unlike marginal (interventional) imputation.">

.. only:: html

  .. image:: /auto_examples/tabular/images/thumb/sphx_glr_plot_conditional_imputer_thumb.png
    :alt:

  :doc:`/auto_examples/tabular/plot_conditional_imputer`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Conditional Data Imputation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to compute second-order Shapley Interaction Index (SII) values for a scikit-learn Random Forest on the California housing dataset.">

.. only:: html

  .. image:: /auto_examples/tabular/images/thumb/sphx_glr_plot_shapiq_scikit_learn_thumb.png
    :alt:

  :doc:`/auto_examples/tabular/plot_shapiq_scikit_learn`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SHAP-IQ with scikit-learn</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="TabPFN is a foundation model for tabular data that uses in-context learning -- fitting is just storing the training data, and inference contextualises new inputs against that context.">

.. only:: html

  .. image:: /auto_examples/tabular/images/thumb/sphx_glr_plot_explaining_tabpfn_thumb.png
    :alt:

  :doc:`/auto_examples/tabular/plot_explaining_tabpfn`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Explaining TabPFN</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Tree Models
===========

Examples demonstrating TreeSHAP-IQ for explaining tree-based models,
including LightGBM and custom tree structures.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use TreeExplainer to explain a custom tree model built from scratch using the Play Tennis dataset.">

.. only:: html

  .. image:: /auto_examples/trees/images/thumb/sphx_glr_plot_treeshapiq_custom_tree_thumb.png
    :alt:

  :doc:`/auto_examples/trees/plot_treeshapiq_custom_tree`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">TreeSHAP-IQ for Custom Tree Models</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates TreeExplainer on a LightGBM model trained on the bike-sharing dataset. TreeSHAP-IQ computes exact Shapley interaction values in linear time for tree ensembles.">

.. only:: html

  .. image:: /auto_examples/trees/images/thumb/sphx_glr_plot_treeshapiq_lightgbm_thumb.png
    :alt:

  :doc:`/auto_examples/trees/plot_treeshapiq_lightgbm`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">TreeSHAP-IQ for LightGBM</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Vision Models
=============

Examples demonstrating how to explain image classification models
using ``shapiq`` with image patch-based cooperative games.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to explain an image classification by a Vision Transformer (ViT) using shapiq. The image is divided into patches and each patch becomes a player in a cooperative game. Shapley values then quantify how much each patch contributes to the predicted class.">

.. only:: html

  .. image:: /auto_examples/vision/images/thumb/sphx_glr_plot_vision_transformer_thumb.png
    :alt:

  :doc:`/auto_examples/vision/plot_vision_transformer`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Explaining a Vision Transformer</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Visualization
=============

Examples showcasing ``shapiq``'s visualization capabilities: force plots,
beeswarm plots, SI graph plots, UpSet plots, and more.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A minimal example showing how to compute exact Shapley values for a small cooperative game using ExactComputer.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_shapley_values_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_shapley_values`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Computing Shapley Values.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the UpSet plot for visualizing feature interactions. The UpSet plot shows the most important interactions as vertical bars with the interacting features in a matrix below.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_upset_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_upset`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">UpSet Plot</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the SI graph plot, which visualizes Shapley interactions as a network. Players are nodes; interactions are edges whose color, thickness, and opacity encode strength and direction.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_si_graph_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_si_graph`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SI Graph Plot</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A comprehensive tour of all local and global visualization functions in shapiq: force plot, waterfall plot, network plot, SI graph plot, stacked bar plot, and global bar plot.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_visualizing_interactions_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_visualizing_interactions`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Visualization Catalog</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to create, manipulate, aggregate, and visualize InteractionValues objects -- the central output type of shapiq.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_interaction_values_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_interaction_values`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Working with InteractionValues</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates beeswarm_plot, which provides a global perspective on feature interactions by plotting interaction values across multiple instances, colored by feature value.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_beeswarm_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_beeswarm`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Beeswarm Plot</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates scatter_plot, which plots the per-sample value of an interaction against the value of one feature. For first-order interactions this matches SHAP&#x27;s shap.plots.scatter; for higher-order interactions the x-axis is restricted to a single feature in the interaction tuple.">

.. only:: html

  .. image:: /auto_examples/visualization/images/thumb/sphx_glr_plot_scatter_thumb.png
    :alt:

  :doc:`/auto_examples/visualization/plot_scatter`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Scatter Plot</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/approximators/index.rst
   /auto_examples/basics/index.rst
   /auto_examples/game_theory/index.rst
   /auto_examples/language/index.rst
   /auto_examples/nearest_neighbor/index.rst
   /auto_examples/tabular/index.rst
   /auto_examples/trees/index.rst
   /auto_examples/vision/index.rst
   /auto_examples/visualization/index.rst