shapiq: 用于机器学习的夏普利交互

一次交互可能胜过千次主效应。

Shapley Interaction Quantification (shapiq) 是一个 Python 包，用于 (1) 近似任意阶的夏普利交互值，(2) 对机器学习中的博弈论算法进行基准测试，(3) 解释模型预测中的特征交互。shapiq 扩展了广为人知的 shap 包，既适用于从事机器学习中博弈论研究的研究人员，也适用于需要解释模型的最终用户。SHAP-IQ 在个体夏普利值的基础上，进一步量化了实体（即博弈论术语中的“玩家”）之间的协同效应，例如解释性特征、数据点或集成模型中的弱学习器。玩家之间的协同作用能够提供对机器学习模型更为全面的理解。

🛠️ 安装

shapiq 旨在与 Python 3.12 及以上版本 一起使用。 可以通过 uv 进行安装：

uv add shapiq

或者通过 pip：

pip install shapiq

👀 即将推出的功能

请在我们的 GitHub 项目板 上查看该库的未来规划。我们在此处规划并跟踪即将推出的功能、改进和维护任务，包括新的解释器、性能优化以及更广泛的模型支持。

⭐ 快速入门

您可以使用 shapiq.explainer 解释您的模型，并用 shapiq.plot 可视化夏普利交互值。如果您对底层的博弈论算法感兴趣，请查看 shapiq.approximator 和 shapiq.games 模块。

计算任意阶的特征交互

使用夏普利交互来解释您的模型： 只需加载数据和模型，然后使用 shapiq.Explainer 计算夏普利交互。

import shapiq
# 加载数据
X, y = shapiq.load_california_housing(to_numpy=True)
# 训练模型
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor()
model.fit(X, y)
# 设置一个计算 k-SII 交互值、最高阶数为 4 的解释器
explainer = shapiq.TabularExplainer(
    model=model,
    data=X,
    index="k-SII",
    max_order=4
)
# 解释模型对第一个样本的预测
interaction_values = explainer.explain(X[0], budget=256)
# 分析交互值
print(interaction_values)

>> InteractionValues(
>>     index=k-SII, max_order=4, min_order=0, estimated=False,
>>     estimation_budget=256, n_players=8, baseline_value=2.07282292,
>>     前 10 个交互：
>>         (0,): 1.696969079  # 特征 0 的归因
>>         (0, 5): 0.4847876
>>         (0, 1): 0.4494288  # 特征 0 和 1 之间的交互
>>         (0, 6): 0.4477677
>>         (1, 5): 0.3750034
>>         (4, 5): 0.3468325
>>         (0, 3, 6): -0.320  # 特征 0、3 和 6 之间的交互
>>         (2, 3, 6): -0.329
>>         (0, 1, 5): -0.363
>>         (6,): -0.56358890
>> )

计算您熟悉的 SHAP 式夏普利值

如果您习惯使用 SHAP，也可以用 shapiq 以相同的方式计算夏普利值： 您可以加载数据和模型，然后使用 shapiq.Explainer 计算夏普利值。如果将索引设置为 'SV'，您将得到与 SHAP 中相同的夏普利值。

import shapiq

data,模型 = ...  # 获取您的数据和模型
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="SV",  # 夏普利值
)
shapley_values = explainer.explain(data[0])
shapley_values.plot_force(feature_names=...)

一旦您获得了夏普利值，也可以轻松计算交互值：

explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="k-SII",  # k-SII 交互值
    max_order=2     # 指定您想要的任何阶数
)
interaction_values = explainer.explain(data[0])
interaction_values.plot_force(feature_names=...)

使用 ProxySPEX（代理稀疏解释器）

对于大规模应用场景，您还可以尝试 👓ProxySPEX 近似器。

# 加载具有大量特征的数据和模型
data,模型,n_features = ...

# 直接使用 ProxySPEX 近似器
approximator = shapiq.ProxySPEX(n=n_features, index="FBII", max_order=2)
fbii_scores = approximator.approximate(budget=2000, game=model.predict)

# 或者结合 ProxySPEX 与解释器使用
explainer = shapiq.Explainer(
    model=model,
    data=data,
    index="FBII",
    max_order=2,
    approximator="proxyspex"  # 指定 ProxySPEX 作为近似器
)
explanation = explainer.explain(data[0])

可视化特征交互

可视化二阶及以下交互得分的一种便捷方式是使用网络图。下面是一个此类图的示例。节点代表特征的归因值，边则表示特征之间的交互作用。节点和边的强度与大小分别与归因值和交互作用的绝对值成正比。

shapiq.network_plot(
    first_order_values=interaction_values.get_n_order_values(1),
    second_order_values=interaction_values.get_n_order_values(2)
)
# 或者使用
interaction_values.plot_network()

上述伪代码可以生成如下图表（此处也附上图片）：

解释 TabPFN

借助 shapiq，您还可以通过使用 shapiq.TabPFNExplainer 中实现的“移除并重新上下文化”解释范式来解释 TabPFN。

import tabpfn, shapiq
data, labels = ...                    # 加载您的数据
model = tabpfn.TabPFNClassifier()     # 获取 TabPFN
model.fit(data, labels)               # “拟合” TabPFN（可选）
explainer = shapiq.TabPFNExplainer(   # 设置解释器
    model=model,
    data=data,
    labels=labels,
    index="FSII"
)
fsii_values = explainer.explain(data[0])  # 使用忠实 Shapley 值进行解释
fsii_values.plot_force()               # 绘制力图

📖 包含教程的文档

shapiq 的文档可在 https://shapiq.readthedocs.io 上找到。如果您对 Shapley 值或 Shapley 交互还不熟悉，建议从 简介 和 示例与教程 开始阅读。这里有许多优质资源可以帮助您快速入门 Shapley 值和交互。

