mmschlk/shapiq

Shapley Values and Shapley Interactions for Machine Learning

shapiq – Shapley Interaction Quantification for Machine Learning

What it is – shapiq is a Python library that extends the popular SHAP ecosystem with Shapley interaction values. While classic SHAP gives a single importance score per feature (the “main effect”), shapiq can also quantify how groups of features synergize or interfere with each other. In game‑theoretic language these are higher‑order Shapley interaction indices.

Key capabilities

  • Any‑order interaction estimation – compute interaction scores for pairs, triples, … up to a user‑specified order (default up to 4 in the quick‑start). The library supplies several approximators, including a sparse “ProxySPEX” method for high‑dimensional data.
  • Drop‑in SHAP compatibility – you can request the classic Shapley value index ("SV") and get exactly the same output format as the shap package, making migration painless.
  • Built‑in game & benchmark suite – shapiq_games provides ready‑made “games” (e.g., TabPFN, CatBoost, image‑based games) and shapiq_benchmark lets you compare algorithms on these tasks.
  • Visualization tools – force‑plot style visualisations for both main effects and interactions, plus network graphs that show features as nodes and interaction strengths as edges.
  • Model‑agnostic – works with any callable that maps inputs to predictions (scikit‑learn models, PyTorch, CatBoost, TabPFN, etc.).

Typical workflow

  1. Load data and train a model (e.g., a RandomForestRegressor).
  2. Instantiate an Explainer (e.g., TabularExplainer) and choose an interaction index such as "k‑SII" (k‑order Shapley Interaction Index) and a max_order.
  3. Call explain(sample, budget=…) – the budget controls how many model evaluations the approximator may use.
  4. Inspect the returned InteractionValues object or call its plot_* methods for force‑plots or network diagrams.

Why it matters – Understanding feature interactions is crucial when models capture non‑linear relationships (e.g., a housing price model where location and size together matter more than each alone). shapiq gives researchers a principled, game‑theoretic way to surface those synergies without hand‑crafting interaction terms.

Installation – pip install shapiq (or uv add shapiq). Optional extras shapiq[games] and shapiq[benchmark] pull in heavy dependencies like torch, tabpfn, catboost, etc.

Status & community – Actively maintained (Python 3.12‑3.15 support, CI badges, test coverage). Contributions are welcomed, and the authors provide a citation for the accompanying NeurIPS 2024 paper.

All details above are taken directly from the repository’s README.

Related

  • Project
    shap/shap

    SHAP (SHapley Additive exPlanations) is a Python library that computes game‑theoretic feature attributions (Shapley values) for any ML model. It offers fast exact methods for tree ensembles, approximations for deep nets, and a model‑agnostic KernelExplainer, plus rich visualisations (waterfall, force, beeswarm, text, image). Install via pip or conda; GPU support is optional. Ideal for interpreting tabular, text, or image models.

  • Project
    MAIF/shapash

    Shapash is a Python library that makes machine learning models interpretable by providing clear, labeled visualizations, an interactive web interface, and automated audit reports.

  • Project
    EpistasisLab/scikit-rebate

    A scikit-learn compatible library of Relief-based feature selection algorithms that identify important feature interactions in tabular data without exhaustive searching.

  • Dispatch
    BAIR Introducing SPEX and ProxySPEX for Scalable LLM Interaction Discovery

    BAIR has introduced SPEX and ProxySPEX, algorithms that use signal processing and coding theory to identify influential interactions between features, training data, and model components at scale.

  • Project
    pgmpy/pgmpy

    A Python library for causal and probabilistic reasoning using graphical models, providing tools for structure learning, parameter estimation, and causal inference.