|PyPiVersion|_ |CondaVersion|_ |MITlicense| |PythonSupport|_ |Downloads|_

|BuildStatusTests|_ |BuildStatusNotebooks|_

.. |MITlicense| image:: https://img.shields.io/badge/License-MIT-blue.svg .. _MITlicense: https://img.shields.io/badge/License-MIT-blue.svg

.. |PyPiVersion| image:: https://img.shields.io/pypi/v/dice-ml .. _PyPiVersion: https://pypi.org/project/dice-ml/

.. |Downloads| image:: https://static.pepy.tech/personalized-badge/dice-ml?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads .. _Downloads: https://pepy.tech/project/dice-ml

.. |PythonSupport| image:: https://img.shields.io/pypi/pyversions/dice-ml .. _PythonSupport: https://pypi.org/project/dice-ml/

.. |CondaVersion| image:: https://anaconda.org/conda-forge/dice-ml/badges/version.svg .. _CondaVersion: https://anaconda.org/conda-forge/dice-ml

.. |BuildStatusTests| image:: https://github.com/interpretml/DiCE/actions/workflows/python-package.yml/badge.svg?branch=main .. _BuildStatusTests: https://github.com/interpretml/DiCE/actions/workflows/python-package.yml?query=workflow%3A%22Python+package%22

.. |BuildStatusNotebooks| image:: https://github.com/interpretml/DiCE/actions/workflows/notebook-tests.yml/badge.svg?branch=main .. _BuildStatusNotebooks: https://github.com/interpretml/DiCE/actions/workflows/notebook-tests.yml?query=workflow%3A%22Notebook+tests%22

用于机器学习的多样化反事实解释（DiCE）

如何解释一个机器学习模型，使其既忠实于模型本身，又易于人类理解？

Ramaravind K. Mothilal <https://raam93.github.io/>, Amit Sharma <http://www.amitsharma.in/>, Chenhao Tan <https://chenhaot.com/>

FAT* '20论文 <https://arxiv.org/abs/1905.07697>_ | 文档 <https://interpretml.github.io/DiCE/>_ | 示例笔记本 <https://github.com/interpretml/DiCE/tree/master/docs/source/notebooks>_ | 实时Jupyter笔记本 |Binder|_

.. |Binder| image:: https://mybinder.org/badge_logo.svg .. _Binder: https://mybinder.org/v2/gh/interpretML/DiCE/master?filepath=docs/source/notebooks

博客文章: 利用多样化反事实进行机器学习解释 <https://www.microsoft.com/en-us/research/blog/open-source-library-provides-explanation-for-machine-learning-through-diverse-counterfactuals/>

案例研究: Towards Data Science <https://towardsdatascience.com/dice-diverse-counterfactual-explanations-for-hotel-cancellations-762c311b2c64>_ (酒店预订) | Analytics Vidhya <https://medium.com/analytics-vidhya/dice-ml-models-with-counterfactual-explanations-for-the-sunk-titanic-30aa035056e0>_ (泰坦尼克号数据集)

.. image:: https://www.microsoft.com/en-us/research/uploads/prod/2020/01/MSR-Amit_1400x788-v3-1blog.gif :align: center :alt: 可视化反事实解释

解释对于机器学习至关重要，尤其是在金融、医疗、教育和刑事司法等关乎社会重大利益的领域中，基于机器学习的系统正被广泛用于辅助决策。 然而，大多数解释方法都依赖于对机器学习模型的近似来生成可解释的解释。例如， 假设某人申请了一笔贷款，却被一家金融公司的贷款发放算法拒绝了。通常，该公司会给出一个关于贷款被拒的原因的解释，比如“信用记录不佳”。然而，这样的解释并不能帮助申请人决定下一步该怎么做才能提高未来获批的可能性。更关键的是，最重要的特征可能根本不足以改变算法的决策，而且在实际中，有些特征甚至无法改变，比如性别和种族。

DiCE实现了反事实（CF）解释 <https://arxiv.org/abs/1711.00399>_，通过展示同一人的特征扰动版本来提供这类信息，这些版本的人本应获得贷款，例如：“如果你的收入再高1万美元，你就能获得贷款”。换句话说，它为模型输出提供了“如果……会怎样”的解释，并且可以作为其他解释方法的有效补充，无论是对终端用户还是对模型开发者而言。

不过，除了简单的线性模型外，要为任何机器学习模型生成有效的CF示例都相当困难。DiCE基于最新研究 <https://arxiv.org/abs/1905.07697>_，能够为任何机器学习模型生成CF解释。其核心思想是将寻找此类解释的问题转化为一个优化问题，类似于寻找对抗样本。关键区别在于，对于解释而言，我们需要的扰动既要能改变机器学习模型的输出，又要具有多样性且在现实中切实可行。因此，DiCE支持生成一组反事实解释，并且具备可调参数，用于控制解释的多样性和与原始输入的接近程度。此外，它还支持对特征施加简单约束，以确保生成的反事实示例切实可行。

