Explainability Result#

Contains the explainability results obtained from _ForecastingModelExplainer.explain().

ShapExplainabilityResult for ShapExplainer. Contains general forecasting model explainability result based on SHAP values.
ShapSingleExplainabilityResult for ShapExplainer. Contains the explainability result for a single model forecast.
TFTExplainabilityResult for TFTExplainer.
ComponentBasedExplainabilityResult for generic component-based explainability result.
HorizonBasedExplainabilityResult for generic horizon-based explainability results.

class darts.explainability.explainability_result.ComponentBasedExplainabilityResult(explained_components)[source]#

Bases: _ExplainabilityResult

Stores the explainability results of a _ForecastingModelExplainer with convenient access to component-based results.

Parameters:: explained_components (dict[str, Any] | list[dict[str, Any]]) – The component-based explainability results.

Examples

>>> explainer = SomeComponentBasedExplainer(model)
>>> result = explainer.explain()
>>> explanation = result.get_explanation(component="some_component")

Methods

get_explanation([component])

Returns one or several explanations for a given component.

get_explanation(component=None)[source]#

Returns one or several explanations for a given component.

Parameters:: component (str | None) – Optionally, the target series component for which to return the explanation. Must be supplied for multivariate forecasting models.
Return type:: Any | list[Any]

class darts.explainability.explainability_result.HorizonBasedExplainabilityResult(explained_forecasts)[source]#

Bases: _ExplainabilityResult

Stores the explainability results of a _ForecastingModelExplainer with convenient access to horizon-based results.

The result is a multivariate TimeSeries instance containing the “explanation” for the (horizon, target_component) forecast at any timestamp forecastable in the foreground series.

The components of the TimeSeries correspond to the input features used by the model to produce the forecasts. They are named according to the convention: "{name}_{type_of_cov}_lag{idx}", where:

{name} is the component name from the original foreground series (target, past covariates, or future covariates).
{type_of_cov} is the covariates type. It can take 3 different values: "target", "pastcov", "futcov".
{idx} is the lag index, where 0 represents the position of the first predicted step.

Static covariates are named according to the convention: "{name}_statcov_target_{comp}", where:

{name} is the variable name of the static covariate.
{comp} is the component name of the target series if static covariates are component-specific, or "global_components" if they are global.

Examples

Say we have a SKLearnModel instance with:

1 target component named "Y",

1 future covariate named "month",

lags = 2, and lags_future_covariates = [-1, 0].

Let’s explain the background series that the model was trained on:

>>> from darts.datasets import AusBeerDataset
>>> from darts.explainability import ShapExplainer
>>> from darts.models import LinearRegressionModel
>>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dta
>>>
>>> # load a target series and create future covariates holding the calendar month values
>>> series = AusBeerDataset().load()
>>> fc = dta(series, attribute="month", add_length=12)
>>>
>>> # create and fit a model
>>> model = LinearRegressionModel(lags=2, lags_future_covariates=[-1, 0])
>>> model.fit(series, future_covariates=fc)
>>>
>>> # create an explainer; requires background series if the model was trained on multiple series
>>> explainer = ShapExplainer(model)
>>> # explain the background series (or foreground if passed to `explain()`)
>>> result = explainer.explain()
>>> result.get_explanation(horizon=1)
            Y_target_lag-2  Y_target_lag-1  month_futcov_lag-1  month_futcov_lag0
1956-07-01      -56.332566     -106.927156          -24.253184          33.064478
1956-10-01      -88.545937      -99.569541           13.642416          84.727725
1957-01-01      -82.194005      -57.000488           51.538016         -70.262016
1957-04-01      -45.443539      -81.175506          -62.148784         -18.598769
1957-07-01      -66.314174      -99.043998          -24.253184          33.064478
...                    ...             ...                 ...                ...
2007-10-01      -11.415330      -11.803715           13.642416          84.727725
2008-01-01       -6.424526       29.714250           51.538016         -70.262016
2008-04-01       29.418521        1.860425          -62.148784         -18.598769
2008-07-01        5.371920      -13.905891          -24.253184          33.064478
2008-10-01       -8.239364       -3.395013           13.642416          84.727725

shape: (210, 4, 1), freq: QS-OCT, size: 6.56 KB

The explanation has length 210, containing the feature SHAP values for all possible forecast start points over the background series.

Methods

get_explanation(horizon[, component])

Returns one or several TimeSeries representing the explanations for a given horizon and component.

get_explanation(horizon, component=None)[source]#

Returns one or several TimeSeries representing the explanations for a given horizon and component.

Parameters:

horizon (int) – The horizon for which to return the explanation.
component (str | None) – Optionally, the target series component for which to return the explanation. Must be supplied for multivariate forecasting models.

Return type:

TimeSeries | list[TimeSeries]

class darts.explainability.explainability_result.ShapExplainabilityResult(explained_forecasts, feature_values, shap_explanation_object)[source]#

Bases: HorizonBasedExplainabilityResult

Stores the explainability results of a ShapExplainer with convenient access to the results.