💬 引用

如果您使用了 shapiq 并对其感到满意，请考虑引用我们的 NeurIPS 论文，或者为本仓库点个赞。

@inproceedings{Muschalik.2024b,
  title     = {shapiq: 用于机器学习的 Shapley 交互},
  author    = {Maximilian Muschalik、Hubert Baniecki、Fabian Fumagalli、Patrick Kolpaczki、Barbara Hammer 和 Eyke H\"{u}llermeier},
  booktitle = {第38届神经信息处理系统大会数据集与基准测试赛道},
  year      = {2024},
  url       = {https://openreview.net/forum?id=knxGmi6SJi}
}

📦 贡献

我们欢迎对 shapiq 的任何形式的贡献！如果您有兴趣参与贡献，请查看我们的 贡献指南。如有任何问题，欢迎随时与我们联系。我们通过 项目看板 和 问题 部分跟踪进展。如果您发现错误或有功能请求，请提交一个问题，或者通过打开拉取请求来帮助我们修复。

📜 许可证

本项目采用 MIT 许可证 许可。

💰 资助

这项工作以 MIT 许可证公开发布。部分作者感谢德国研究基金会 (DFG) 在编号 TRR 318/1 2021 – 438445824 的资助下提供的财政支持。

---

由 shapiq 团队用心打造。

shapiq 快速上手指南

shapiq 是一个用于机器学习的 Shapley 交互量化工具包。它不仅扩展了经典的 SHAP 库，还能量化特征、数据点或弱学习器之间的协同效应（Synergy），提供比单一 Shapley 值更全面的模型解释视角。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：要求 Python 3.12 及以上版本
• 前置依赖：
  • 推荐安装 scikit-learn 用于构建示例模型。
  • 若需可视化网络图，建议安装 networkx 和 matplotlib。

安装步骤

你可以选择使用 pip 或现代化的 uv 工具进行安装。

方式一：使用 pip (推荐)

pip install shapiq

国内加速提示：如果遇到下载速度慢的问题，可以使用清华或阿里云镜像源：

pip install shapiq -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 uv

如果你已经安装了 uv 包管理器：

uv add shapiq

基本使用

以下示例演示如何加载数据、训练模型，并计算高阶特征交互值（Shapley Interactions）。

1. 计算任意阶特征交互

此示例展示如何使用 TabularExplainer 计算高达 4 阶的 k-SII 交互值。

import shapiq
from sklearn.ensemble import RandomForestRegressor

# 1. 加载数据 (内置加州房价数据集)
X, y = shapiq.load_california_housing(to_numpy=True)

# 2. 训练模型
model = RandomForestRegressor()
model.fit(X, y)

# 3. 设置解释器
# index="k-SII": 使用 k-Shapley Interaction Index
# max_order=4: 计算最高 4 阶的交互作用
explainer = shapiq.TabularExplainer(
    model=model,
    data=X,
    index="k-SII",
    max_order=4
)

# 4. 解释第一个样本的预测结果
# budget=256: 限制评估次数以加快近似速度
interaction_values = explainer.explain(X[0], budget=256)

# 5. 查看结果
print(interaction_values)

输出示例：

InteractionValues(
    index=k-SII, max_order=4, min_order=0, estimated=False,
    estimation_budget=256, n_players=8, baseline_value=2.07282292,
    Top 10 interactions:
        (0,): 1.696969079  # 特征 0 的独立贡献
        (0, 5): 0.4847876
        (0, 1): 0.4494288  # 特征 0 和 1 之间的交互作用
        (0, 6): 0.4477677
        (1, 5): 0.3750034
        ...
)

2. 兼容传统 SHAP 用法

如果你习惯使用 SHAP，shapiq 也支持计算标准的 Shapley 值（SV），并可无缝切换至交互值计算。

import shapiq

# 假设已有 data 和 model
# data, model = ... 

# 计算标准 Shapley 值
explainer_sv = shapiq.Explainer(
    model=model,
    data=data,
    index="SV",  # 指定为 Shapley Values
)
shapley_values = explainer_sv.explain(data[0])
# shapley_values.plot_force(feature_names=...)

# 计算二阶交互值
explainer_si = shapiq.Explainer(
    model=model,
    data=data,
    index="k-SII", 
    max_order=2     # 指定计算 2 阶交互
)
interaction_values = explainer_si.explain(data[0])
# interaction_values.plot_force(feature_names=...)

3. 可视化交互关系

对于 2 阶及以下的交互值，可以使用网络图直观展示特征归因（节点）与特征间交互（边）。

# 方法一：直接使用 plot_network
interaction_values.plot_network()

# 方法二：手动提取不同阶数的值绘图
shapiq.network_plot(
    first_order_values=interaction_values.get_n_order_values(1),
    second_order_values=interaction_values.get_n_order_values(2)
)

4. 高级场景：大规模数据与 TabPFN

• 大规模数据：对于特征数量巨大的场景，推荐使用 ProxySPEX 近似器以提高效率。

  approximator = shapiq.ProxySPEX(n=n_features, index="FBII", max_order=2)
  fbii_scores = approximator.approximate(budget=2000, game=model.predict)
  

• 解释 TabPFN 模型：shapiq 原生支持解释 TabPFN 模型。

  import tabpfn, shapiq
  
  model = tabpfn.TabPFNClassifier()
  model.fit(data, labels)
  
  explainer = shapiq.TabPFNExplainer(
      model=model,
      data=data,
      labels=labels,
      index="FSII"
  )
  fsii_values = explainer.explain(data[0])
  fsii_values.plot_force()
  

更多详细教程和 API 文档请访问：https://shapiq.readthedocs.io