shap.TreeExplainer

class shap.TreeExplainer(model: ~typing.Any, data: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~typing.Any]] | ~pandas.core.frame.DataFrame | None = None, model_output: str = 'raw', feature_perturbation: ~typing.Literal['auto', 'interventional', 'tree_path_dependent'] = 'auto', feature_names: list[str] | None = None, approximate: ~typing.Any = <object object>, link: ~typing.Any = None, linearize_link: ~typing.Any = None)

使用 Tree SHAP 算法解释集成树模型的输出。

Tree SHAP 是一种快速而精确的方法，用于在几种不同的特征依赖假设下，为树模型和树集成模型估算 SHAP 值。它依赖于外部模型包或本地编译的 C 扩展中快速的 C++ 实现。

示例

请参阅 Tree 解释器示例

__init__(model: ~typing.Any, data: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~typing.Any]] | ~pandas.core.frame.DataFrame | None = None, model_output: str = 'raw', feature_perturbation: ~typing.Literal['auto', 'interventional', 'tree_path_dependent'] = 'auto', feature_names: list[str] | None = None, approximate: ~typing.Any = <object object>, link: ~typing.Any = None, linearize_link: ~typing.Any = None) → None

为传入的模型构建一个新的 Tree 解释器。

参数:
model模型对象

我们想要解释的基于树的机器学习模型。支持 XGBoost、LightGBM、CatBoost、Pyspark 和大多数基于树的 scikit-learn 模型。

datanumpy.array 或 pandas.DataFrame

用于集成特征的背景数据集。

当 feature_perturbation="tree_path_dependent" 时，此参数是可选的，因为在这种情况下，我们可以使用每个树路径上的训练样本数量作为我们的背景数据集（这记录在 model 对象中）。

feature_perturbation“auto”（默认），“interventional” 或 “tree_path_dependent”

由于 SHAP 值依赖于条件期望，我们需要决定如何处理相关（或以其他方式依赖）的输入特征。

  • 如果为 "interventional"，则需要背景数据集 data。特征之间的依赖关系根据因果推断的规则处理 [1]。运行时与您使用的背景数据集的大小呈线性关系：100 到 1000 个随机背景样本是很好的大小。

  • 如果为 "tree_path_dependent"，则不需要背景数据集，并且方法是只遵循树并使用每个叶子路径上的训练样本数量来表示背景分布。

  • 如果为 "auto"，当提供了背景数据集时，将使用“interventional”方法，否则将使用“tree_path_dependent”方法。

0.47 版新增： 添加了 “auto” 选项。

0.47 版更改： 默认行为将从 “interventional” 更改为 “auto”。将来，未提供背景数据集而传递 feature_pertubation=”interventional” 将引发错误。

model_output“raw”、“probability”、“log_loss” 或模型方法名称

应解释的模型输出。

  • 如果为“raw”，则我们解释树的原始输出，这因模型而异。对于回归模型，“raw”是标准输出。对于 XGBoost 中的二元分类，这是对数优势比。

  • 如果为“probability”，则我们解释模型转换到概率空间的输出（请注意，这意味着 SHAP 值现在总和为模型的概率输出）。

  • 如果为“log_loss”，则我们解释模型损失函数的自然对数，以便 SHAP 值总和为每个样本的模型对数损失。这有助于按特征分解模型性能。

  • 如果 model_output 是 model 对象上受支持的预测方法的名称，则我们解释该模型方法的输出。例如，model_output="predict_proba" 解释调用 model.predict_proba 的结果。

目前，仅当 feature_perturbation="interventional" 时才支持“probability”和“log_loss”选项。

approximate布尔值

已弃用，将在 v0.47.0 中弃用，并在 v0.49.0 版本中移除。请改用 shap_values() 或 __call__ 方法中的 approximate 参数。

参考文献

[1]

Janzing, Dominik, Lenon Minorics, and Patrick Blöbaum. “Feature relevance quantification in explainable AI: A causal problem.” 国际人工智能与统计会议. PMLR, 2020。

方法

__init__(model[, data, model_output, ...])

为传入的模型构建一个新的 Tree 解释器。

assert_additivity(phi, model_output)

explain_row(*row_args, max_evals, ...)

解释单行数据并返回元组 (row_values, row_expected_values, row_mask_shapes, main_effects)。

load(in_file[, model_loader, masker_loader, ...])

从给定的文件流加载一个解释器。

save(out_file[, model_saver, masker_saver])

将解释器写入给定的文件流。

shap_interaction_values(X[, y, tree_limit])

估算一组样本的 SHAP 交互值。

shap_values(X[, y, tree_limit, approximate, ...])

为一组样本估计 SHAP 值。

supports_model_with_masker(model, masker)

判断此解释器是否能处理给定的模型。

属性

数据

data_missing

