ContributionsMixin

class openstef_models.explainability.ContributionsMixin

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

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).

• data

Returns:

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

Return type:

TimeSeriesDataset

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

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).

• data

• kind

• kwargs (Any)

Returns:

Plotly Figure.

Raises:

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

Return type:

Figure