explainerdashboard

作者：Oege Dijk

此软件包方便快速部署一个用于解释机器学习模型（兼容 scikit-learn）工作原理的仪表板 Web 应用程序。该仪表板提供关于模型性能、特征重要性、特征对单个预测的贡献、假设情景分析、部分依赖图、SHAP（交互）值、单个决策树可视化等的交互式图表。

您还可以在笔记本或 Colab 环境中交互式地探索仪表板的各个组件，或者直接从这些环境中启动仪表板。借助库的模块化设计，您还可以使用自己的自定义布局和说明来设计仪表板，并将多个仪表板组合成一个ExplainerHub。

仪表板可以直接从正在运行的仪表板导出为静态 HTML，也可以作为自动化 CI/CD 部署流程的一部分以程序化方式生成为工件。

示例已部署于：Fly.io、Hugging Face Space，详细文档请参见 explainerdashboard.readthedocs.io，有关如何为不同模型启动仪表板的示例笔记本请见[notebooks/dashboard_examples.ipynb]，而有关如何与解释器对象交互的示例笔记本则请见[notebooks/explainer_examples.ipynb]。

它支持 scikit-learn、xgboost、catboost、lightgbm 和 skorch（用于表格型 PyTorch 模型的 sklearn 封装）等框架。

安装

您可以通过 pip 安装该软件包：

pip install explainerdashboard

或者通过 conda-forge：

conda install -c conda-forge explainerdashboard

SageMaker Studio

SageMaker Studio 在独立的应用程序中运行笔记本和终端，因此常见的工作流程是将仪表板配置导出到磁盘，然后从 JupyterServer 终端运行它。当在 Studio 中运行时，explainerdashboard 可以自动检测 SageMaker 并应用正确的代理前缀，或者您可以显式设置它们。

笔记本示例（将仪表板导出到磁盘）：

db = ExplainerDashboard(
    explainer,
    mode="dash",
    port=8051,
    sagemaker=True,
)
db.to_yaml("dashboard.yaml", explainerfile="dashboard.joblib", dump_explainer=True)

终端示例（从 JupyterServer 应用程序运行）：

explainerdashboard run dashboard.yaml --sagemaker --port 8051 --no-browser

通过 Studio 代理 URL 访问仪表板：

<STUDIO_URL>/jupyter/default/proxy/8051/

如果您的 Studio 代理路径不同，可以覆盖前缀：

explainerdashboard run dashboard.yaml \
  --routes-pathname-prefix="/" \
  --requests-pathname-prefix="/jupyter/default/proxy/8051/"

自动检测会检查 /opt/ml/metadata/resource-metadata.json 文件是否存在。

演示：

（如需实时演示，请访问 Fly.io 或 Hugging Face Space）

背景

在许多组织中，尤其是政府机构，但随着 GDPR 的实施，在私营部门也越来越重要的是能够解释机器学习算法的内部运作机制。客户在一定程度上有权了解为何会收到某一特定预测结果，而越来越多的内部和外部监管机构也要求提供解释。随着可解释 AI 方面的最新进展（例如 SHAP 值），传统的“黑箱”说法已不再适用，但要从模型中提取解释仍然需要大量的数据处理和图表制作工作。本库旨在简化这一过程。

其目标是多方面的：

• 使数据科学家能够在几行代码内快速检查其模型的工作原理和性能；
• 使非数据科学领域的利益相关者，如管理者、董事以及内部和外部监督机构，能够在无需依赖数据科学家生成每一张图表和表格的情况下，交互式地检查模型的内部运作；
• 便于构建一款应用程序，为要求解释的客户提供对其模型个体预测的解释；
• 向与模型协同工作的人员（人机协作）解释模型的内部运作，使他们理解模型能做什么、不能做什么。这一点很重要，因为它可以帮助他们判断何时模型可能缺乏信息而需要人工干预。

该库包含：

• SHAP 值（即每个特征对每个个体预测的贡献是多少？）
• 排列重要性（当您随机打乱某个特征时，模型指标会恶化多少？）
• 部分依赖图（当您改变单个特征时，模型预测会发生怎样的变化？）
• SHAP 交互值（将 SHAP 值分解为直接效应和交互效应）
• 对于随机森林、XGBoost 和 LightGBM 模型：单个决策树的可视化
• 对于分类模型：精确度曲线、混淆矩阵、ROC AUC 曲线、PR AUC 曲线等
• 对于回归模型：拟合优度图、残差图等。

