BaseForecastingModel#

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

Bases: BaseModel, Predictor[TimeSeriesDataset, ForecastDataset]

Abstract base for forecasting models (single-forecaster and ensemble).

Provides the shared pipeline skeleton: preprocessing -> predict -> postprocessing, data preparation, scoring, and evaluation. Concrete subclasses must implement the abstract hooks fit, is_fitted, quantiles, and max_horizon. Subclasses following the single-input template method pattern should also override _predict; those with a different predict flow (e.g. ensemble) can override predict() directly.

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.

Parameters:

data (Any)

preprocessing: TransformPipeline[TimeSeriesDataset]#
postprocessing: TransformPipeline[ForecastDataset]#
target_column: str#
data_splitter: DataSplitter#
cutoff_history: timedelta#
evaluation_metrics: list[MetricProvider]#
tags: dict[str, str]#
abstract property quantiles: list[Quantile]#

Quantile levels this model produces forecasts for.

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

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

Train the forecasting model on the provided dataset.

Parameters:
Returns:

Result containing training details and metrics.

Return type:

ModelFitResult

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

Prepare input data for forecasting by applying preprocessing and filtering.

Transforms raw time series data through the preprocessing pipeline, restores the target column, and filters out incomplete historical data to ensure training quality.

Parameters:

  • data (TimeSeriesDataset) – Raw time series dataset to prepare for forecasting.

  • forecast_start (datetime | None) – Optional start time for forecasts. If provided and earlier than the cutoff time, overrides the cutoff for data filtering.

  • data

  • forecast_start

Returns:

Processed forecast input dataset ready for model prediction.

Return type:

ForecastInputDataset

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

Generate forecasts using the trained model.

Transforms input data through the preprocessing pipeline, generates predictions using the underlying forecaster(s), and applies postprocessing transformations.

Parameters:

  • data (TimeSeriesDataset) – Input time series data for generating forecasts.

  • forecast_start (datetime | None) – Starting time for forecasts. If None, uses data end time.

  • data

  • forecast_start

Returns:

Processed forecast dataset with predictions and uncertainty estimates.

Raises:

NotFittedError – If the model hasn’t been trained yet.

Return type:

ForecastDataset

score(data: TimeSeriesDataset) → SubsetMetric[source]#

Evaluate model performance on the provided dataset.

Generates predictions for the dataset and calculates evaluation metrics by comparing against ground truth values.

Parameters:

  • data (TimeSeriesDataset) – Time series dataset containing both features and target values for evaluation.

  • data

Returns:

Evaluation metrics computed at the maximum forecast horizon.

Return type:

SubsetMetric

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