[Feature] SHAP-based explainer for torch models

.github/workflows/merge.yml

@@ -96,7 +96,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        example-name: [00-quickstart.ipynb, 01-multi-time-series-and-covariates.ipynb, 02-data-processing.ipynb, 03-FFT-examples.ipynb, 04-RNN-examples.ipynb, 05-TCN-examples.ipynb, 06-Transformer-examples.ipynb, 07-NBEATS-examples.ipynb, 08-DeepAR-examples.ipynb, 09-DeepTCN-examples.ipynb, 10-Kalman-filter-examples.ipynb, 11-GP-filter-examples.ipynb, 12-Dynamic-Time-Warping-example.ipynb, 13-TFT-examples.ipynb, 15-static-covariates.ipynb, 16-hierarchical-reconciliation.ipynb, 18-TiDE-examples.ipynb, 19-EnsembleModel-examples.ipynb, 20-SKLearnModel-examples.ipynb, 21-TSMixer-examples.ipynb, 22-anomaly-detection-examples.ipynb, 23-Conformal-Prediction-examples.ipynb, 24-SKLearnClassifierModel-examples.ipynb, 25-FoundationModel-examples.ipynb, 26-NeuralForecast-examples.ipynb, 27-Torch-and-Foundation-Model-Fine-Tuning-examples.ipynb]
+        example-name: [00-quickstart.ipynb, 01-multi-time-series-and-covariates.ipynb, 02-data-processing.ipynb, 03-FFT-examples.ipynb, 04-RNN-examples.ipynb, 05-TCN-examples.ipynb, 06-Transformer-examples.ipynb, 07-NBEATS-examples.ipynb, 08-DeepAR-examples.ipynb, 09-DeepTCN-examples.ipynb, 10-Kalman-filter-examples.ipynb, 11-GP-filter-examples.ipynb, 12-Dynamic-Time-Warping-example.ipynb, 13-TFT-examples.ipynb, 15-static-covariates.ipynb, 16-hierarchical-reconciliation.ipynb, 18-TiDE-examples.ipynb, 19-EnsembleModel-examples.ipynb, 20-SKLearnModel-examples.ipynb, 21-TSMixer-examples.ipynb, 22-anomaly-detection-examples.ipynb, 23-Conformal-Prediction-examples.ipynb, 24-SKLearnClassifierModel-examples.ipynb, 25-FoundationModel-examples.ipynb, 26-NeuralForecast-examples.ipynb, 27-Torch-and-Foundation-Model-Fine-Tuning-examples.ipynb, 28-Explainability-examples.ipynb]
     steps:
       - name: "Clone repository"
         uses: actions/checkout@v6

CHANGELOG.md

@@ -15,12 +15,24 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 
 **Improved**
 