安装DICE

DiCE支持Python 3及以上版本。DiCE的稳定版已在PyPI <https://pypi.org/project/dice-ml/>_上发布。

.. code:: bash

pip install dice-ml

DiCE也在conda-forge <https://anaconda.org/conda-forge/dice-ml>_上可用。

.. code:: bash

conda install -c conda-forge dice-ml

要安装DiCE的最新（开发）版本及其依赖项，需克隆此仓库并在仓库的最顶层文件夹中运行pip install：

.. code:: bash

pip install -e .

如遇任何问题，可尝试手动安装依赖项。

.. code:: bash

pip install -r requirements.txt
# 针对深度学习模型的额外依赖
pip install -r requirements-deeplearning.txt
# 运行单元测试所需
pip install -r requirements-test.txt

开始使用DiCE

借助DiCE，生成解释只需三个简单步骤：准备数据集、训练模型，然后调用DiCE为任意输入生成反事实示例。DiCE也可以与预训练模型配合使用，无论是否拥有原始训练数据。

.. code:: python

import dice_ml
from dice_ml.utils import helpers # 辅助函数
from sklearn.model_selection import train_test_split

数据集 = helpers.load_adult_income_dataset()
目标变量 = 数据集["income"] # 结果变量 
训练集、测试集、以及剩余部分，通过train_test_split分割数据集，
                                                     目标变量，
                                                     测试集占比20%，
                                                     随机种子0，
                                                     按目标变量分层抽样
# 用于训练机器学习模型的数据集
d = dice_ml.Data(dataframe=train_dataset,
                 连续特征['年龄', '每周工作小时数'],
                 结果名称='收入')

# 预训练的机器学习模型
m = dice_ml.Model(model_path=dice_ml.utils.helpers.get_adult_income_modelpath(),
                  后端='TF2', 函数="ohe-min-max")
# DiCE解释实例
exp = dice_ml.Dice(d,m)

对于任意给定的输入，我们现在可以生成反事实解释。例如， 以下输入会导致类别0（低收入），而我们想知道哪些最小的变化能够使预测结果变为1（高收入）。

.. code:: python

# 生成反事实示例
查询实例 = test_dataset.drop(columns="收入")[0:1]
dice_exp = exp.generate_counterfactuals(query_instance, total_CFs=4, desired_class="opposite")
# 可视化反事实解释
dice_exp.visualize_as_dataframe()

.. image:: https://raw.githubusercontent.com/interpretml/DiCE/master/docs/_static/getting_started_updated.png :width: 400 :alt: 反事实示例列表

您可以通过以下方式保存生成的反事实示例。

.. code:: python

# 将生成的反事实示例保存到磁盘
dice_exp.cf_examples_list[0].final_cfs_df.to_csv(path_or_buf='counterfactuals.csv', index=False)

更多详情，请参阅docs/source/notebooks <https://github.com/interpretml/DiCE/tree/master/docs/source/notebooks>_文件夹。这里有一些示例笔记本：

• 入门指南 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_getting_started.ipynb>_: 为sklearn、tensorflow或pytorch二分类器生成CF示例，并计算特征重要性得分。
• 解释多类分类器和回归器 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_multiclass_classification_and_regression.ipynb>_: 为多类分类器或回归器生成CF解释。
• 局部与全局特征重要性 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_feature_importances.ipynb>_: 利用生成的反事实估计局部和全局特征重要性得分。
• 为反事实生成设定约束 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_model_agnostic_CFs.ipynb>_: 指定需要变化的特征及其允许范围，以确保生成的反事实示例有效。

支持的反事实生成方法

DiCE可以使用以下方法生成反事实示例。

与模型无关的方法

• 随机采样
• KD树（用于训练数据内的反事实）
• 遗传算法

请参阅与模型无关的笔记本 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_model_agnostic_CFs.ipynb>_，了解如何使用这些方法的代码示例。

基于梯度的方法

• 在Mothilal等人（2020年） <https://arxiv.org/abs/1905.07697>_中描述的显式损失驱动方法（深度学习模型的默认方法）。
• 在Mahajan等人（2019年） <https://arxiv.org/abs/1912.03277>中描述的变分自编码器（VAE）方法（参见BaseVAE的笔记本 <https://github.com/interpretml/DiCE/blob/master/docs/notebooks/DiCE_getting_started_feasible.ipynb>）。

后两种方法需要可微分的模型，例如神经网络。如果您对某种特定方法感兴趣，请在此处提交问题here <https://github.com/interpretml/DiCE/issues>_。

