|PyPi版本|_ |Conda版本|_ |MIT许可证| |Python支持|_ |下载次数|_

|测试构建状态|_ |笔记本构建状态|_

.. |MIT许可证| 图片:: https://img.shields.io/badge/License-MIT-blue.svg .. _MIT许可证: https://img.shields.io/badge/License-MIT-blue.svg

.. |PyPi版本| 图片:: https://img.shields.io/pypi/v/dice-ml .. _PyPi版本: https://pypi.org/project/dice-ml/

.. |下载次数| 图片:: https://static.pepy.tech/personalized-badge/dice-ml?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads .. _下载次数: https://pepy.tech/project/dice-ml

.. |Python支持| 图片:: https://img.shields.io/pypi/pyversions/dice-ml .. _Python支持: https://pypi.org/project/dice-ml/

.. |Conda版本| 图片:: https://anaconda.org/conda-forge/dice-ml/badges/version.svg .. _Conda版本: https://anaconda.org/conda-forge/dice-ml

.. |测试构建状态| 图片:: https://github.com/interpretml/DiCE/actions/workflows/python-package.yml/badge.svg?branch=main .. _测试构建状态: https://github.com/interpretml/DiCE/actions/workflows/python-package.yml?query=workflow%3A%22Python+package%22

.. |笔记本构建状态| 图片:: https://github.com/interpretml/DiCE/actions/workflows/notebook-tests.yml/badge.svg?branch=main .. _笔记本构建状态: https://github.com/interpretml/DiCE/actions/workflows/notebook-tests.yml?query=workflow%3A%22Notebook+tests%22

ML的多样化反事实解释（DiCE）

如何解释一个机器学习模型，使得解释既真实可信又可解释？

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

.. |Bind器| 图片:: https://mybinder.org/badge_logo.svg .. _Bind器: https://mybinder.org/v2/gh/interpretML/DiCE/master?filepath=docs/source/notebooks

博客文章: 使用多样化反事实来解释ML <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>（泰坦尼克号数据集）

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

解释对于机器学习至关重要，特别是在机器学习系统被用于金融、医疗、教育和刑事司法等社会关键领域的决策时。但是，大多数解释方法依赖于ML模型的近似，以创建可解释的解释。例如，考虑一个申请贷款被金融公司的贷款分配算法拒绝的人。通常，公司可能会提供拒绝贷款的解释，例如由于“信用历史不佳”。然而，这样的解释并不能帮助这个人决定下一步该做什么以提高未来被批准的机会。至关重要的是，最重要的特征可能不足以改变算法的决定，而在实践中，可能甚至无法改变，例如性别和种族。

DiCE实现了反事实（CF）解释 <https://arxiv.org/abs/1711.00399>_，通过展示同一个人的特征变动版本，提供了这些信息，比如“如果你的收入高于$10,000，你就会获得贷款”。换句话说，它为模型输出提供了“假设”解释，并且可以对终端用户和模型开发者都是其他解释方法的有用补充。

然而，除了简单的线性模型外，为任何机器学习模型生成有效的CF示例都是困难的。DiCE基于最新研究 <https://arxiv.org/abs/1905.07697>_，为任何ML模型生成CF解释。核心思想是将找到这种解释设置为一个优化问题，类似于寻找对抗性示例。关键区别在于，对于解释，我们需要的是改变机器学习模型输出的扰动，同时这些扰动是多样的，并且可行。因此，DiCE支持生成一组反事实解释，并且具有用于调节解释多样性和接近度的参数。它还支持对特征的简单约束，以确保生成的反事实示例的可行性。

安装DICE

DiCE支持Python 3+。DiCE的稳定版本可在PyPI <https://pypi.org/project/dice-ml/>_上获得。

.. 代码:: bash

pip install dice-ml

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

.. 代码:: bash

conda install -c conda-forge dice-ml

要安装最新（开发版）的DiCE及其依赖项，请克隆此仓库并从仓库的最顶层目录运行pip install：

.. 代码:: bash

pip install -e .

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

.. 代码:: bash

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

开始使用DiCE

使用DiCE，生成解释是一个简单的三步过程：设置数据集，训练模型，然后调用DiCE为任何输入生成反事实示例。DiCE也可以与预训练模型一起工作，无论是否有原始训练数据。

.. 代码:: python

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)
# 训练ML模型的数据集
d = dice_ml.Data(dataframe=train_dataset,
                 continuous_features=['age', 'hours_per_week'],
                 outcome_name='income')

# 预训练的ML模型
m = dice_ml.Model(model_path=dice_ml.utils.helpers.get_adult_income_modelpath(),
                  backend='TF2', func="ohe-min-max")
# DiCE解释实例
exp = dice_ml.Dice(d,m)

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

.. 代码:: python

# 生成反事实示例
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()

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

