[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-Chronos-2-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-Chronos-2-examples.ipynb, 26-NeuralForecast-examples.ipynb, 27-Torch-and-Foundation-Model-Fine-Tuning-examples.ipynb, 29-Explainability-examples.ipynb]
     steps:
       - name: "Clone repository"
         uses: actions/checkout@v4

CHANGELOG.md

@@ -9,14 +9,26 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 
 ### For users of the library:
 
+- 🚀🚀 Added SHAP-based explainer `TorchExplainer` for torch forecasting models. This allows for explaining the predictions of any `TorchForecastingModel` with SHAP permutation explainer and others, in a consistent API with existing `SKLearnExplainer`. It supports global and local explanations and can output SHAP values for further analysis. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+  - Check out the new [Explainability of Forecasting Models Notebook](https://unit8co.github.io/darts/examples/29-Explainability-examples.html) for usage of `SKLearnExplainer` and `TorchExplainer`.
+- 🔴 Renamed `ShapExplainer` to `SKLearnExplainer` to better reflect its scope of explaining sklearn-based models. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+- Added `explain_single()` method to `SKLearnExplainer` and `TorchExplainer` to allow explaining a single forecast instance, in addition to the existing batched method `explain()`. This is useful for local explanations of individual predictions with reduced computational cost. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
 - Added native multi-quantile support for `CatBoostModel` by using CatBoost’s `MultiQuantile` loss for faster training and inference. Set `likelihood="multiquantile"` to enable this feature. [#3032](https://github.com/unit8co/darts/pull/3032) by [Zhihao Dai](https://github.com/daidahao)
 
 **Fixed**
 
 - Fixed a device mismatch error in `TFTModel` when moving a trained model to a different device (e.g., GPU to CPU for ONNX export). `attention_mask` and `relative_index` are now registered as non-persistent buffers so they are properly moved with the model. [#3053](https://github.com/unit8co/darts/pull/3053) by [Wolfhart Feldmeier](https://github.com/trahflow)
+- Fixed several bugs in `SKLearnExplainer` 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).
+- Fixed rendering issues of `CustomBlockRNNModule` and `CustomRNNModule` in the documentation. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+- Fixed rendering issues of `20-SKLearnModel-examples` notebook in the documentation. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+
 
 ### For developers of the library:
 
+- Added `SHAPSingleExplainabilityResult` class as the return type of `explain_single()` method in `SKLearnExplainer` 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).
+- Sped up the documentation build by utilizing multiple CPU cores. [#3049](https://github.com/unit8co/darts/pull/3049) by [Zhihao Dai](https://github.com/daidahao).
+
 ## [0.43.0](https://github.com/unit8co/darts/tree/0.43.0) (2026-03-23)
 
 ### For users of the library:
@@ -31,6 +43,12 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
   - 🔴 `plot_attention()` now also returns the matplotlib figures for all explained series, instead of only the matplotlib axis for the last series.
 - `TorchForecastingModel` now raises a warning when the input series have mixed data types, or the prediction series do not have the same data type as the series used for training. [#3043](https://github.com/unit8co/darts/pull/3043) by [Oswald Zink](https://github.com/ozink-u8)
 
+**Fixed**
+
+**Dependencies**
+
+### For developers of the library:
+
 ## [0.42.1](https://github.com/unit8co/darts/tree/0.42.1) (2026-03-07)
 
 ### For users of the library:

README.md

@@ -198,7 +198,7 @@ series.plot()
   This is useful for example for Day-Ahead Market forecasts, or when the covariates (or target series) are reported
   with a delay.
 
-* **Explainability:** Darts has the ability to *explain* some forecasting models using Shap values.
+* **Explainability:** Darts has the ability to *explain* some forecasting models using SHAP values.
 
 * **Data Processing:** Tools to easily apply (and revert) common transformations on
   time series data (scaling, filling missing values, differencing, boxcox, ...)

darts/explainability/__init__.py

@@ -4,32 +4,46 @@
 
 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.sklearn_explainer.SKLearnExplainer`: SHAP-based explainer for SKLearn models.
+- :class:`~darts.explainability.torch_explainer.TorchExplainer`: SHAP-based explainer for PyTorch models.
+
+Model-Specific Explainers
+-------------------------
+- :class:`~darts.explainability.tft_explainer.TFTExplainer`: Explainer for
+  :class:`TFTModel <darts.models.forecasting.tft_model.TFTModel>`.
+
 """
 
 from darts.explainability.explainability_result import (
-    ShapExplainabilityResult,
+    SHAPExplainabilityResult,
+    SHAPSingleExplainabilityResult,
     TFTExplainabilityResult,
-    _ExplainabilityResult,
 )
-from darts.explainability.shap_explainer import ShapExplainer
+from darts.explainability.sklearn_explainer import SKLearnExplainer
 from darts.logging import get_logger
 from darts.utils.utils import NotImportedModule
 
 logger = get_logger(__name__)
 try:
     from darts.explainability.tft_explainer import TFTExplainer
+    from darts.explainability.torch_explainer import TorchExplainer
 except ModuleNotFoundError:
     logger.warning(
         "Support for Torch based explainers not available. "
         'To enable them, install "darts[torch]" or "darts[all]" (with pip); '
         'or "u8darts-torch" or "u8darts-all" (with conda).'
     )
     TFTExplainer = NotImportedModule(module_name="(Py)Torch", warn=False)
+    TorchExplainer = NotImportedModule(module_name="(Py)Torch", warn=False)
 
 __all__ = [
-    "ShapExplainabilityResult",
+    "SHAPExplainabilityResult",
+    "SHAPSingleExplainabilityResult",
     "TFTExplainabilityResult",
-    "_ExplainabilityResult",
-    "ShapExplainer",
+    "SKLearnExplainer",
     "TFTExplainer",
+    "TorchExplainer",
 ]

darts/explainability/explainability.py

@@ -75,7 +75,7 @@ def __init__(
             )
         self.model = model
         # default forecasting horizon
-        self.n: int | None = getattr(self.model, "output_chunk_length", None)
+        self.n: int = getattr(self.model, "output_chunk_length", None) or 1
 
         # check background input validity and process it
         (
@@ -87,6 +87,7 @@ def __init__(
             self.past_covariates_components,
             self.future_covariates_components,
         ) = process_input(
+            n=self.n,
             model=model,
             input_type="background",
             series=background_series,
@@ -148,6 +149,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,