+- Improvements to `ShapExplainer` : [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+  - 🚀🚀 `ShapExplainer` can now also explain any `TorchForecastingModel` including regular torch models (`TiDEModel`, ...) as well as foundation models (`Chronos2`, ...). It supports global and local explanations and can output SHAP values for further analysis.
+  - Added method `explain_single()` to explain a single model forecast in detail, in addition to the existing batched method `explain()`. This is useful for local explanations of individual predictions with reduced computational cost.
+  - Method `summary_plot()` can now also be computed on any optional foreground series using parameters `foreground_series`, `foreground_past_covariates`, `foreground_future_covariates`.
+  - 🔴 Renamed method `force_plot_from_ts()` to `force_plot()` to simplify.
+  - Added a new [Explainability of Forecasting Models Notebook](https://unit8co.github.io/darts/examples/28-Explainability-examples.html) for detailed usage of `ShapExplainer`.
+
 **Fixed**
 
+- Fixed several bugs in `ShapExplainer` including mismatched SHAP method enum values, feature naming conventions, inconsistent instance count in `explain()`. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+- Fixed a bug in explainability utils where stationarity tests were not properly conducted due to usage of `all()`. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+
 **Dependencies**
 
 ### For developers of the library:
 
+- Added `ShapSingleExplainabilityResult` class as the return type of `explain_single()` method in `ShapExplainer` and `TorchExplainer` and to store the SHAP results of a single instance explanation. This is in contrast to the existing `ShapExplainabilityResult` which stores results for batched explanations. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+
 ## [0.44.1](https://github.com/unit8co/darts/tree/0.44.1) (2026-05-05)
 
 ### For users of the library:

darts/explainability/__init__.py

@@ -4,6 +4,17 @@
 
 Tools for explaining and interpreting forecasting model predictions, including SHAP-based explainers and
 model-specific explainability methods.
+
+`SHAP <https://github.com/slundberg/shap>`__-Based Explainers
+-------------------------------------------------------------
+- :class:`~darts.explainability.shap_explainer.ShapExplainer`: SHAP-based explainer for Darts' SKLearn
+  and Torch Models.
+
+Model-Specific Explainers
+-------------------------
+- :class:`~darts.explainability.tft_explainer.TFTExplainer`: Explainer for
+  :class:`TFTModel <darts.models.forecasting.tft_model.TFTModel>`.
+
 """
 
 from typing import TYPE_CHECKING
@@ -15,18 +26,21 @@
         ShapExplainabilityResult as ShapExplainabilityResult,
     )
     from darts.explainability.explainability_result import (
-        TFTExplainabilityResult as TFTExplainabilityResult,
+        ShapSingleExplainabilityResult as ShapSingleExplainabilityResult,
     )
     from darts.explainability.explainability_result import (
-        _ExplainabilityResult as _ExplainabilityResult,
+        TFTExplainabilityResult as TFTExplainabilityResult,
     )
     from darts.explainability.shap_explainer import ShapExplainer as ShapExplainer
     from darts.explainability.tft_explainer import TFTExplainer as TFTExplainer
 
 _LAZY_IMPORTS: dict[str, tuple[str, str | None]] = {
     "ShapExplainabilityResult": ("darts.explainability.explainability_result", None),
+    "ShapSingleExplainabilityResult": (
+        "darts.explainability.explainability_result",
+        None,
+    ),
     "TFTExplainabilityResult": ("darts.explainability.explainability_result", None),
-    "_ExplainabilityResult": ("darts.explainability.explainability_result", None),
     "ShapExplainer": ("darts.explainability.shap_explainer", None),
     "TFTExplainer": ("darts.explainability.tft_explainer", "(Py)Torch"),
 }

darts/explainability/explainability.py

@@ -66,6 +66,11 @@ def __init__(
         test_stationarity
             Whether to raise a warning if not all `background_series` are stationary.
         """
+        if not isinstance(model, ForecastingModel):
+            raise_log(
+                ValueError("`model` must be a Darts `ForecastingModel` object."),
+                logger,
+            )
         if not model._fit_called:
             raise_log(
                 ValueError(
@@ -75,18 +80,20 @@ def __init__(
             )
         self.model = model
         # default forecasting horizon
-        self.n: int | None = getattr(self.model, "output_chunk_length", None)
+        self.n: int = self.model.output_chunk_length or 1
 
         # check background input validity and process it
         (
             self.background_series,
             self.background_past_covariates,
             self.background_future_covariates,
             self.target_components,
+            self.target_components_likelihood,
             self.static_covariates_components,
             self.past_covariates_components,
             self.future_covariates_components,
         ) = process_input(
+            n=self.n,
             model=model,
             input_type="background",
             series=background_series,
@@ -148,6 +155,7 @@ def _process_foreground(
         foreground_future_covariates: TimeSeriesLike | None = None,
     ):
         return process_input(
+            n=self.n,
             model=self.model,
             input_type="foreground",
             series=foreground_series,
@@ -171,6 +179,6 @@ def _process_horizons_and_targets(
             horizons=horizons,
             fallback_horizon=self.n,
             target_components=target_components,
-            fallback_target_components=self.target_components,
+            fallback_target_components=self.target_components_likelihood,
             check_component_names=self.check_component_names,
         )