🔍 概述

Shapash 是一个 Python 库，旨在 让机器学习对所有人来说都可解释、易理解。它提供了多种可视化工具，配有清晰明确的标签，便于所有人快速掌握。

借助 Shapash，您可以生成一个 Web 应用程序，帮助简化对 模型特征之间交互关系 的理解，并实现 局部与全局解释性之间的无缝切换。通过这个 Web 应用程序，数据科学家可以轻松地理解自己的模型，并将结果 分享给数据专家和非专业人士。

此外，Shapash 还有助于数据科学审计工作，能够以 全面报告的形式呈现 关于任何模型和数据的 有价值信息。

Shapash 适用于回归、二分类和多分类问题。它 兼容众多模型，包括 Catboost、XGBoost、LightGBM、Scikit-learn 集成模型、线性模型以及 SVM 等。对于其他模型，也有集成 Shapash 的解决方案；更多详情请参阅 这里。

[!NOTE] 如果您想给我们反馈：反馈表单

Shapash 应用演示

🌱 文档与资源

• ReadTheDocs:
• 面向法语观众的视频介绍
• Medium:
  • 用 Shapash 理解你的模型 - Towards AI
  • 模型可审计性 - Towards DS
  • 特征组 - Towards AI
  • 增强可解释性方法的信心 - Towards DS
  • 挑选示例来理解机器学习模型
  • 增强 Web 应用内置功能，实现全面的机器学习模型解释

🎉 有什么新功能？

版本	新特性	描述	教程
2.3.x	额外的数据集列 新演示 文章	在Web应用中：向数据集中添加目标列和误差列，并可添加模型之外的特征，以提供更多筛选选项
2.3.x	身份卡 新演示 文章	在Web应用中：新增身份卡，用于汇总所选样本的信息
2.2.x	样本挑选 文章	Web应用中新增样本挑选标签页。图表展示了“真实值 vs 预测值”
2.2.x	数据集筛选	Web应用中新增数据筛选标签页。此外，Web应用还进行了多项改进：添加副标题、标签以及屏幕布局调整
2.0.x	Shapash重构	重构了compile方法和init方法的属性。为新的后端实现了重构
1.7.x	颜色可变化	允许用户使用自定义调色板来生成符合自身设计风格的输出
1.6.x	可解释性质量指标 文章	为了增强对可解释性方法的信心，您可以使用3个指标来评估可解释性的相关性：稳定性、一致性和紧凑性
1.4.x	特征分组 演示	现在可以将具有共同属性的特征归为一组。如果您的模型包含大量特征，此功能会非常有用。
1.3.x	Shapash报告 演示	一份独立的HTML报告，可作为审计文档的基础。

🔥 功能特性

• 展示清晰易懂的结果：图表和输出对每个特征及其取值都使用了明确的标签

• 允许数据科学家通过一个Web应用快速理解其模型，轻松在全局与局部可解释性之间切换，并了解不同特征的贡献情况：Shapash-Monitor在线演示

• 总结并导出局部解释

Shapash 提供简洁明了的局部解释，使任何背景的数据用户都能通过总结性和明确的解释来理解监督模型的单个预测结果。

• 使用多种指标评估可解释性的质量

• 轻松与非数据领域的用户分享和讨论结果

• 可根据解释性特征、附加特征以及正确或错误的预测结果进行筛选，选择子集以深入分析可解释性。挑选示例以理解机器学习模型

• 部署项目中的可解释性部分：从模型训练到部署（API 或批处理模式）

• 通过生成项目的独立 HTML 报告，为模型的可审计性做出贡献。报告示例 我们相信，这份报告将为模型和数据的审计提供有力支持，从而提升 AI 治理水平。 数据科学家现在可以向任何对项目感兴趣的人提供一份记录其工作各方面的文档，作为审计报告的基础。 该文档可在团队内部（内部审计、DPO、风险、合规等部门）轻松共享。

⚙️ Shapash 的工作原理

Shapash 是一个用于模型可解释性相关库的叠加型工具包。它使用 Shap 或 Lime 作为后端来计算特征贡献。 Shapash 基于构建机器学习模型所需的各个步骤，使结果更加易于理解。

