BacktestForecasterMixin#

class openstef_beam.backtesting.backtest_forecaster.BacktestForecasterMixin[source]

Bases: object

Mixin defining the interface for forecasting models in backtesting frameworks.

Provides the essential contract for models that can be used in backtesting pipelines. Implementations must handle training on historical data and generating predictions with proper timestamp and availability metadata.

Key responsibilities:

  • Train models on historical time series data with proper context windows

  • Generate probabilistic forecasts across specified quantiles

  • Handle missing data gracefully and return None when predictions aren’t possible

  • Provide consistent output formatting for downstream evaluation

Implementation requirements:

  • Must implement quantiles property to specify which quantiles are predicted

  • Must implement predict() method for core forecasting logic

  • Should implement fit() method for model training (optional for some models)

  • Output predictions must include quantile columns formatted as [quantile_PXX]

Example

Basic implementation for a simple forecasting model

>>> from openstef_beam.backtesting.backtest_forecaster import BacktestForecasterMixin
>>> from openstef_core.types import Quantile
>>> import pandas as pd
>>>
>>> class SimpleForecaster(BacktestForecasterMixin):
...     def __init__(self, config):
...         self.config = config
...         self._quantiles = [Quantile(0.1), Quantile(0.5), Quantile(0.9)]
...
...     @property
...     def quantiles(self):
...         return self._quantiles
...
...     def fit(self, data):
...         # Train model on historical data
...         self.model_params = self._extract_patterns(data)
...
...     def predict(self, data):
...         # Generate predictions for the forecast horizon
...         if not self._has_sufficient_data(data):
...             return None
...
...         predictions = self._generate_forecasts(data)
...         return self._format_output(predictions)
Integration with benchmarking:

Forecaster implementations are typically created by factory functions that customize the model for specific targets

>>> def create_forecaster(context, target):
...     config = BacktestForecasterConfig(
...         predict_context_length=timedelta(days=7),
...         training_context_length=timedelta(days=365),
...         # ... other config parameters
...     )
...     return SimpleForecaster(config)
>>>
>>> # Use in benchmark pipeline
>>> # benchmark = BenchmarkPipeline(...)
>>> # benchmark.run(forecaster_factory=create_forecaster)

Guarantees:

  • Returns None when prediction cannot be performed reliably

  • Provides properly formatted prediction output with timestamp metadata

  • Handles edge cases and missing data gracefully

  • Maintains consistent error handling patterns across implementations

config: BacktestForecasterConfig
abstract property quantiles: list[Quantile]

Return the list of quantiles that this forecaster predicts.

fit(data: RestrictedHorizonVersionedTimeSeries) → None[source]

Handles the training of the model.

Parameters:

  • data (RestrictedHorizonVersionedTimeSeries) – Time series data with context for training.

  • data

Return type:

None

abstractmethod predict(data: RestrictedHorizonVersionedTimeSeries) → TimeSeriesDataset | None[source]

Core prediction logic to be implemented by subclasses.

Parameters:

  • data (RestrictedHorizonVersionedTimeSeries) – Time series data with context for prediction.

  • data

Returns:

DataFrame with predictions or None if prediction cannot be performed.

  • The predictions should be formatted in quantile columns [quantile_PXX]

  • The index should be the timestamp of the prediction

Return type:

TimeSeriesDataset | None

predict_versioned(data: RestrictedHorizonVersionedTimeSeries) → TimeSeriesDataset | None[source]

Predicts a versioned time series with the model.

Guarantees:

  • Returns None if _handle_predict returns None

  • Adds ‘timestamp’ column from index and ‘available_at’ from horizon

  • Contains quantile columns formatted as [quantile_PXX]

Parameters:

  • data (RestrictedHorizonVersionedTimeSeries) – Time series data with context for prediction.

  • data

Returns:

VersionedTimeSeriesDataset with predictions.

Return type:

TimeSeriesDataset | None