该库的设计具有模块化特性，因此应该很容易使用 Plotly Dash 构建您自己的交互式仪表板，其中大部分数据计算、格式化以及图表和表格的渲染工作都由 explainerdashboard 处理，从而使您可以专注于布局和项目特定的文字说明。（即设计使其不仅对数据科学家，而且对贵组织的业务用户也易于理解）

此外，还提供了一个内置的标准仪表板，带有预建的选项卡（您可以单独关闭它们）。

使用示例

拟合模型、构建解释器对象、搭建仪表板并运行它，可以简单地如下所示：

ExplainerDashboard(ClassifierExplainer(RandomForestClassifier().fit(X_train, y_train), X_test, y_test)).run()

下面是一个多行示例，添加了一些额外的参数。 你可以使用 cats 参数将独热编码的分类变量分组在一起。你可以传递一个字典，指定每个分类特征对应的独热列列表；或者如果你使用例如 pd.get_dummies(df.Name, prefix=['Name']) 进行编码（生成列名 'Name_Adam', 'Name_Bob'），则可以直接传递前缀 'Name'：

from sklearn.ensemble import RandomForestClassifier
from explainerdashboard import ClassifierExplainer, ExplainerDashboard
from explainerdashboard.datasets import titanic_survive, titanic_names

feature_descriptions = {
    "Sex": "乘客性别",
    "Gender": "乘客性别",
    "Deck": "乘客所处的甲板",
    "PassengerClass": "船票等级：1等、2等或3等",
    "Fare": "乘客支付的票价",
    "Embarked": "乘客登船的港口，可能是南安普敦、瑟堡或昆士敦",
    "Age": "乘客年龄",
    "No_of_siblings_plus_spouses_on_board": "船上兄弟姐妹与配偶人数之和",
    "No_of_parents_plus_children_on_board" : "船上父母与子女人数之和",
}

X_train, y_train, X_test, y_test = titanic_survive()
train_names, test_names = titanic_names()
model = RandomForestClassifier(n_estimators=50, max_depth=5)
model.fit(X_train, y_train)

explainer = ClassifierExplainer(model, X_test, y_test,
                                cats=['Deck', 'Embarked',
                                    {'Gender': ['Sex_male', 'Sex_female', 'Sex_nan']}],
                                cats_notencoded={'Embarked': 'Stowaway'}, # 默认为 'NOT_ENCODED'
                                descriptions=feature_descriptions, # 为仪表板添加表格和悬停标签
                                labels=['未幸存', '幸存'], # 默认为 ['0', '1', 等]
                                idxs = test_names, # 默认为 X.index
                                index_name = "乘客", # 默认为 X.index.name
                                target = "生存", # 默认为 y.name
                                )

db = ExplainerDashboard(explainer,
                        title="泰坦尼克号解释器", # 默认为 "模型解释器"
                        shap_interaction=False, # 可以通过布尔值关闭选项卡
                        )
db.run(port=8050)

如果你传递的是 sklearn 或 imblearn 的 Pipeline，你还可以清理转换后的特征名称，并让解释器自动推断独热编码组：

explainer = ClassifierExplainer(
    pipeline_model, X_test, y_test,
    strip_pipeline_prefix=True,      # 例如 "num__Age" -> "Age"
    feature_name_fn=None,            # 可选的自定义重命名函数
    auto_detect_pipeline_cats=True,  # 从转换后的管道输出中推断分类变量
)

对于回归模型，你还可以传递目标变量的单位（例如美元）：

X_train, y_train, X_test, y_test = titanic_fare()
model = RandomForestRegressor().fit(X_train, y_train)

explainer = RegressionExplainer(model, X_test, y_test,
                                cats=['Deck', 'Embarked', 'Sex'],
                                descriptions=feature_descriptions,
                                units = "$", # 默认为空字符串
                                )

ExplainerDashboard(explainer).run()

对于带有后处理/缩放的管道模型，只要编码后的列是二值化的（不一定是严格的 0/1），现在就可以接受通过 cats 传递的分组分类特征。

y_test 实际上是可选的，尽管仪表板的某些部分，比如性能指标，显然将不可用：ExplainerDashboard(ClassifierExplainer(model, X_test)).run()。