It extends the HorizonBasedExplainabilityResult and carries additional information specific to the SHAP explainers.

get_explanation(): SHAP values for a given horizon and component in multivariate TimeSeries format.
get_feature_values(): input feature values for a given horizon and component in multivariate TimeSeries format.
get_shap_explanation_object(): shap.Explanation object for a given horizon and component.

Examples

>>> from darts.datasets import AusBeerDataset
>>> from darts.explainability import ShapExplainer
>>> from darts.models import LinearRegressionModel
>>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dta
>>>
>>> # load a target series and create future covariates holding the calendar month values
>>> series = AusBeerDataset().load()
>>> fc = dta(series, attribute="month", add_length=12)
>>>
>>> # create and fit a model
>>> model = LinearRegressionModel(lags=2, lags_future_covariates=[-1, 0])
>>> model.fit(series, future_covariates=fc)
>>>
>>> # create an explainer; requires background series if the model was trained on multiple series
>>> explainer = ShapExplainer(model)
>>> # explain the background series (or foreground if passed to `explain()`)
>>> result = explainer.explain()
>>>
>>> # get explanations for a specific horizon (and optional component for multivariate models)
>>> # the feature SHAP values for all possible forecast start points
>>> explanation = result.get_explanation(horizon=1)
>>> # the feature values used as model inputs for all possible forecast start points
>>> feature_values = result.get_feature_values(horizon=1)
>>> # the raw shap objects for further processing
>>> shap_object = result.get_shap_explanation_object(horizon=1)

Methods

`get_explanation`(horizon[, component])	Returns one or several `TimeSeries` representing the explanations for a given horizon and component.
`get_feature_values`(horizon[, component])	Returns one or several `TimeSeries` representing the feature values for a given horizon and component.
`get_shap_explanation_object`(horizon[, component])	Returns the underlying `shap.Explanation` object for a given horizon and component.

get_explanation(horizon, component=None)#

Returns one or several TimeSeries representing the explanations for a given horizon and component.

Parameters:

horizon (int) – The horizon for which to return the explanation.
component (str | None) – Optionally, the target series component for which to return the explanation. Must be supplied for multivariate forecasting models.

Return type:

TimeSeries | list[TimeSeries]

get_feature_values(horizon, component=None)[source]#

Returns one or several TimeSeries representing the feature values for a given horizon and component.

Parameters:

horizon (int) – The horizon for which to return the feature values.
component (str | None) – Optionally, the target series component for which to return the feature values. Must be supplied for multivariate forecasting models.

Return type:

TimeSeries | list[TimeSeries]

get_shap_explanation_object(horizon, component=None)[source]#

Returns the underlying shap.Explanation object for a given horizon and component.

Parameters:

horizon (int) – The horizon for which to return the shap.Explanation object.
component (str | None) – Optionally, the target series component for which to return the shap.Explanation object. Must be supplied for multivariate forecasting models.

Return type:

Explanation | list[Explanation]

class darts.explainability.explainability_result.ShapSingleExplainabilityResult(explained_components, feature_values, shap_explanation_object)[source]#

Bases: ComponentBasedExplainabilityResult

Stores the explainability results of a ShapExplainer for a single model forecast with convenient access to the results.

It extends the ComponentBasedExplainabilityResult and carries additional information specific to the SHAP explainers.

get_explanation(): SHAP values for a given component in multivariate TimeSeries format.
get_feature_values(): input feature values for a given component in single-timestamp multivariate TimeSeries format.
get_shap_explanation_object(): shap.Explanation object for a given component.

Examples

>>> from darts.datasets import AusBeerDataset
>>> from darts.explainability import ShapExplainer
>>> from darts.models import LinearRegressionModel
>>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dta
>>>
>>> # load a target series and create future covariates holding the calendar month values
>>> series = AusBeerDataset().load()
>>> fc = dta(series, attribute="month", add_length=12)
>>>
>>> # create and fit a model
>>> model = LinearRegressionModel(lags=2, lags_future_covariates=[-1, 0])
>>> model.fit(series, future_covariates=fc)
>>>
>>> # create an explainer; requires background series if the model was trained on multiple series
>>> explainer = ShapExplainer(model)
>>> # explain the background forecast (or foreground forecast if passed to `explain_single()`)
>>> result = explainer.explain_single()
>>> # get explanations for that forecast (and optional component for multivariate models)
>>> # the feature SHAP values for that forecast
>>> explanation = result.get_explanation()
>>> # the feature values used as model inputs for that forecast
>>> feature_values = result.get_feature_values()
>>> # the raw shap objects for further processing
>>> shap_object = result.get_shap_explanation_object()

Methods

`get_explanation`([component])	Returns the `TimeSeries` representing the explanation for a given component.
`get_feature_values`([component])	Returns the `TimeSeries` representing the feature values for a given component.
`get_shap_explanation_object`([component])	Returns the underlying `shap.Explanation` object for a given component.

get_explanation(component=None)[source]#

Returns the TimeSeries representing the explanation for a given component.

