用于回归模型的 Shap Explainer

专用于时间序列预测模型的 shap explainer。

此类（目前）仅限于 Darts 中预测模型的 RegressionModel 实例。它使用 shap 值来提供每个输入特征的“解释”。输入特征包括不同的过去滞后（目标和/或过去协变量的），以及预测模型用于产生预测的未来协变量的潜在未来滞后。此外，在多元时间序列的情况下，特征包含每个（滞后）时间序列的每个维度。

注意

此 explainer 受用于计算 shap 值的常见特征独立性假设的限制。这意味着它无法捕捉某些滞后通过影响其他滞后而可能对目标产生的潜在间接影响。

  • explain() 为给定的前景时间序列生成解释（如果未提供前景，则为背景时间序列）。

  • summary_plot() 显示目标时间序列的每个预测范围和每个分量维度的 shap 图摘要。

  • force_plot_from_ts() 为给定的目标时间序列显示一个目标和一个预测范围的 shap force_plot。它以累加力的布局显示每个滞后/协变量的 shap 值。

    布局。

class darts.explainability.shap_explainer.ShapExplainer(model, background_series=None, background_past_covariates=None, background_future_covariates=None, background_num_samples=None, shap_method=None, **kwargs)[source]

基类: _ForecastingModelExplainer

定义

  • 背景时间序列是用于训练 shap explainer 的 TimeSeries。

  • 前景时间序列是经过拟合后可以由 shap explainer 解释的 TimeSeries。

目前，ShapExplainer 只适用于 RegressionModel 预测模型。可解释的预测范围数量 (t+1, t+2, …) 最多等于 model 的 output_chunk_length。

参数

  • model (darts.models.forecasting.regression_model.RegressionModel) – 需要解释的 RegressionModel。必须先进行拟合。

  • background_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 用于与任何前景时间序列一起训练 ShapExplainer 的一个或多个时间序列。考虑使用精简且精心挑选的背景时间序列以减少计算时间。如果 model 是在单个目标时间序列上拟合的，则此参数是可选的。默认情况下，它是在拟合时使用的 series。如果 model 是在多个（列表形式的）目标时间序列上拟合的，则此参数是强制性的。

  • background_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 模型拟合后所需的过去协变量时间序列或时间序列列表。

  • background_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 模型拟合后所需的未来协变量时间序列或时间序列列表。

  • background_num_samples (Optional[int, None]) – 可选参数，是否对原始背景时间序列进行抽样。随机抽取构建的训练数据集中的 background_num_samples 个训练样本（使用 shap.utils.sample()）。通常用于加速计算，特别是当 shap_method 为 "kernel" 或 "permutation" 时。

  • shap_method (Optional[str, None]) – 可选参数，要应用的 shap 方法。默认情况下，将尝试根据已知模型集中的预定义内部映射来选择最合适的方法。支持的值："permutation", "partition", "tree", "kernel", "sampling", "linear", "deep", "gradient", "additive"。

  • **kwargs – 可选参数，传递给 shap_method 的其他关键字参数。

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.explainability.shap_explainer import ShapExplainer
>>> from darts.models import LinearRegressionModel
>>> series = AirPassengersDataset().load()
>>> model = LinearRegressionModel(lags=12)
>>> model.fit(series[:-36])
>>> shap_explain = ShapExplainer(model)
>>> results = shap_explain.explain()
>>> shap_explain.summary_plot()
>>> shap_explain.force_plot_from_ts()

方法

explain([前景时间序列, ...])

解释前景时间序列并返回 ShapExplainabilityResult。

force_plot_from_ts([前景时间序列, ...])

为给定的前景时间序列显示一个目标和一个预测范围的 shap force_plot。

summary_plot([预测范围, 目标分量, ...])

显示目标每个预测范围和每个分量维度的 shap 图摘要。
explain(foreground_series=None, foreground_past_covariates=None, foreground_future_covariates=None, horizons=None, target_components=None)[source]

解释前景时间序列并返回 ShapExplainabilityResult。可以使用方法 get_explanation() 获取结果。结果是一个多元 TimeSeries 实例，包含对应于前景 TimeSeries 输入的任何可预测时间戳处（预测范围，目标分量）预测的“解释”。

此多元 TimeSeries 的分量命名约定为："{name}_{type_of_cov}_lag_{idx}"，其中

  • {name} 是原始前景时间序列（目标、过去或未来）的分量名称。

  • {type_of_cov} 是协变量类型。它可以取以下 3 个不同值："target", "past_cov" 或 "future_cov"。

  • {idx} 是滞后索引。