你可以使用 db.save_html('dashboard.html') 将仪表板导出为静态 HTML 文件。

ExplainerDashboard(explainer, index=0).save_html('dashboard.html')

ExplainerDashboard(explainer, index='Cumings, Mrs. John Bradley (Florence Briggs Thayer)').save_html('dashboard.html')

对于简化的单页仪表板，可以尝试 ExplainerDashboard(explainer, simple=True)。

ExplainerHub

你可以使用 ExplainerHub 将多个仪表板组合起来，并托管在一个地方：

db1 = ExplainerDashboard(explainer1, title="分类器解释器",
         description="预测泰坦尼克号上乘客生存情况的模型")
db2 = ExplainerDashboard(explainer2, title="回归解释器",
         description="预测泰坦尼克号船票价格的模型")
hub = ExplainerHub([db1, db2])
hub.run()

你可以调整标题和描述，管理用户和登录，从配置文件中存储和加载数据，通过命令行管理 Hub 等等。更多信息请参阅 ExplainerHub 文档。

处理计算缓慢的问题

仪表板中的一些计算，例如 SHAP（交互）值和置换重要性的计算，在处理大型数据集或复杂模型时可能会非常缓慢。以下是一些技巧，可以帮助您减少这种不便：

1. 关闭交互性选项卡（shap_interaction=False），并禁用置换重要性计算（no_permutations=True）。尤其是 SHAP 交互值的计算速度可能非常慢，而且通常在分析中并不需要。对于置换重要性计算，您可以设置 n_jobs 参数以并行加速计算。
2. 计算近似 SHAP 值。您可以在初始化解释器时通过传递 shap_kwargs=dict(approximate=True) 来启用近似 SHAP 值的计算。
3. 如果您的模型支持，可以使用 GPU Tree SHAP，只需在初始化时传入 shap='gputree' 即可。这需要 NVIDIA GPU 和支持 CUDA 的 SHAP 构建环境（请参阅 SHAP 文档）。
4. 存储解释器对象。虽然每个实例的计算结果只会被计算一次，但每次实例化新的解释器时都需要重新计算这些属性。您可以通过 explainer.dump("explainer.joblib") 将其保存，并使用 ClassifierExplainer.from_file("explainer.joblib") 加载。所有已计算的属性都会与解释器一同存储。
5. 使用较小的（测试）数据集，或者采用更小的决策树。TreeSHAP 的计算复杂度为 O(TLD^2)，其中 T 是树的数量，L 是任意一棵树的最大叶节点数，D 则是任意一棵树的最大深度。因此，减少决策树中的叶节点数量或平均深度可以显著加快 SHAP 计算的速度。
6. 预先计算 SHAP 值。如果您已经在其他地方计算过 SHAP 值，或者可以在大型集群上进行计算，又或者您的模型支持 GPU 生成的 SHAP 值，那么您可以直接将这些预计算的 SHAP 值通过 explainer.set_shap_values() 和 explainer.set_shap_interaction_values() 方法添加到解释器中。
7. 只绘制随机样本点。当观测数量非常多时，渲染图表本身也可能变得很慢。您可以使用 plot_sample 参数来为仪表板中的各种散点图绘制一个（每次不同）随机样本。例如：ExplainerDashboard(explainer, plot_sample=1000).run()。

在笔记本中启动

在 Jupyter 或 Google Colab 中工作时，您可以使用 ExplainerDashboard(mode='inline')、ExplainerDashboard(mode='external') 或 ExplainerDashboard(mode='jupyterlab') 来在笔记本内嵌入式运行仪表板，或者在单独的标签页中运行，同时保持笔记本的交互性。（db.run(mode='inline') 现在也适用）

此外，还有一个专门的界面可用于在笔记本中快速显示交互式组件：InlineExplainer()。例如，您可以使用 InlineExplainer(explainer).shap.dependence() 在笔记本的输出单元格中交互式地显示 SHAP 依赖性组件。

命令行工具

您可以使用 explainer.dump("explainer.joblib") 将解释器保存到磁盘，然后通过命令行运行：

$ explainerdashboard run explainer.joblib

或者将整个仪表板的配置保存为 .yaml 文件，例如使用 dashboard.to_yaml("dashboard.yaml", explainerfile="explainer.joblib", dump_explainer=True)，然后通过以下命令运行：

$ explainerdashboard run dashboard.yaml

