Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
120 commits
Select commit Hold shift + click to select a range
247c1d3
Fix a bug in `_test_stationarity`
daidahao Feb 25, 2026
4c530ad
Fix a bug in `SequentialTorchInferenceDataset`
daidahao Feb 25, 2026
697a25f
Init torch explainer
daidahao Feb 25, 2026
7ce5c4e
Add notebooks for exploration
daidahao Feb 25, 2026
111e37d
Use KernelExplainer instead of Deep
daidahao Feb 25, 2026
0eec361
Add todo note
daidahao Feb 25, 2026
78ea8de
Collate `np.ndarray` directly & feature names
daidahao Feb 26, 2026
d36b052
Add `summary_plot`
daidahao Feb 26, 2026
e0999e0
Add `force_plot_from_ts`
daidahao Feb 26, 2026
4338f3a
Validate `__getitem__` index
daidahao Feb 26, 2026
65747b1
Apply inference encodings for foreground series
daidahao Feb 26, 2026
7cf1611
Move device for batch processing
daidahao Feb 26, 2026
6d9c271
Add exact explainer
daidahao Feb 26, 2026
b60a5d7
Add TCN handling
daidahao Feb 27, 2026
57f23c3
Speed up and set module to eval mode
daidahao Feb 27, 2026
71cf1c9
Misc
daidahao Feb 27, 2026
540840e
Fix a RNN test
daidahao Feb 27, 2026
43bcc38
Handle RNN module
daidahao Feb 27, 2026
6eebbe2
Fix a SHAP test
daidahao Feb 28, 2026
20148b6
Fix feature names
daidahao Feb 28, 2026
e4adb31
Add static cov support
daidahao Feb 28, 2026
3ba139a
Fix typos
daidahao Mar 2, 2026
4fb65ae
Remove static cov todo
daidahao Mar 3, 2026
17cdeb1
Add prob support
daidahao Mar 4, 2026
bda41d4
Update doc dependencies
daidahao Mar 4, 2026
fc1be29
Update sklearn notebook
daidahao Mar 4, 2026
2f18312
Fix a typo
daidahao Mar 4, 2026
7ca0258
Rename to SKLearnExplainer
daidahao Mar 4, 2026
0e3011f
Rename #2
daidahao Mar 4, 2026
8cc9490
Rename #3
daidahao Mar 4, 2026
b68eabb
Remove model attr
daidahao Mar 4, 2026
bfe9414
Fix capitailisation
daidahao Mar 4, 2026
bdbe463
Cap #2
daidahao Mar 4, 2026
5b04447
Update SKLearn explainer doc
daidahao Mar 4, 2026
b2ce2be
Cap #3
daidahao Mar 4, 2026
9e2fb79
Update SK force plot and summary plot
daidahao Mar 4, 2026
1c1751d
Update force plot name
daidahao Mar 4, 2026
798ad7b
Update torch force and summary plots
daidahao Mar 4, 2026
364e589
Update SK doc
daidahao Mar 4, 2026
905fd15
Update SK header
daidahao Mar 4, 2026
a2b3844
Update SK force plot docstring
daidahao Mar 5, 2026
2ccf1cd
Add static cov convention
daidahao Mar 6, 2026
546dcbe
Remove RNN docstring errors
daidahao Mar 6, 2026
6c38b44
Torch explainer doc header
daidahao Mar 6, 2026
349943b
Update header doc
daidahao Mar 6, 2026
7cf4c39
Add torch explainer docstring
daidahao Mar 6, 2026
03689fa
Add `explain()` docstring
daidahao Mar 6, 2026
9e99ad1
Add `summary_plot()` and `force_plot()` docstring
daidahao Mar 6, 2026
0100951
Add `explain_single()` to torch explainer
daidahao Mar 6, 2026
4e9f093
Fix bugs for shap object
daidahao Mar 7, 2026
63d941f
Update result classes docstring
daidahao Mar 7, 2026
8b47c56
Update result header
daidahao Mar 7, 2026
3bcc96f
Add `explain_single` docstring
daidahao Mar 7, 2026
68a1289
Add `explain_single()` to sklearn explainer
daidahao Mar 10, 2026
1b2957e
Update doc header and add note
daidahao Mar 10, 2026
14a6e0b
Add creation test
daidahao Mar 10, 2026
496511d
Add chronos2 to tests
daidahao Mar 10, 2026
07647a1
Add comments
daidahao Mar 10, 2026
54b8082
Add explain test
daidahao Mar 11, 2026
aa40d8e
Expand explain test
daidahao Mar 11, 2026
e9a4b80
Reduce test time
daidahao Mar 11, 2026
01542c8
Add explain without foreground test
daidahao Mar 12, 2026
86674c2
Add explain with shap methods test
daidahao Mar 12, 2026
e281ca5
Add explain probabilistic test
daidahao Mar 12, 2026
049cc04
Add test_explain_multiple_series
daidahao Mar 12, 2026
2338c0c
Add explain single test
daidahao Mar 12, 2026
a7ff08f
Add explain single without background test
daidahao Mar 12, 2026
a072812
Add test explain single shape methods
daidahao Mar 12, 2026
09ff9d7
Add test_explain_single_probabilistic_model
daidahao Mar 13, 2026
e705a35
Add test_summary_plot
daidahao Mar 13, 2026
3467fb0
Add test_force_plot
daidahao Mar 13, 2026
be0ef16
Add test_waterfall_plot
daidahao Mar 13, 2026
5efb075
Improve code coverage of torch explainer
daidahao Mar 13, 2026
7d54b86
Improve code coverage
daidahao Mar 13, 2026
a328af0
Improve tests
daidahao Mar 13, 2026
3340b2c
Add test_explain_single
daidahao Mar 13, 2026
e27f221
Improve code cov.
daidahao Mar 13, 2026
3542230
Improve code cov.
daidahao Mar 13, 2026
396bfae
Improve code coverage
daidahao Mar 13, 2026
de3ce84
Improve code cov.
daidahao Mar 13, 2026
ef00354
Improve #5
daidahao Mar 13, 2026
ab20ab6
Add test_explain_univariate for torch
daidahao Mar 13, 2026
3188703
Bugfix: trim series when future cov too short
daidahao Mar 14, 2026
8ade0e2
Bugfix: too short future covs. when training
daidahao Mar 14, 2026
6d60d14
Add notebook draft
daidahao Mar 15, 2026
b3ebb16
Fix a notebook bug
daidahao Mar 15, 2026
a64d3fa
Revert "Update doc dependencies"
daidahao Mar 15, 2026
895c4e6
Update Makefile for faster compilation
daidahao Mar 15, 2026
1e5f7df
Complete global explanation
daidahao Mar 15, 2026
023e062
Add Local Explainability
daidahao Mar 16, 2026
c02e0d8
Add force plot
daidahao Mar 16, 2026
9e96df8
Complete local explanability
daidahao Mar 16, 2026
bb248a6
Add pytorch model to notebook
daidahao Mar 17, 2026
6f27f94
Update header
daidahao Mar 17, 2026
97472e6
Add labels to info and warning
daidahao Mar 17, 2026
74f3139
Supress warnings
daidahao Mar 17, 2026
d380369
Update docs and remove `raise_if`
daidahao Mar 17, 2026
b283825
Fix typos
daidahao Mar 17, 2026
97967dc
Complete notebook
daidahao Mar 18, 2026
542e59d
Remove unused files
daidahao Mar 18, 2026
87446e8
Change default to permutation
daidahao Mar 19, 2026
c318c07
Add reference to notebook
daidahao Mar 19, 2026
a9954ee
Update PR note
daidahao Mar 19, 2026
fdb1ca8
Rename to 29- notebook
daidahao Mar 19, 2026
3da9b4a
Add notebook links
daidahao Mar 19, 2026
1bfaf12
Update tests
daidahao Mar 19, 2026
866a5f2
Pass along optional kwargs to SHAP
daidahao Mar 19, 2026
c6aa6a3
Update `plot_kwargs` in tests
daidahao Mar 19, 2026
554cb58
Relax base value threshold in tests
daidahao Mar 19, 2026
9fb08d6
Add API reference
daidahao Mar 19, 2026
5f45b51
Update changelog
daidahao Mar 21, 2026
181358b
Update PR note
daidahao Mar 21, 2026
fcbb4b6
Update #2
daidahao Mar 21, 2026
00fc092
Fix typos
daidahao Mar 27, 2026
4407546
Lint
daidahao Mar 27, 2026
273953a
Update CHANGELOG
daidahao Mar 27, 2026
b4aa527
Merge branch 'master' into feature/shap-torch
daidahao Mar 28, 2026
999b8b8
Fix nb name typos
daidahao Mar 29, 2026
bf1a1cc
Fix Partition explainer typo
daidahao Mar 30, 2026
c148909
Merge branch 'master' into feature/shap-torch
daidahao Mar 31, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/merge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, ...)
Expand Down
26 changes: 20 additions & 6 deletions darts/explainability/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
4 changes: 3 additions & 1 deletion darts/explainability/explainability.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
(
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
Loading
Loading