你可以用以下方式保存生成的反事实示例。

.. 代码:: 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>_）。

最后两个方法需要一个可微模型，例如神经网络。如果您对某个特定方法感兴趣，请在这里 <https://github.com/interpretml/DiCE/issues>_提出问题。

支持的用例

数据

DiCE不需要访问整个数据集。它只需要每个特征的元数据属性（连续特征的最小值、最大值和类别特征的层级）。因此，对于敏感数据，可以将数据集提供为：

.. 代码:: python

d = data.Data(features={
                   'age':[17, 90],
                   'workclass': ['Government', 'Other/Unknown', 'Private', 'Self-Employed'],

'教育程度': ['副学士', '学士', '博士', '高中毕业', '硕士', '专业学校', '学校', '一些大学'], '婚姻状况': ['离婚', '已婚', '分居', '单身', '丧偶'], '职业': ['蓝领', '其他/未知', '专业人士', '销售', '服务', '白领'], '种族': ['其他', '白人'], '性别': ['女性', '男性'], '每周工作小时': [1, 99]}, 结果名称='收入')

模型

我们支持预训练模型以及训练模型。以下是使用Tensorflow的一个简单示例。

.. code:: python

sess = tf.InteractiveSession()
# 生成训练和测试数据
train, _ = d.split_data(d.normalize_data(d.one_hot_encoded_data))
X_train = train.loc[:, train.columns != 'income']
y_train = train.loc[:, train.columns == 'income']
# 拟合一个密集神经网络模型
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 = {'age': 10, 'hours_per_week': 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=['age','workclass','education','occupation','hours_per_week'])

它还支持反映实际约束的特征简单约束（例如，每周工作小时应该在10到50之间，使用permitted_range参数）。

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

反事实解释的承诺

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

决策主体：反事实解释可以用来探索基于ML模型收到的决策的可操作补救措施。DiCE通过显示具有可操作替代档案的决策结果，帮助人们了解他们可以做些什么来改变模型的结果。
ML模型开发者：反事实解释对模型开发者也很有用，帮助他们调试模型中的潜在问题。DiCE可以用于展示一组输入的CF解释，以发现是否存在某些特征的潜在问题（例如，对于95%的输入，改变特征X和Y会改变结果，而对于其余5%则不会）。我们致力于支持汇总指标，帮助开发者调试ML模型。
决策者：反事实解释对于诸如医生或法官这样的决策者也可能有用，他们可能使用ML模型来做决策。对于特定个体，DiCE允许探查ML模型，看看会导致不同ML结果的可能变化，从而让决策者评估他们对预测的信任。
决策评估者：最后，反事实解释对关注ML模型公平性或其他理想属性的决策评估者也很有用。我们计划在未来增加对此的支持。

路线图

理想情况下，反事实解释应在广泛的建议变化(多样性)和相对容易采用这些变化(接近原始输入)之间取得平衡，同时遵循现实世界的因果法则，例如，人们几乎不可能降低他们的教育程度或改变种族。

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

支持使用DiCE调试机器学习模型
构建英语短语（例如，当特征发生变化时的期望结果）和其他输出反事实示例的方法
使用反事实评价特征分配方法，如LIME和SHAP，在必要性和充分性指标上的表现（参见本文 <https://arxiv.org/abs/2011.04917>_）
支持贝叶斯优化及其他生成反事实解释的算法
反事实生成的更好可行性约束

引用

如果你发现DiCE对你的研究工作有用，请引用如下。

Ramaravind K. Mothilal, Amit Sharma, 和Chenhao Tan (2020). 通过多样化的反事实解释解释机器学习分类器. 2020年公平性、责任和透明度会议论文集。

Bibtex::

@inproceedings{mothilal2020dice,
	title={Explaining machine learning classifiers through diverse counterfactual explanations},
	author={Mothilal, Ramaravind K and Sharma, Amit and Tan, Chenhao},
	booktitle={Proceedings of the 2020 Conference on Fairness, Accountability, and Transparency},
	pages={607--617},
	year={2020}
}

贡献

该项目欢迎贡献和建议。大多数贡献需要你同意《贡献者许可协议》(CLA)，声明你有权并确实向我们授予使用贡献的权利。详情请访问 https://cla.microsoft.com。

当你提交拉取请求时，CLA bot将自动确定你是否需要提供CLA并适当标记PR（例如，标签、评论）。只需按照机器人提供的说明操作。你只需在使用我们CLA的所有仓库中执行一次此操作。

该项目采用了微软开源行为准则 <https://opensource.microsoft.com/codeofconduct/>。欲了解更多信息，请参阅行为准则FAQ <https://opensource.microsoft.com/codeofconduct/faq/> 或联系 opencode@microsoft.com <mailto:opencode@microsoft.com>_ 提出任何其他问题或意见。