ContributionsMixin#

class openstef_models.explainability.ContributionsMixin[source]#

Bases: ABC

Mixin for forecasters that can explain per-sample feature contributions.

Unlike ExplainableForecaster which provides aggregate feature importance, this mixin provides per-sample decomposition of predictions — i.e., how much each feature contributed to the prediction for each individual sample.

For tree-based models (XGBoost), this corresponds to SHAP TreeExplainer values. For linear models (GBLinear), this is the coefficient x feature value decomposition. For ensembles, this shows each base model’s contribution weight.

abstractmethod predict_contributions(data: ForecastInputDataset) → TimeSeriesDataset[source]#

Compute per-sample feature contributions for the given input data.

Returns a TimeSeriesDataset where columns are feature names (or model names for ensemble contributions) and rows correspond to the same time index as the input. Values represent the additive contribution of each feature to the prediction at that timestep.

Parameters:

data (ForecastInputDataset) – Preprocessed input data (same format as predict() takes).

Return type:

TimeSeriesDataset

Returns:

TimeSeriesDataset with feature contributions. Columns are features, rows are timesteps. A bias column may be included for the model intercept/base value.

plot_contributions(data: ForecastInputDataset, kind: Literal['heatmap', 'waterfall', 'bar'] = 'heatmap', **kwargs: Any) → Figure[source]#

Plot per-sample feature contributions.

Calls predict_contributions() and visualizes the result using the requested chart type.

Parameters:
  • data (ForecastInputDataset) – Preprocessed input data.

  • kind (Literal['heatmap', 'waterfall', 'bar']) – Chart type — "heatmap", "waterfall", or "bar".

  • **kwargs (Any) – Forwarded to the corresponding plotter method (e.g. top_n, timestep).

Return type:

Figure

Returns:

Plotly Figure.

Raises:

ValueError – If kind is not one of the supported chart types.