您还可以使用 explainerdashboard build 命令行工具构建解释器。有关详细信息，请参阅 explainerdashboard CLI 文档。

自定义您的仪表板

仪表板具有高度模块化和可定制性，因此您可以根据自身需求和项目进行调整。

更改 Bootstrap 主题

您可以通过传递相应 CSS 文件的链接来更改 Bootstrap 主题。您可以使用 dash_bootstrap_components 提供的便捷 themes 模块为您生成 CSS URL：

import dash_bootstrap_components as dbc

ExplainerDashboard(explainer, bootstrap=dbc.themes.FLATLY).run()

有关支持的主题列表，请参阅 dbc 主题文档 和 bootwatch 网站。

关闭选项卡

您可以通过布尔标志关闭单个选项卡。这样做还可以确保不会执行该选项卡所需的昂贵计算：

ExplainerDashboard(explainer,
                    importances=False,
                    model_summary=True,
                    contributions=True,
                    whatif=True,
                    shap_dependence=True,
                    shap_interaction=False,
                    decision_trees=True)

隐藏组件

您还可以在各个选项卡上隐藏单个组件：

    ExplainerDashboard(explainer,
        # 重要性选项卡：
        hide_importances=True,
        # 分类统计选项卡：
        hide_globalcutoff=True, hide_modelsummary=True,
        hide_confusionmatrix=True, hide_precision=True,
        hide_classification=True, hide_rocauc=True,
        hide_prauc=True, hide_liftcurve=True, hide_cumprecision=True,
        # 回归统计选项卡：
        # hide_modelsummary=True,
        hide_predsvsactual=True, hide_residuals=True,
        hide_regvscol=True,
        # 个体预测选项卡：
        hide_predindexselector=True, hide_predictionsummary=True,
        hide_contributiongraph=True, hide_pdp=True,
        hide_contributiontable=True,
        # WhatIf 选项卡：
        hide_whatifindexselector=True, hide_whatifprediction=True,
        hide_inputeditor=True, hide_whatifcontributiongraph=True,
        hide_whatifcontributiontable=True, hide_whatifpdp=True,
        # SHAP 依赖性选项卡：
        hide_shapsummary=True, hide_shapdependence=True,
        # SHAP 交互性选项卡：
        hide_interactionsummary=True, hide_interactiondependence=True,
        # 决策树选项卡：
        hide_treeindexselector=True, hide_treesgraph=True,
        hide_treepathtable=True, hide_treepathgraph=True,
        ).run()

在组件内部隐藏切换按钮和下拉菜单

你还可以使用 **kwargs 来隐藏单个切换按钮和下拉菜单。然而，这些选项并不是针对单个组件的，因此如果你传递 hide_cats=True，那么所有包含该选项的组件中的分类特征切换按钮都会被隐藏：

ExplainerDashboard(explainer,
                    no_permutations=True, # 不显示或计算排列重要性
                    hide_poweredby=True, # 隐藏 poweredby:explainerdashboard 页脚
                    hide_popout=True, # 隐藏每个图表上的“弹出”按钮
                    hide_depth=True, # 隐藏深度（特征数量）下拉菜单
                    hide_sort=True, # 隐藏贡献度图表/表格中的排序类型下拉菜单
                    hide_orientation=True, # 隐藏贡献度图表/表格中的方向下拉菜单
                    hide_type=True, # 隐藏重要性组件中的 SHAP/排列切换按钮
                    hide_dropna=True, # 隐藏 PDP 组件中的 dropna 切换按钮
                    hide_sample=True, # 隐藏 PDP 组件中的样本大小输入框
                    hide_gridlines=True, # 隐藏 PDP 组件中的网格线
                    hide_gridpoints=True, # 隐藏 PDP 组件中的网格点输入框
                    hide_cats_sort=True, # 隐藏分类特征的排序选项
                    hide_cutoff=True, # 隐藏分类组件中的阈值选择器
                    hide_percentage=True, # 隐藏分类组件中的百分比切换按钮
                    hide_log_x=True, # 隐藏回归图中的 x 轴对数切换按钮
                    hide_log_y=True, # 隐藏回归图中的 y 轴对数切换按钮
                    hide_ratio=True, # 隐藏残差类型的下拉菜单
                    hide_points=True, # 隐藏小提琴图散点标记的显示切换按钮
                    hide_winsor=True, # 隐藏 Winsorize 输入框
                    hide_wizard=True, # 隐藏提升曲线组件中的向导切换按钮
                    hide_range=True, # 隐藏特征输入上的范围下标
                    hide_star_explanation=True, # 隐藏“* 表示观测标签”的文本
)