Shapash 适用于回归、二分类或多分类问题。
它兼容多种模型：Catboost、Xgboost、LightGBM、Sklearn Ensemble、线性模型、SVM。

如果您的模型不在兼容列表中，也可以将使用 Shap 或其他方法计算出的局部贡献提供给 Shapash。这里有一个如何向 Shapash 提供贡献的示例。为了进一步完善这一用法，已创建了一个问题。

Shapash 可以使用 category-encoders 对象、sklearn ColumnTransformer，或者直接使用特征字典。

• Category_encoder：OneHotEncoder、OrdinalEncoder、BaseNEncoder、BinaryEncoder、TargetEncoder
• Sklearn ColumnTransformer：OneHotEncoder、OrdinalEncoder、StandardScaler、QuantileTransformer、PowerTransformer

🛠 安装说明

Shapash 适用于 Python 3.9 至 3.12 版本。可通过 pip 进行安装：

pip install shapash

若需生成 Shapash 报告，则需要额外的依赖项。您可以通过以下命令安装这些依赖：

pip install shapash[report]

如果您遇到兼容性问题，请参阅 Shapash 文档中的相应章节此处。

🕐 快速入门

展示结果的4个步骤：

• 第1步：声明 SmartExplainer 对象

  在 compile 方法中有一个必填参数：Model 您可以在此处声明 features_dict，以指定要显示的标签

from shapash import SmartExplainer

xpl = SmartExplainer(
    model=regressor,
    features_dict=house_dict,  # 可选参数
    preprocessing=encoder,  # 可选：compile 步骤可以使用 inverse_transform 方法
    postprocessing=postprocess,  # 可选：参见教程中的后处理部分
)

• 第2步：编译数据集，…

  在 compile 方法中有一个必填参数：Dataset

xpl.compile(
    x=xtest,
    y_pred=y_pred,  # 可选：用于您自己的预测（默认为 model.predict）
    y_target=yTest,  # 可选：允许显示真实值与预测值的对比
    additional_data=xadditional,  # 可选：Web 应用程序的附加特征数据集
    additional_features_dict=features_dict_additional,  # 可选：附加数据的字典
)

• 第3步：展示输出

  有多种输出和图表可供使用。例如，您可以启动 Web 应用程序：

app = xpl.run_app()

Shapash-Monitor 实时演示

• 第4步：生成 Shapash 报告

  此步骤允许您使用数据集的不同划分以及所使用的指标，生成项目的独立 HTML 报告：

xpl.generate_report(
    output_file="path/to/output/report.html",
    project_info_file="path/to/project_info.yml",
    x_train=xtrain,
    y_train=ytrain,
    y_test=ytest,
    title_story="房屋价格报告",
    title_description="""本文档是 Kaggle 房屋价格教程项目的数据科学报告。
        它使用 Shapash 库生成。""",
    metrics=[{"name": "MSE", "path": "sklearn.metrics.mean_squared_error"}],
)

报告示例

• 第5步：从训练到部署：SmartPredictor 对象

  Shapash 提供了一个 SmartPredictor 对象，用于在运营需求中部署局部解释的摘要信息。 这是一个专门用于部署的对象，比 SmartExplainer 更轻量，并增加了额外的一致性检查。 SmartPredictor 可以通过 API 或批处理模式使用。它提供预测、详细或汇总的局部可解释性，并采用适当的措辞。

predictor = xpl.to_smartpredictor()

请参阅教程部分，了解如何使用 SmartPredictor 对象。

📖 教程

此 GitHub 仓库提供了许多教程，帮助您轻松上手 Shapash。

概述

• 使用具体案例启动 Web 应用程序
• Jupyter 概览 - SmartExplainer 对象提供的主要输出和方法
• Shapash 在生产环境中的应用：从模型训练到部署（API 或批处理模式）
• 使用特征组
• 使用 SmartPredictor 在生产环境中部署局部可解释性

图表和绘图

• Shapash 特征重要性
• 贡献度图，用于理解单个特征如何影响预测
• 使用 filter 和 local_plot 方法总结、展示和导出局部贡献
• 比较贡献度图，用于理解为何不同个体的预测结果存在差异
• 可视化变量之间的交互作用
• 展示真实值与预测值的对比
• 自定义 Web 应用程序、图表和报告中的颜色

