TimeSHAP

PyPI版本

TimeSHAP是一个模型无关的、循环的解释器，它基于KernelSHAP并将其扩展到序列域。TimeSHAP计算事件/时间戳、特征和单元级别的归因。由于序列可以任意长，TimeSHAP还实现了一种基于Shapley值的剪枝算法，用于找出对决策贡献最大的连续最近事件子集。

本仓库是发表在KDD 2021上的论文《TimeSHAP: 通过序列扰动解释循环模型》中TimeSHAP算法的代码实现。

论文链接在此，视频演示在此。

安装TimeSHAP

通过Pip

pip install timeshap

通过Github

使用以下命令将仓库克隆到本地目录：

git clone https://github.com/feedzai/timeshap.git

进入克隆的仓库并安装包：

cd timeshap
pip install .

测试安装

在终端中启动Python会话：

python

导入TimeSHAP

import timeshap

30秒了解TimeSHAP

输入

待解释的模型；
待解释的实例；
背景实例。

输出

局部剪枝输出；（解释单个实例）
局部事件解释；（解释单个实例）
局部特征解释；（解释单个实例）
全局剪枝统计；（解释多个实例）
全局事件解释；（解释多个实例）
全局特征解释；（解释多个实例）

模型接口

为了让TimeSHAP解释模型，必须提供一个入口点。这个Callable入口点必须接收一个3D numpy数组(序列数; 序列长度; 特征数)，并返回一个2D numpy数组(序列数; 1)，其中包含每个序列对应的分数。

此外，为了使TimeSHAP更加优化，可以选择与分数一起返回模型的隐藏状态（如果适用）。尽管这是可选的，但我们强烈建议这样做，因为它有很大的影响。如果选择返回隐藏状态，该隐藏状态应该是：（参见notebook中的具体示例）

一个3D numpy数组，(RNN层数, 序列数, 隐藏维度)（notebook中的ExplainedRNN类）；
一个numpy数组的元组，遵循前面描述的特征（通常用于使用具有不同隐藏维度的堆叠RNN时）（notebook中的ExplainedGRU2Layer类）；
一个numpy数组元组的元组（通常用于使用LSTM时）（notebook中的ExplainedLSTM类）；只要符合前面描述的接口，TimeSHAP就能解释任何黑盒模型，包括PyTorch和TensorFlow模型，这两种模型都在我们的教程中有示例（PyTorch，TensorFlow）。

我们教程中提供的示例：

TensorFlow

model = tf.keras.models.Model(inputs=inputs, outputs=ff2)
f = lambda x: model.predict(x)

PyTorch - （模型接收和返回隐藏状态的示例）

model_wrapped = TorchModelWrapper(model)
f_hs = lambda x, y=None: model_wrapped.predict_last_hs(x, y)

模型包装器

为了方便模型与TimeSHAP之间的接口，TimeSHAP实现了ModelWrappers。这些包装器在PyTorch教程笔记本中使用，它们允许更大的解释模型灵活性，因为它们允许：

批处理逻辑：在使用非常大的输入或NSamples时很有用，这些输入或NSamples无法放入GPU内存，因此需要批处理机制；
输入格式/类型：当模型不使用numpy数组时很有用。这就是我们提供的PyTorch示例的情况；
隐藏状态逻辑：当模型的隐藏状态与TimeSHAP要求的隐藏状态格式不匹配时很有用。

TimeSHAP解释方法

TimeSHAP提供了几种方法，可以根据所需的解释来使用。局部方法提供了对应于特定被解释序列的模型决策的详细视图。全局方法聚合给定数据集的局部解释，以呈现模型的全局视图。

局部解释

剪枝

local_pruning()在给定序列上执行剪枝算法，使用用户定义的容差，并返回剪枝索引以及用于绘图的信息。

plot_temp_coalition_pruning()绘制由local_pruning()计算的剪枝算法信息。

事件级解释

local_event()使用用户给定的参数计算给定序列的事件级解释，并返回相应的事件级解释。

plot_event_heatmap()绘制由local_event()计算的事件级解释。

特征级解释

local_feat()使用用户给定的参数计算给定序列的特征级解释，并返回相应的特征级解释。

plot_feat_barplot()绘制由local_feat()计算的特征级解释。

单元级解释

local_cell_level()使用相应的事件和特征级解释以及用户给定的参数计算给定序列的单元级解释，并返回相应的单元级解释。

plot_cell_level()绘制由local_cell_level()计算的特征级解释。

局部报告

local_report()计算给定序列的TimeSHAP局部解释并绘制它们。

全局解释

全局剪枝统计

prune_all()对多个给定序列执行剪枝算法。

pruning_statistics()使用prune_all()计算的剪枝数据，为多个用户给定的剪枝容差计算剪枝统计信息，返回一个包含统计信息的pandas.DataFrame。

全局事件级解释

event_explain_all()使用用户定义的参数计算多个实例的TimeSHAP事件级解释。 plot_global_event() 函数绘制由 event_explain_all() 计算得出的全局事件级别解释。

全局特征级别解释

feat_explain_all() 函数根据用户定义的参数为多个实例计算 TimeSHAP 特征级别解释。

plot_global_feat() 函数绘制由 feat_explain_all() 计算得出的全局特征级别解释。

全局报告 global_report() 函数计算多个实例的 TimeSHAP 解释，将解释汇总为两个图表并返回。

教程为了演示 TimeSHAP 接口和方法，您可以参考 AReM.ipynb。在本教程中，我们获取一个开源数据集，对其进行处理，用其训练 Pytorch 循环模型，然后使用 TimeSHAP 对其进行解释，展示了所有前面描述的方法。

此外，我们还在同一数据集上训练了一个 TensorFlow 模型 AReM_TF.ipynb。

仓库结构

notebooks - 演示该软件包的教程笔记本；
src/timeshap - 软件包源代码；
- src/timeshap/explainer - 生成解释的 TimeSHAP 方法
- src/timeshap/explainer/kernel - TimeSHAPKernel
- src/timeshap/plot - 生成解释图表的 TimeSHAP 方法
- src/timeshap/utils - TimeSHAP 执行的工具方法
- src/timeshap/wrappers - 模型的包装类，用于简化 TimeSHAP 解释

引用 TimeSHAP