支持的使用场景

数据

DiCE并不需要访问完整的数据集。它只需要每个特征的元数据属性（连续特征的最小值、最大值，以及分类特征的取值水平）。因此，对于敏感数据，可以这样提供数据集：

.. code:: python

d = data.Data(features={
                   '年龄':[17, 90],
                   '工作单位': ['政府', '其他/未知', '私人', '个体经营'],
                   '教育': ['协会', '学士', '博士', '高中毕业', '硕士', '专业学校', '学校', '一些大学'],
                   '婚姻状况': ['离婚', '已婚', '分居', '单身', '丧偶'],
                   '职业':['蓝领', '其他/未知', '专业人士', '销售', '服务', '白领'],
                   '种族': ['其他', '白人'],
                   '性别':['女性', '男性'],
                   '每周工作小时数': [1, 99]},
         结果名称='收入')

模型

我们既支持预训练模型，也支持训练新模型。这里有一个使用Tensorflow的简单示例。

.. code:: python

sess = tf.InteractiveSession()
# 生成训练和测试数据
训练集，_ = d.split_data(d.normalize_data(d.one_hot_encoded_data))
X_train = train.loc[:, train.columns != '收入']
y_train = train.loc[:, train.columns == '收入']
# 拟合一个密集型神经网络模型
ann_model = keras.Sequential()
ann_model.add(keras.layers.Dense(20, input_shape=(X_train.shape[1],), kernel_regularizer=keras.regularizers.l1(0.001), activation=tf.nn.relu))
ann_model.add(keras.layers.Dense(1, activation=tf.nn.sigmoid))
ann_model.compile(loss='binary_crossentropy', optimizer=tf.keras.optimizers.Adam(0.01), metrics=['accuracy'])
ann_model.fit(X_train, y_train, validation_split=0.20, epochs=100, verbose=0, class_weight={0:1,1:2})

# 生成用于解释的DiCE模型
m = model.Model(model=ann_model)

请参阅入门指南 <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_getting_started.ipynb>_笔记本，查看使用DiCE结合sklearn和PyTorch模型的代码示例。

解释

我们通过一张表格来可视化解释，突出显示特征的变化。我们还计划支持英文解释！

反事实解释的可行性

我们承认，并非所有反事实解释对用户来说都是可行的。一般来说，越接近个人特征的反事实就越容易实现。同时，多样性也很重要，可以帮助个人在多个可能选项之间做出选择。

DiCE提供了可调参数，用于控制多样性和与原始输入的接近程度，从而生成不同类型的解释。

.. code:: python

dice_exp = exp.generate_counterfactuals(query_instance,
                total_CFs=4, desired_class="opposite",
                proximity_weight=1.5, diversity_weight=1.0)

此外，某些特征可能比其他特征更难改变（例如，教育程度比每周工作小时数更难改变）。DiCE允许通过指定特征权重来输入特征改变的相对难度。较高的特征权重意味着该特征比其他特征更难改变。例如，一种方法是使用与中位数的平均绝对偏差作为衡量连续特征改变相对难度的指标。默认情况下，DiCE会在内部计算这一指标，并将连续特征之间的距离除以该特征在训练集中数值的MAD。我们也可以通过feature_weights参数赋予不同的值。

.. code:: python

# 赋予新的权重
feature_weights = {'年龄': 10, '每周工作小时数': 5}
# 现在使用新的特征权重生成解释
dice_exp = exp.generate_counterfactuals(query_instance,
                total_CFs=4, desired_class="opposite",
                feature_weights=feature_weights)

最后，有些特征是无法改变的，比如年龄或种族。因此，DiCE也允许输入需要变化的特征列表。

.. code:: python

dice_exp = exp.generate_counterfactuals(query_instance,
                total_CFs=4, desired_class="opposite",
                features_to_vary=['年龄','工作单位','教育','职业','每周工作小时数'])

它还支持对特征施加简单的约束，以反映实际限制（例如，每周工作小时数应在10至50之间，可通过permitted_range参数设置）。

更多详情，请参阅this <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_model_agnostic_CFs.ipynb>_笔记本。

反事实解释的承诺

反事实解释忠实于模型，对于因机器学习模型作出的决策，对所有利益相关者都可能很有用。

• 决策对象：反事实解释可用于探索针对某人因机器学习模型作出的决策所采取的可行补救措施。DiCE展示了带有可操作替代特征配置的决策结果，以帮助人们了解自己原本可以做些什么来改变模型的结果。

• 机器学习模型开发者：反事实解释也有助于模型开发者调试模型，查找潜在问题。DiCE可用于为选定的输入生成CF解释，从而揭示某些特征是否存在有问题的（不）独立性（例如，对于95%的输入，改变特征X和Y会改变结果，但对另外5%则不然）。我们旨在支持汇总指标，以帮助开发者调试机器学习模型。

