PolySHAP approximator

.gitignore

@@ -181,6 +181,7 @@ illustration_sources/
 src/shapiq_games/datasets/data/tabarena_*.csv
 
 shapiq/games/benchmark/precomputed/
+benchmark/results/*
 precomputed.zip
 game_storage/*
 
@@ -189,6 +190,7 @@ src/shapiq/_version.py
 
 # Claude
 .claude/
+.claude
 
 # C-Extension files
 *.so
@@ -199,5 +201,8 @@ docs/source/sg_execution_times.rst
 docs/source/generated/
 docs/source/gen_modules/
 
+# Cache
+cache/
+
 # Local debug / scratch scripts (not public)
 scripts/

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### New Features
+
+- adds the `PolySHAP` approximator in `shapiq.approximator.regression` for Shapley value estimation via interaction-informed polynomial regression (PolySHAP, [Fumagalli et al., ICLR 2026](https://arxiv.org/abs/2601.18608)). PolySHAP generalizes `KernelSHAP` by fitting a *k*-additive polynomial surrogate of the game before reading off the Shapley values. The interaction frontier can be the full *k*-additive frontier up to `max_order` (with `max_order=1` recovering `KernelSHAP`), a budget-controlled partial frontier (`max_terms`), or a user-supplied set of interaction terms (`prior_frontier`). Registered as a Shapley-value (`SV`) approximator.
+
 ## v1.6.0 (2026-07-06)
 
 ### Highlights of new Features

docs/source/references.bib

@@ -111,6 +111,13 @@ @article{Fumagalli.2026
   eprinttype = {arXiv},
   eprint     = {2602.01399}
 }
+@inproceedings{Fumagalli.2026a,
+  title     = {{PolySHAP}: Extending {KernelSHAP} with Interaction-Informed Polynomial Regression},
+  author    = {Fabian Fumagalli and R. Teal Witter and Christopher Musco},
+  year      = {2026},
+  booktitle = {The Fourteenth International Conference on Learning Representations ({ICLR} 2026)},
+  url       = {https://arxiv.org/abs/2601.18608}
+}
 @inproceedings{Harris.2022,
   title     = {Joint Shapley values: a measure of joint feature importance},
   author    = {Chris Harris and Richard Pymar and Colin Rowat},

examples/approximators/plot_polyshap.py

@@ -0,0 +1,76 @@
+"""
+PolySHAP
+========
+
+Shapley value approximation with interaction-informed polynomial regression
+using :class:`~shapiq.approximator.PolySHAP` :footcite:t:`Fumagalli.2026a`.
+
+PolySHAP extends KernelSHAP by fitting a *k-additive* surrogate of the game -- a
+polynomial of degree ``max_order`` over the players -- and reading the Shapley
+values off that surrogate. ``max_order=1`` reduces to plain KernelSHAP, while
+higher orders capture interactions explicitly. When the game's interactions do
+not exceed ``max_order``, PolySHAP recovers the exact Shapley values.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+import shapiq
+from shapiq.approximator import PolySHAP
+
+N_PLAYERS = 8
+BUDGET = 200
+feature_names = [f"x{i}" for i in range(N_PLAYERS)]
+
+weights = np.array([0.4, 0.3, 0.2, 0.1, 0.05, -0.1, -0.2, -0.3])
+
+
+def game_fun(coalitions: np.ndarray) -> np.ndarray:
+    # A linear game plus a single pairwise interaction between x0 and x1.
+    # This game is exactly 2-additive: its interactions never exceed order 2.
+    coalitions = np.atleast_2d(coalitions)
+    return (coalitions @ weights) + 0.5 * coalitions[:, 0] * coalitions[:, 1]
+
+
+# %%
+# Approximate Shapley values
+# --------------------------
+# The game has a pairwise interaction, so we fit a second-order (``max_order=2``)
+# polynomial surrogate to recover the Shapley values.
+
+approximator = PolySHAP(n=N_PLAYERS, max_order=2, random_state=42)
+iv = approximator.approximate(BUDGET, game_fun)
+print(iv)
+
+# %%
+# Force plot
+# ----------
+
+iv.plot_force(feature_names=feature_names)
+
+# %%
+# Higher order improves accuracy
+# ------------------------------
+# Because the game is exactly 2-additive, raising ``max_order`` to match its
+# interaction order recovers the exact Shapley values, whereas ``max_order=1``
+# (equivalent to KernelSHAP) leaves a visible approximation error. We compare
+# both against the exact Shapley values from :class:`~shapiq.ExactComputer`.
+
+exact = np.asarray(
+    shapiq.ExactComputer(game_fun, n_players=N_PLAYERS)(index="SV", order=1).get_n_order_values(1)
+)
+
+for max_order in (1, 2):
+    est = np.asarray(
+        PolySHAP(n=N_PLAYERS, max_order=max_order, random_state=42)
+        .approximate(BUDGET, game_fun)
+        .get_n_order_values(1)
+    )
+    mse = float(np.mean((est - exact) ** 2))
+    print(f"max_order={max_order}: MSE vs. exact Shapley = {mse:.2e}")
+
+# %%
+# References
+# ----------
+# .. footbibliography::

src/shapiq/approximator/__init__.py

@@ -17,6 +17,7 @@
     KernelSHAP,
     KernelSHAPIQ,
     OddSHAP,
+    PolySHAP,
     RegressionFBII,
     RegressionFSII,
     kADDSHAP,
@@ -64,6 +65,7 @@ def __init__(self, *_args: object, **_kwargs: object) -> None:
     ProxySPEX,
     OddSHAP,
     ShaplEIG,
+    PolySHAP,
 ]
 
 # contains all SI approximators
@@ -149,4 +151,5 @@ def __init__(self, *_args: object, **_kwargs: object) -> None:
     "STII_APPROXIMATORS",
     "FSII_APPROXIMATORS",
     "FBII_APPROXIMATORS",
+    "PolySHAP",
 ]

src/shapiq/approximator/regression/__init__.py

@@ -6,6 +6,7 @@
 from .kernelshap import KernelSHAP
 from .kernelshapiq import InconsistentKernelSHAPIQ, KernelSHAPIQ
 from .oddshap import OddSHAP
+from .polyshap import PolySHAP
 
 __all__ = [
     "kADDSHAP",
@@ -15,5 +16,6 @@
     "InconsistentKernelSHAPIQ",
     "Regression",
     "RegressionFBII",
+    "PolySHAP",
     "OddSHAP",
 ]