设置默认值

你还可以为各种下拉菜单和切换按钮设置默认值。所有组件及其参数都可以在文档中找到。以下是一些有用的参数示例：

ExplainerDashboard(explainer,
                    higher_is_better=False, # 反转贡献度图表中的绿色和红色
                    n_input_cols=3, # 将“如果怎样”选项卡中的特征输入分为 3 列
                    input_features=['Sex', 'Deck', 'PassengerClass', 'Fare', 'Age'], # 按此顺序显示这些“如果怎样”输入
                    hide_features=['Fare'], # 隐藏特定的“如果怎样”输入
                    col='Fare', # SHAP 图表中的初始特征
                    color_col='Age', # SHAP 依赖关系图中的颜色特征
                    interact_col='Age', # SHAP 相互作用图中的交互特征
                    depth=5, # 仅显示前 5 个特征
                    sort = 'low-to-high', # 在贡献度图表/表格中按 SHAP 值从低到高排序
                    cats_topx=3, # 仅显示分类特征的前 3 个类别
                    cats_sort='alphabet', # 按字母顺序对分类特征进行排序
                    orientation='horizontal', # 贡献度图表中的水平条形图
                    index='Rugg, Miss. Emily', # 初始显示的索引
                    pdp_col='Fare', # 初始的 PDP 特征
                    cutoff=0.8, # 分类图表中的阈值
                    round=2 # 对浮点数应用的四舍五入位数
                    show_metrics=['accuracy', 'f1', custom_metric] # 仅显示某些指标
                    plot_sample=1000, # 仅在散点图中显示 1000 个随机标记
                    )

设计自定义布局

仪表板中的所有组件都是模块化的且可重用的，这意味着你可以围绕它们构建自己的自定义 Dash 仪表板。

通过使用内置的 ExplainerComponent 类，只需具备最基本的 HTML 和 Bootstrap 知识，就可以轻松构建自己的布局。例如，如果你只想显示 ConfusionMatrixComponent 和 ShapContributionsGraphComponent，但要隐藏一些切换按钮：

from explainerdashboard.custom import *