• 决策者：反事实解释可能对诸如医生或法官之类的决策者有用，他们可能会使用机器学习模型作出决策。对于特定个人，DiCE允许深入探究机器学习模型，查看可能导致不同模型结果的可能变化，从而使决策者能够评估自己对预测的信任程度。

• 决策评估者：最后，反事实解释也可能对决策评估者有用，他们可能关注机器学习模型的公平性或其他理想特性。我们计划在未来支持这一功能。

路线图

理想情况下，反事实解释应在建议的广泛变化范围（多样性）与采纳这些变化的相对容易程度（与原始输入的接近程度）之间取得平衡，并且还要遵循世界的因果规律，例如，一个人很难降低自己的教育程度或改变自己的种族。

我们正在努力为DiCE添加以下功能：

• 支持使用DiCE调试机器学习模型
• 构建英文短语（例如，“如果改变了特征，就会得到期望的结果”）以及其他输出反事实示例的方式
• 使用反事实评估LIME和SHAP等特征归因方法的必要性和充分性指标（参见this paper <https://arxiv.org/abs/2011.04917>_）
• 支持贝叶斯优化及其他算法生成反事实解释
• 更好的反事实生成可行性约束

引用

如果您发现DiCE对您的研究工作有帮助，请按如下方式引用。

Ramaravind K. Mothilal、Amit Sharma和Chenhao Tan（2020年）。通过多样化反事实解释来解释机器学习分类器。2020年公平、问责与透明度会议论文集。

Bibtex::

@inproceedings{mothilal2020dice,
		title={通过多样化反事实解释来解释机器学习分类器},
		author={Mothilal, Ramaravind K 和 Sharma, Amit 和 Tan, Chenhao},
		booktitle={2020年公平、问责与透明度会议论文集},
		pages={607--617},
		year={2020}
}

贡献

本项目欢迎贡献与建议。大多数贡献都需要您同意一份《贡献者许可协议》（CLA），声明您有权并确实授予我们使用您贡献的权利。详情请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人会自动判断您是否需要提供CLA，并相应地标注PR（例如，添加标签、留言）。您只需按照机器人提供的指示操作即可。在整个使用我们CLA的项目中，您只需完成一次即可。

本项目已采用微软开源行为准则 <https://opensource.microsoft.com/codeofconduct/>。 更多信息请参阅行为准则常见问题 <https://opensource.microsoft.com/codeofconduct/faq/>，或如有任何其他问题或意见，请联系opencode@microsoft.com <mailto:opencode@microsoft.com>_。

DiCE 快速上手指南

环境准备

• 系统要求：支持 Python 3.x 及以上版本
• 前置依赖：
  • Python 3.x
  • pip 或 conda（推荐使用国内镜像源加速安装）

---

安装步骤

使用 pip 安装（推荐）

pip install dice-ml

如需使用国内镜像源，可添加 -i 参数：

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

使用 conda 安装

conda install -c conda-forge dice-ml

安装开发版（从源码安装）

git clone https://github.com/interpretml/DiCE.git
cd DiCE
pip install -e .

如果遇到依赖问题，可以手动安装依赖包：

pip install -r requirements.txt
pip install -r requirements-deeplearning.txt

---

基本使用

以下是一个最简单的使用示例，展示如何生成反事实解释。

步骤一：导入库并加载数据

import dice_ml
from dice_ml.utils import helpers
from sklearn.model_selection import train_test_split

dataset = helpers.load_adult_income_dataset()
target = dataset["income"]
train_dataset, test_dataset, _, _ = train_test_split(dataset,
                                                     target,
                                                     test_size=0.2,
                                                     random_state=0,
                                                     stratify=target)

步骤二：初始化数据和模型

d = dice_ml.Data(dataframe=train_dataset,
                 continuous_features=['age', 'hours_per_week'],
                 outcome_name='income')

m = dice_ml.Model(model_path=dice_ml.utils.helpers.get_adult_income_modelpath(),
                  backend='TF2', func="ohe-min-max")

exp = dice_ml.Dice(d, m)

步骤三：生成反事实解释

query_instance = test_dataset.drop(columns="income")[0:1]
dice_exp = exp.generate_counterfactuals(query_instance, total_CFs=4, desired_class="opposite")
dice_exp.visualize_as_dataframe()

步骤四：保存结果

dice_exp.cf_examples_list[0].final_cfs_df.to_csv(path_or_buf='counterfactuals.csv', index=False)

---

通过以上步骤，你可以快速使用 DiCE 工具为机器学习模型生成多样化的反事实解释。更多示例和高级用法，请参考项目文档中的 Notebooks。