使用编码器和字典的不同方式

• 使用 Category_Encoder 及其逆变换
• 使用 ColumnTransformers
• 使用简单的 Python 字典

通过后处理展示数据

在 compile 方法中使用 postprocessing 参数

使用不同的后端

• 使用 Shap 计算 Shapley 贡献度
• 使用 Lime 计算局部解释，并用 Shapash 进行总结
• 更快地编译 Lime 结果并确保贡献度的一致性
• 使用 FastTreeSHAP 或添加来自其他后端的贡献
• 使用 Class Shapash 后端

评估可解释性的质量

• 利用 稳定性、一致性 和 紧凑性 指标建立对可解释性方法的信心

生成项目报告

• 使用 generate_report 生成项目的独立 HTML 报告

通过 Shapash Web 应用程序分析您的模型

• 添加模型之外的特征，以获得更多探索选项

🤝 贡献者

🏆 奖项

Shapash 快速上手指南

Shapash 是一个旨在让机器学习模型对所有人都可解释的 Python 库。它提供清晰的可视化图表和标签，支持生成 Web 应用以便在局部和全局可解释性之间无缝切换，并能为回归、二分类及多分类问题生成审计报告。

环境准备

• 操作系统: Linux, macOS, Windows
• Python 版本: 3.8 - 3.11 (推荐 3.9+)
• 前置依赖:
  • 核心依赖：pandas, numpy, scikit-learn, plotly, dash
  • 支持的模型库（按需安装）：xgboost, lightgbm, catboost, shap
• 浏览器: 推荐使用 Chrome 或 Firefox 以获取最佳 WebApp 体验。

安装步骤

1. 基础安装

使用 pip 安装最新稳定版：

pip install shapash

2. 国内加速安装（推荐）

如果您在中国大陆，建议使用清华源或阿里源以加快下载速度：

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

3. 安装完整依赖（可选）

如果您需要使用所有支持的模型（如 CatBoost, XGBoost 等），建议安装完整依赖包：

pip install "shapash[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的使用流程：训练一个模型，初始化 Shapash，并启动交互式 Web 应用。

1. 准备数据与模型

首先导入必要的库并训练一个简单的模型（以 sklearn 为例）：

import pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from shapash import SmartExplainer

# 加载示例数据
url = "https://raw.githubusercontent.com/pymetrics/audit-ai/master/data/compas.csv"
data = pd.read_csv(url)

# 数据预处理（简化版）
features = ['age', 'juv_fel_count', 'juv_misd_count', 'juv_other_count', 'priors_count']
X = data[features]
y = data['two_year_recid']

# 划分数据集
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# 训练模型
model = RandomForestClassifier(n_estimators=10, random_state=42)
model.fit(X_train, y_train)

2. 初始化 Shapash 解释器

编译解释器以计算特征贡献度。features_dict 用于将列名映射为更易读的中文或描述性标签（可选但推荐）。

# 定义特征字典（将英文列名映射为易读标签）
features_dict = {
    'age': '年龄',
    'juv_fel_count': '少年重罪记录数',
    'juv_misd_count': '少年轻罪记录数',
    'juv_other_count': '其他少年记录数',
    'priors_count': '前科数量'
}

# 初始化 SmartExplainer
xpl = SmartExplainer(model=model, features_dict=features_dict)

# 编译解释器
# x_pred: 测试集预测概率 (对于分类问题)
# x_init: 测试集原始特征数据
xpl.compile(
    x=X_test,
    y_pred=model.predict_proba(X_test)[:, 1] 
)

3. 启动 Web 应用

运行以下命令启动本地 Web 服务器，自动在浏览器中打开交互式仪表盘：

xpl.run_app()

操作提示：

• 启动后，终端会显示访问地址（通常为 http://127.0.0.1:8050/）。
• 在 Web 界面中，您可以查看全局特征重要性、筛选特定样本、分析单个预测的原因（局部解释），以及导出分析报告。

4. (可选) 生成静态审计报告

如果不需启动 Web 应用，可直接生成独立的 HTML 报告用于审计：

xpl.to_html(path='shapash_report.html', title='模型可解释性报告')