class CustomDashboard(ExplainerComponent):
    def __init__(self, explainer, name=None):
        super().__init__(explainer, title="Custom Dashboard")
        self.confusion = ConfusionMatrixComponent(explainer, name=self.name+"cm",
                            hide_selector=True, hide_percentage=True,
                            cutoff=0.75)
        self.contrib = ShapContributionsGraphComponent(explainer, name=self.name+"contrib",
                            hide_selector=True, hide_cats=True,
                            hide_depth=True, hide_sort=True,
                            index='Rugg, Miss. Emily')

    def layout(self):
        return dbc.Container([
            dbc.Row([
                dbc.Col([
                    html.H1("Custom Demonstration:"),
                    html.H3("如何使用 ExplainerComponents 构建自定义布局。")
                ])
            ]),
            dbc.Row([
                dbc.Col([
                    self.confusion.layout(),
                ]),
                dbc.Col([
                    self.contrib.layout(),
                ])
            ])
        )

db = ExplainerDashboard(explainer, CustomDashboard, hide_header=True).run()

你可以利用这一点来定义专属于你自己的模型、项目和需求的自定义布局。你可以以默认仪表板选项卡所使用的 ExplainerComposites 作为起点，并对其进行编辑以重新组织组件、添加文本等。更多详细信息请参阅自定义仪表板文档。一个已部署的自定义仪表板可以在 Fly.io(源代码) 上找到。

部署

如果你想使用例如 gunicorn 或 waitress 来部署仪表板，你应该在代码中添加 app = db.flask_server() 来暴露 Flask 服务器。然后你可以通过例如 gunicorn dashboard:app 来启动服务器 （假设你定义仪表板的文件名为 dashboard.py）。 另请参阅 ExplainerDashboard 章节 以及文档中的 部署章节。 针对特定平台的指南，请参阅： 部署到 Fly.io 和 部署到 Hugging Face Spaces。 还有 部署到 Azure Web 应用, 部署在反向代理和路径前缀后, 部署到 Google Cloud Run, 部署到 Kubernetes (Ingress), 在 Databricks 笔记本中部署, 以及 在 Kaggle 笔记本中部署。

对于简洁的生产模式，只需暴露一个 WSGI 应用程序，并使用 gunicorn 运行： app = db.flask_server() 和 gunicorn --bind=0.0.0.0:${PORT:-8000} dashboard:app。 如果你的部署运行在代理或路径前缀之后，并且看到“加载中…”的提示，请查看上述部署文档，确保 url_base_pathname、routes_pathname_prefix 和 requests_pathname_prefix 设置一致。

将你的 explainer 和仪表板布局存储到磁盘上，然后再重新加载可能会很有帮助，例如：

generate_dashboard.py:

from explainerdashboard import ClassifierExplainer, ExplainerDashboard
from explainerdashboard.custom import *

explainer = ClassifierExplainer(model, X_test, y_test)

# 构建 ExplainerDashboard 可确保所有必要的属性都被计算出来：
db = ExplainerDashboard(explainer, [ShapDependenceComposite, WhatIfComposite],
                        title='Awesome Dashboard', hide_whatifpdp=True)

# 将 explainer 和仪表板配置都保存下来：
db.to_yaml("dashboard.yaml", explainerfile="explainer.joblib", dump_explainer=True)

然后你可以在 dashboard.py 中重新加载它：

from explainerdashboard import ClassifierExplainer, ExplainerDashboard

# 你可以在从配置文件加载时覆盖参数：
db = ExplainerDashboard.from_config("dashboard.yaml", title="Awesomer Title")

app = db.flask_server()

然后可以通过以下命令运行：

    $ gunicorn dashboard:app

或者使用 waitress（Windows 上也适用）：

    $ waitress-serve dashboard:app

最小化内存使用

当你部署一个包含大量行数 (n) 和列数 (m) 的数据集的仪表板时，其内存占用可能会非常大。你可以使用 explainer.memory_usage() 来检查（近似的）内存使用情况。（顺便提一句：如果你的数据行数很多，可能还需要设置 plot_sample 参数）

为了减少内存占用，你可以采取以下几种措施：

1. 不包含 SHAP 交互图：SHAP 交互值的形状是 (n*m*m)，因此会占用相当大的内存。

2. 降低精度。默认情况下，SHAP 值以 'float64' 格式存储，但你可以将其改为 'float32' 格式来节省一半的空间： ClassifierExplainer(model, X_test, y_test, precision='float32') 当然，你也可以自行对 X_test 数据集设置较低的精度。

3. 对于多分类模型，默认情况下 ClassifierExplainer 会为所有类别计算 SHAP 值。如果你只对某一类别感兴趣，可以丢弃其他类别的 SHAP 值： explainer.keep_shap_pos_label_only(pos_label)

4. 将数据外部存储。例如，你可以在 explainer 中仅存储 10,000 行数据（足以生成重要性与依赖性图表），而将剩余的数百万行输入数据存储在外部文件或数据库中：

   • 使用 explainer.set_X_row_func() 可以设置一个函数，该函数接受一个 index 作为参数，并返回对应索引的单行 DataFrame，其中包含与模型兼容的输入数据。这个函数可以包括对数据库的查询或文件读取操作。
   • 使用 explainer.set_y_func() 可以设置一个函数，该函数接受一个 index 作为参数，返回该索引对应的观测结果 y。
   • 使用 explainer.set_index_list_func() 可以设置一个函数，该函数返回可查询的可用索引列表。此函数仅在仪表板启动时调用一次。

   如果索引数量非常多，且用户能够在其他地方查找这些索引，你还可以将索引下拉菜单替换为简单的自由文本输入框，方法是设置 index_dropdown=False。默认情况下，只有有效的索引（即在 get_index_list() 列表中）才会被传递给其他组件，但你可以通过设置 index_check=False 来覆盖这一行为。此外，你还可以设置一个 explainer.set_index_check_func(func) 函数，该函数应返回一个布尔值，指示给定的 index 是否存在。

   重要提示：这些函数可能会被多个独立组件多次调用，因此最好实现某种缓存功能。你传入的函数也可以是方法，这样你就可以访问 explainer 的所有内部机制。

文档

文档可在 explainerdashboard.readthedocs.io 找到。

关于如何为不同类型的模型启动仪表板的示例笔记本在此：dashboard_examples.ipynb。

关于如何与 explainer 对象交互的示例笔记本在此：explainer_examples.ipynb。

关于如何设计自定义仪表板的示例笔记本在此：custom_examples.ipynb。

已部署示例：

你可以在 Fly.io 和 Hugging Face Space 找到示例仪表板。

（源代码位于 https://github.com/oegedijk/explainingtitanic）

引用：

DOI 可在 zenodo 上找到

explainerdashboard 快速上手指南

explainerdashboard 是一个用于快速部署机器学习模型解释仪表盘的 Python 库。它支持 scikit-learn、xgboost、catboost、lightgbm 等主流框架，能够生成交互式网页，展示模型性能、特征重要性、SHAP 值、部分依赖图（PDP）以及“如果...会怎样”分析等功能，帮助数据科学家和业务人员理解黑盒模型。

环境准备

• 操作系统：Windows, macOS, Linux
• Python 版本：建议 Python 3.7 及以上
• 前置依赖：
  • 已训练好的机器学习模型（需兼容 scikit-learn 接口）
  • 测试数据集 (X_test, y_test)
  • 基础科学计算库：pandas, numpy, scikit-learn
  • 可视化后端：plotly, dash (安装本库时会自动处理)

安装步骤

推荐使用国内镜像源加速安装。

方式一：使用 pip 安装（推荐）

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

方式二：使用 conda 安装

conda install -c conda-forge explainerdashboard

基本使用

只需几行代码即可为分类或回归模型启动一个完整的解释性仪表盘。

1. 最简示例（一行代码启动）

适用于快速检查模型行为。以下示例使用随机森林分类器：

from sklearn.ensemble import RandomForestClassifier
from explainerdashboard import ClassifierExplainer, ExplainerDashboard

# 假设 X_train, y_train, X_test, y_test 已准备好
model = RandomForestClassifier().fit(X_train, y_train)

# 构建解释器并直接运行仪表盘
ExplainerDashboard(ClassifierExplainer(model, X_test, y_test)).run()

运行后，终端会显示访问地址（默认为 http://127.0.0.1:8050），在浏览器打开即可查看。

2. 标准示例（自定义配置）

在实际项目中，通常需要指定特征描述、类别分组和标签名称，以提升仪表盘的可读性。

from sklearn.ensemble import RandomForestClassifier
from explainerdashboard import ClassifierExplainer, ExplainerDashboard

# 1. 训练模型
model = RandomForestClassifier(n_estimators=50, max_depth=5)
model.fit(X_train, y_train)

# 2. 构建解释器对象
# cats: 将 One-Hot 编码的列归组（如 'Sex_male', 'Sex_female' 归为 'Sex'）
# descriptions: 特征的人类可读描述
# labels: 分类目标的标签名称
explainer = ClassifierExplainer(
    model, 
    X_test, 
    y_test,
    cats=['Deck', 'Embarked', {'Gender': ['Sex_male', 'Sex_female']}],
    descriptions={
        "Age": "乘客年龄",
        "Fare": "票價",
        "Sex": "性别"
    },
    labels=['未幸存', '幸存'],
    idxs=test_names, # 可选：设置样本索引名称
    index_name="乘客姓名",
    target="生存状态"
)

# 3. 创建并运行仪表盘
db = ExplainerDashboard(
    explainer,
    title="泰坦尼克号生存预测模型解释",
    shap_interaction=False, # 可关闭特定标签页以简化界面
)

db.run(port=8050)

3. 回归模型示例

对于回归任务，使用 RegressionExplainer 并可指定目标单位：

from sklearn.ensemble import RandomForestRegressor
from explainerdashboard import RegressionExplainer, ExplainerDashboard

model = RandomForestRegressor().fit(X_train, y_train)

explainer = RegressionExplainer(
    model, 
    X_test, 
    y_test,
    cats=['Deck', 'Embarked', 'Sex'],
    units="$" # 指定目标变量单位
)

ExplainerDashboard(explainer).run()

4. 导出静态 HTML

若需将仪表盘作为报告分享或集成到 CI/CD 流程中，可导出为静态 HTML 文件：

# 导出包含所有交互功能的静态 HTML
db.save_html('dashboard.html')

# 或者导出针对特定样本的静态页面
ExplainerDashboard(explainer, index=0).save_html('specific_prediction.html')