参数

  • foreground_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，需要解释的一个或多个目标 TimeSeries。可以是多元的。如果未提供，将改为解释背景 TimeSeries。

  • foreground_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，如果预测模型需要，提供一个或多个过去协变量 TimeSeries。

  • foreground_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，如果预测模型需要，提供一个或多个未来协变量 TimeSeries。

  • horizons (Optional[Sequence[int], None]) – 可选参数，一个整数或整数序列，表示需要解释的未来时间步长。1 对应于第一个预测时间戳。所有值必须 <= 解释的预测模型的 output_chunk_length。

  • target_components (Optional[Sequence[str], None]) – 可选参数，一个字符串或字符串序列，表示需要解释的目标分量。

返回值

预测解释结果

返回值类型

ShapExplainabilityResult

示例

假设我们有一个模型，包含 2 个目标分量，命名为 "T_0" 和 "T_1"，3 个过去协变量，默认分量名称为 "0", "1", 和 "2"，以及一个未来协变量，默认分量名称为 "0"。同时，horizons = [1, 2]。该模型是一个回归模型，具有 lags = 3，lags_past_covariates=[-1, -3]，lags_future_covariates = [0]。

我们提供长度为 5 的 foreground_series，foreground_past_covariates 和 foreground_future_covariates。

>>> explain_results = explainer.explain(
>>>     foreground_series=foreground_series,
>>>     foreground_past_covariates=foreground_past_covariates,
>>>     foreground_future_covariates=foreground_future_covariates,
>>>     horizons=[1, 2],
>>>     target_names=["T_0", "T_1"])
>>> output = explain_results.get_explanation(horizon=1, component="T_1")
>>> feature_values = explain_results.get_feature_values(horizon=1, component="T_1")
>>> shap_objects = explain_results.get_shap_explanation_objects(horizon=1, component="T_1")

然后该方法返回一个多元 TimeSeries，其中包含 ShapExplainer 的解释，分量名称如下

  • T_0_target_lag-1

  • T_0_target_lag-2

  • T_0_target_lag-3

  • T_1_target_lag-1

  • T_1_target_lag-2

  • T_1_target_lag-3

  • 0_past_cov_lag-1

  • 0_past_cov_lag-3

  • 1_past_cov_lag-1

  • 1_past_cov_lag-3

  • 2_past_cov_lag-1

  • 2_past_cov_lag-3

  • 0_fut_cov_lag_0

此时间序列长度为 3，因为模型可以解释 5-3+1 个预测（时间戳索引 4、5 和 6）

force_plot_from_ts(foreground_series=None, foreground_past_covariates=None, foreground_future_covariates=None, horizon=1, target_component=None, **kwargs)[source]

为给定的前景时间序列显示一个目标和一个预测范围的 shap force_plot。它以累加力的布局显示每个滞后/协变量的 shap 值。

显示图表后，选择“原始样本顺序”以按时间顺序观察时间序列。

参数

  • foreground_series (Optional[TimeSeries, None]) – 可选参数，需要解释的目标时间序列。可以是多元的。如果为 None，将使用 background_series。

  • foreground_past_covariates (Optional[TimeSeries, None]) – 可选参数，如果预测模型需要，提供一个过去协变量时间序列。如果为 None，将使用 background_past_covariates。

  • foreground_future_covariates (Optional[TimeSeries, None]) – 可选参数，如果预测模型需要，提供一个未来协变量时间序列。如果为 None，将使用 background_future_covariates。

  • horizon (Optional[int, None]) – 可选参数，一个整数，表示需要解释的未来点/步长，从第一个预测步长 1 开始。horizons 不能大于 output_chunk_length。

  • target_component (Optional[str, None]) – 可选参数，要绘制的目标分量。如果目标时间序列是多元的，则必须指定目标分量。

  • **kwargs – 可选参数，传递给 shap.force_plot() 的其他关键字参数。

model: RegressionModel
summary_plot(horizons=None, target_components=None, num_samples=None, plot_type='dot', **kwargs)[source]

显示目标每个预测范围和每个分量维度的 shap 图摘要。此方法重用初始背景数据作为前景（可能经过抽样），以提供每个特征的整体重要性图。如果未提供目标名称和/或预测范围，则会生成所有摘要图。

参数

  • horizons (Union[int, Sequence[int], None]) – 可选参数，一个整数或整数序列，表示需要解释的未来点/步长，从第一个预测步长 1 开始。horizons 必须 <= 预测模型的 output_chunk_length。

  • target_components (Union[str, Sequence[str], None]) – 可选参数，一个字符串或字符串序列，表示需要解释的目标分量。

  • num_samples (Optional[int, None]) – 可选参数，一个整数，用于对前景时间序列（基于背景）进行抽样，以提高性能。

  • plot_type (Optional[str, None]) – 可选参数，指定使用 shap 库的哪种图表类型。可以是 'dot', 'bar', 'violin' 之一。

返回值

一个嵌套字典 {预测范围 : {分量 : shap.Explanation}}，包含所有预测范围和分量的原始解释。

返回值类型

shaps_

上一页

可解释性结果

下一页

用于 Temporal Fusion Transformer (TFTModel) 的 TFT Explainer