feature_perturbation

expected_value

model

model_output

data_feature_names

masker

output_names

feature_names

link

linearize_link

explain_row(*row_args: Any, max_evals: int | Literal['auto'], main_effects: bool, error_bounds: bool, outputs: Any, silent: bool, **kwargs: Any) → dict[str, Any]

解释单行数据并返回元组 (row_values, row_expected_values, row_mask_shapes, main_effects)。

这是一个抽象方法，需要由每个子类实现。

返回:
tuple

一个元组 (row_values, row_expected_values, row_mask_shapes)，其中 row_values 是每个样本的归因值数组，row_expected_values 是表示每个样本的模型期望值的数组（或单个值）（除非存在固定的输入，例如解释损失时的标签，否则所有样本的期望值都相同），而 row_mask_shapes 是所有输入形状的列表（因为 row_values 总是被展平的）。

classmethod load(in_file: Any, model_loader: Callable[..., Any] | None = None, masker_loader: Callable[..., Any] | None = None, instantiate: bool = True) → Explainer | dict[str, Any]

从给定的文件流加载一个解释器。

参数:
in_file用于加载对象的文件流。
save(out_file: Any, model_saver: str | Callable[..., Any] = '.save', masker_saver: str | Callable[..., Any] = '.save') → None

将解释器写入给定的文件流。

shap_interaction_values(X: ndarray[Any, dtype[Any]] | DataFrame | Any, y: ndarray[Any, dtype[Any]] | Series | None = None, tree_limit: int | None = None) → ndarray[Any, dtype[Any]]

估算一组样本的 SHAP 交互值。

参数:
Xnumpy.array, pandas.DataFrame 或 catboost.Pool (用于 catboost)

一个样本矩阵（# 样本数 x # 特征数），用于解释模型的输出。

ynumpy.array

每个样本的标签值数组。在解释损失函数时使用（尚未支持）。

tree_limitNone (默认) 或 int

限制模型使用的树的数量。默认情况下，使用原始模型的限制（None）。-1 表示没有限制。

返回:
np.array

返回一个矩阵。其形状取决于模型输出的数量

  • 一个输出：形状为 (#num_samples, #features, #features) 的矩阵。

  • 多个输出：形状为 (#num_samples, #features, #features, #num_outputs) 的矩阵。

每个样本的矩阵 (#num_samples, #features, #features) 之和等于该样本的模型输出与模型输出的期望值（存储在解释器的 expected_value 属性中）之间的差值。此矩阵的每行之和是该特征在该样本上的 SHAP 值。矩阵的对角线元素表示该特征对预测的“主要影响”。对称的非对角线元素表示该样本的所有特征对之间的交互影响。对于具有向量输出的模型，这将返回一个张量列表，每个输出一个。

0.45.0 版更改： 具有多个输出的模型的返回类型从列表更改为 np.ndarray。

shap_values(X: Any, y: ndarray[Any, dtype[Any]] | Series | None = None, tree_limit: int | None = None, approximate: bool = False, check_additivity: bool = True, from_call: bool = False) → ndarray[Any, dtype[Any]]

为一组样本估计 SHAP 值。

参数:
XAny

可以是类似数据框的对象，例如 numpy.array、pandas.DataFrame 或 catboost.Pool (用于 catboost)。一个样本矩阵（# 样本 x # 特征），用于解释模型的输出。

ynumpy.array

每个样本的标签值数组。在解释损失函数时使用。

tree_limitNone (默认) 或 int

限制模型使用的树的数量。默认情况下，使用原始模型的限制（None）。-1 表示没有限制。

approximate布尔值

运行速度快，但只能粗略估算 Tree SHAP 值。这运行了 Saabas 先前提出的一个方法，该方法只考虑单个特征顺序。请注意，这不具备 Shapley 值的连续性保证，并且对树中较低层的分裂赋予了过多的权重。

check_additivity布尔值

运行验证检查，确保 SHAP 值之和等于模型的输出。此检查仅需少量时间，并将捕获潜在的意外错误。请注意，此检查目前仅在解释模型边际时运行。

返回:
np.array

估计的 SHAP 值，通常形状为 (# 样本数 x # 特征数)。

每一行的总和等于该样本的模型输出与模型输出期望值（存储为解释器的 expected_value 属性）之间的差值。

返回数组的形状取决于模型输出的数量

  • 一个输出：形状为 (#num_samples, *X.shape[1:]) 的数组。

  • 多个输出：形状为 (#num_samples, *X.shape[1:], #num_outputs) 的数组。

0.45.0 版更改： 具有多个输出的模型的返回类型从列表更改为 np.ndarray。

static supports_model_with_masker(model: Any, masker: Any) → bool

判断此解释器是否能处理给定的模型。

这是一个抽象的静态方法，需要由每个子类实现。