ForecastingModel#

class openstef_models.models.ForecastingModel(**data: Any) → None[source]#

Bases: BaseForecastingModel

Single-forecaster pipeline: preprocessing -> forecaster -> postprocessing.

Orchestrates the full forecasting workflow by managing feature engineering, model training/prediction, and result postprocessing. Automatically handles the differences between single-horizon and multi-horizon forecasters while ensuring data consistency and validation throughout the pipeline.

Invariants

  • fit() must be called before predict()

  • Forecaster and preprocessing horizons must match during initialization

Important

The cutoff_history parameter is crucial when using lag-based features in preprocessing. For example, a lag-14 transformation creates NaN values for the first 14 days of data. Set cutoff_history to exclude these incomplete rows from training. You must configure this manually based on your preprocessing pipeline since lags cannot be automatically inferred from the transforms.

Example

Basic forecasting workflow:

>>> from openstef_models.models.forecasting.constant_median_forecaster import (
...     ConstantMedianForecaster,
... )
>>> from openstef_core.types import LeadTime
>>> from datetime import timedelta
>>>
>>> # Note: This is a conceptual example showing the API structure
>>> # Real usage requires implemented forecaster classes
>>> forecaster = ConstantMedianForecaster(
...     horizons=[LeadTime.from_string("PT36H")]
... )
>>> # Create and train model
>>> model = ForecastingModel(
...     forecaster=forecaster,
...     cutoff_history=timedelta(days=14),  # Match your maximum lag in preprocessing
... )
>>> model.fit(training_data)
>>>
>>> # Generate forecasts
>>> forecasts = model.predict(new_data)
Parameters:

data (Any)

forecaster: Forecaster#
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.

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.

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

Train the forecasting model on the provided dataset.

Fits the preprocessing pipeline and underlying forecaster. Handles both single-horizon and multi-horizon forecasters appropriately.

The data splitting follows this sequence: 1. Split test set from full data (using test_splitter) 2. Split validation from remaining train+val data (using val_splitter) 3. Train on the final training set

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.

Raises:

InsufficientlyCompleteError – If no training data remains after dropping rows with NaN targets.

Return type:

ModelFitResult

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

Compute per-sample feature contributions for predictions.

Not all models support contributions. The default raises NotImplementedError; subclasses backed by a ContributionsMixin forecaster override this to delegate.

Parameters:

  • data (TimeSeriesDataset) – Raw time series data (will be preprocessed internally).

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

  • data

  • forecast_start

Raises:

NotImplementedError – If the model does not support contributions.

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