The components of the TimeSeries correspond to the input features used by the model to produce the forecasts. The time index contains the forecasted timestamps in the future. Therefore, the values of TimeSeries are the SHAP values of the features for the forecast at each forecasted timestamp.

Parameters:: component (str | None) – Optionally, the target series component for which to return the explanation. Must be supplied for multivariate forecasting models.
Return type:: TimeSeries

get_feature_values(component=None)[source]#

Returns the TimeSeries representing the feature values for a given component.

The components of the TimeSeries correspond to the input features used by the model to produce the forecasts. The time index contains only one timestamp, which is the first forecasted timestamp in the future. The values of the TimeSeries are the feature values used by the model to produce the forecast starting at that timestamp.

Parameters:: component (str | None) – The component for which to return the feature values. Must be supplied for multivariate forecasting models.
Return type:: TimeSeries

get_shap_explanation_object(component=None)[source]#

Returns the underlying shap.Explanation object for a given component.

Parameters:: component (str | None) – The component for which to return the shap.Explanation object. Must be supplied for multivariate forecasting models.
Return type:: Explanation

class darts.explainability.explainability_result.TFTExplainabilityResult(explanations)[source]#

Bases: ComponentBasedExplainabilityResult

Stores the explainability results of a TFTExplainer with convenient access to the results. It extends the ComponentBasedExplainabilityResult and carries information specific to the TFT explainer.

get_attention(): self attention over the encoder and decoder
get_encoder_importance(): encoder feature importances including past target, past covariates, and historic part of future covariates.
get_decoder_importance(): decoder feature importances including future part of future covariates.
get_static_covariates_importance(): static covariates importances.
get_feature_importances(): get all feature importances at once.

Examples

>>> from darts.datasets import AusBeerDataset
>>> from darts.explainability import TFTExplainer
>>> from darts.models import TFTModel
>>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dta
>>>
>>> # load a target series and create future covariates holding the calendar month values
>>> series = AusBeerDataset().load().astype("float32")
>>> fc = dta(series, attribute="month", add_length=12, dtype=series.dtype)
>>>
>>> # create and fit a model
>>> model = TFTModel(
>>>     input_chunk_length=12,
>>>     output_chunk_length=12,
>>>     use_reversible_instance_norm=True
>>> )
>>> model.fit(series, future_covariates=fc)
>>>
>>> # create an explainer
>>> explainer = TFTExplainer(model)
>>> # explain a single forecast:
>>> # - by default, if foreground is not provided, it is the forecast of the background
>>> # - otherwise, it is the forecast of the foreground
>>> result = explainer.explain()
>>> attention = result.get_attention()
>>> feature_importances = result.get_feature_importances()
>>> encoder_importance = result.get_encoder_importance()
>>> decoder_importance = result.get_decoder_importance()
>>> static_cov_importance = result.get_static_covariates_importance()

Methods

`get_attention`()	Returns the time-dependent attention on the encoder and decoder for each horizon in (1, output_chunk_length).
`get_decoder_importance`()	Returns the time-dependent decoder importances as a pd.DataFrames.
`get_encoder_importance`()	Returns the time-dependent encoder importances as a pd.DataFrames.
`get_explanation`([component])	Returns one or several explanations for a given component.
`get_feature_importances`()	Returns the feature importances for the encoder, decoder and static covariates as pd.DataFrames.
`get_static_covariates_importance`()	Returns the numeric and categorical static covariates importances as a pd.DataFrames.

get_attention()[source]#

Returns the time-dependent attention on the encoder and decoder for each horizon in (1, output_chunk_length). The time index ranges from the prediction series’ start time - input_chunk_length and ends at the prediction series’ end time. If multiple series were used when calling TFTExplainer.explain(), returns a list of TimeSeries.

Return type:: TimeSeries | list[TimeSeries]

get_decoder_importance()[source]#

Returns the time-dependent decoder importances as a pd.DataFrames. If multiple series were used in TFTExplainer.explain(), returns a list of pd.DataFrames.

Return type:: DataFrame | list[DataFrame]

get_encoder_importance()[source]#

Returns the time-dependent encoder importances as a pd.DataFrames. If multiple series were used in TFTExplainer.explain(), returns a list of pd.DataFrames.

Return type:: DataFrame | list[DataFrame]

get_explanation(component=None)#

Returns one or several explanations for a given component.

Parameters:: component (str | None) – Optionally, the target series component for which to return the explanation. Must be supplied for multivariate forecasting models.
Return type:: Any | list[Any]

get_feature_importances()[source]#

Returns the feature importances for the encoder, decoder and static covariates as pd.DataFrames. If multiple series were used in TFTExplainer.explain(), returns a list of pd.DataFrames per importance.

Return type:: dict[str, DataFrame | list[DataFrame]]

get_static_covariates_importance()[source]#

Returns the numeric and categorical static covariates importances as a pd.DataFrames. If multiple series were used in TFTExplainer.explain(), returns a list of pd.DataFrames.

Return type:: DataFrame | list[DataFrame]

Explainability Result#

This Page