EnsembleForecastingModel#

class openstef_meta.models.ensemble_forecasting_model.EnsembleForecastingModel(**data: Any) → None[source]

Bases: BaseForecastingModel

Ensemble forecasting pipeline: common preprocessing -> N forecasters -> combiner.

Runs multiple base forecasters in parallel, aggregates their predictions via a ForecastCombiner, and applies shared postprocessing. Extends BaseForecastingModel as a sibling of ForecastingModel — not a subclass.

The preprocessing field (inherited from base) holds the common preprocessing shared across all base forecasters. model_specific_preprocessing adds per-forecaster transforms on top.

Invariants

  • fit() must be called before predict()

  • All forecaster horizons must be present in the input data

Important

The cutoff_history parameter is crucial when using lag-based features. Set it to exclude incomplete rows from training (e.g. timedelta(days=14) for a lag-14 transform).

Example

>>> from openstef_models.models.forecasting.constant_quantile_forecaster import (
...     ConstantQuantileForecaster,
... )
>>> from openstef_meta.models.forecast_combiners.learned_weights_combiner import WeightsCombiner
>>> from openstef_core.types import LeadTime
>>> from datetime import timedelta
>>>
>>> forecaster_1 = ConstantQuantileForecaster(
...     horizons=[LeadTime.from_string("PT36H")]
... )
>>> forecaster_2 = ConstantQuantileForecaster(
...     horizons=[LeadTime.from_string("PT36H")]
... )
>>> combiner = WeightsCombiner(
...     horizons=[LeadTime.from_string("PT36H")],
... )
>>> model = EnsembleForecastingModel(
...     forecasters={"constant_median": forecaster_1, "constant_median_2": forecaster_2},
...     combiner=combiner,
...     cutoff_history=timedelta(days=14),
... )
>>> model.fit(training_data)
>>> forecasts = model.predict(new_data)
Parameters:

data (Any)

forecasters: dict[str, Forecaster]
combiner: ForecastCombiner
model_specific_preprocessing: dict[str, TransformPipeline[TimeSeriesDataset]]
combiner_preprocessing: TransformPipeline[TimeSeriesDataset]
model_specific_postprocessing: TransformPipeline[ForecastDataset]
combiner_postprocessing: TransformPipeline[ForecastDataset]
property forecaster_configs: dict[str, Forecaster]

Configuration of each base forecaster, keyed by name.

property quantiles: list[Quantile]

Quantile levels this model produces forecasts for.

property max_horizon: LeadTime

Maximum lead-time (horizon) supported by this model.

property hyperparams: HyperParams

Hyperparameters for this model.

Override in subclasses to expose the relevant hyperparameters. Used by integrations (e.g. MLflow) to log tuning parameters without needing to know the model’s internal structure.

Returns:

HyperParams instance (defaults to empty base HyperParams).

property is_fitted: bool

Check if the predictor has been fitted.

property component_hyperparams: dict[str, HyperParams]

Per-component hyperparameters (e.g. per-forecaster in an ensemble).

Returns:

Empty dict by default; ensemble subclasses override.

get_explainable_components() → dict[str, ExplainableForecaster][source]

Return named components that support feature-importance plotting.

Keys are used as filename suffixes; an empty key means no suffix. Override in subclasses to expose forecasters and/or combiners.

Return type:

dict[str, ExplainableForecaster]

Returns:

Empty dict by default.

property forecaster_names: list[str]

Returns the names of the underlying forecasters.

fit(data: TimeSeriesDataset, data_val: TimeSeriesDataset | None = None, data_test: TimeSeriesDataset | None = None) → EnsembleModelFitResult[source]

Train all base forecasters and then the combiner.

Parameters:

  • data (TimeSeriesDataset) – Historical time series data with features and target values.

  • data_val (TimeSeriesDataset | None) – Optional validation data. If provided, splitters are ignored for validation.

  • data_test (TimeSeriesDataset | None) – Optional test data. If provided, splitters are ignored for test.

  • data

  • data_val

  • data_test

Returns:

FitResult containing training details and metrics.

Return type:

EnsembleModelFitResult

prepare_forecaster_input(data: TimeSeriesDataset, forecaster_name: str = '', forecast_start: datetime | None = None) → ForecastInputDataset[source]

Prepare input data for a specific base forecaster.

Applies common preprocessing, then model-specific preprocessing, restores the target column, and trims history via the shared base prepare_input.

Parameters:

  • data (TimeSeriesDataset) – Raw time series dataset.

  • forecaster_name (str) – Which forecaster to prepare data for.

  • forecast_start (datetime | None) – Optional forecast start time override.

  • data

  • forecaster_name

  • forecast_start

Returns:

Processed forecast input dataset ready for the named forecaster.

Return type:

ForecastInputDataset

predict(data: TimeSeriesDataset, forecast_start: datetime | None = None) → ForecastDataset[source]

Generate forecasts for the provided dataset.

Parameters:

  • data (TimeSeriesDataset) – Input time series dataset for prediction.

  • forecast_start (datetime | None) – Optional start time for forecasts.

  • data

  • forecast_start

Returns:

ForecastDataset containing the generated forecasts.

Raises:

NotFittedError – If the model has not been fitted yet.

Return type:

ForecastDataset

predict_contributions(data: TimeSeriesDataset, forecast_start: datetime | None = None) → TimeSeriesDataset[source]

Compute per-model contributions for the ensemble prediction.

Parameters:

  • data (TimeSeriesDataset) – Input time series dataset.

  • forecast_start (datetime | None) – Optional start time for forecasts.

  • data

  • forecast_start

Returns:

TimeSeriesDataset where each column is a base model’s contribution.

Raises:

NotFittedError – If the model has not been fitted yet.

Return type:

TimeSeriesDataset

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'protected_namespaces': (), 'ser_json_inf_nan': 'null'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self (BaseModel) – The BaseModel instance.

  • context (Any) – The context.

  • self

  • context

Return type:

None