energy_analysis.forecast_benchmark#

Rolling-origin solar/wind forecasts with common pre-issue information.

Measured ONS generation is the target. Resource forecasts are deliberately simple: previous-day valid irradiance and last-valid wind-speed persistence. They are not archived NWP. Future measured weather and restriction flags never enter a model. ONS observations are revised historical data, not an as-issued SCADA vintage; this is a reproducible retrospective forecasting experiment.

class energy_analysis.forecast_benchmark.ForecastBenchmarkConfig(training_steps=672, horizon_steps=48, step_minutes=30, period_steps=48)[source]#

Bases: object

Fourteen-day rolling fit/context, daily issues and a 24-hour horizon.

Parameters:
  • training_steps (int)

  • horizon_steps (int)

  • step_minutes (int)

  • period_steps (int)

training_steps: int#
horizon_steps: int#
step_minutes: int#
period_steps: int#
class energy_analysis.forecast_benchmark.ForecastFold(technology, plant_id, issue_time, future_index, history_power, train_features, train_power, future_features, known_covariates, baseline, training_scale_mw)[source]#

Bases: object

A model-ready fold containing only history and constructed future features.

Parameters:
  • technology (str)

  • plant_id (str)

  • issue_time (Timestamp)

  • future_index (DatetimeIndex)

  • history_power (FloatArray)

  • train_features (FloatArray)

  • train_power (FloatArray)

  • future_features (FloatArray)

  • known_covariates (FloatArray)

  • baseline (FloatArray)

  • training_scale_mw (float)

technology: str#
plant_id: str#
issue_time: Timestamp#
future_index: DatetimeIndex#
history_power: FloatArray#
train_features: FloatArray#
train_power: FloatArray#
future_features: FloatArray#
known_covariates: FloatArray#
baseline: FloatArray#
training_scale_mw: float#
property key: str#
property input_sha256: str#

Bind cached model output to all numerical inputs and forecast labels.

energy_analysis.forecast_benchmark.load_benchmark_observations(data_directory, *, technologies=('solar', 'wind'))[source]#

Read checksum-verified native subsets and retain quality/restriction evidence.

Parameters:
  • data_directory (str | Path)

  • technologies (tuple[str, ...])

Return type:

dict[str, DataFrame]

energy_analysis.forecast_benchmark.prepare_forecast_fold(history, future_index, technology, *, config=ForecastBenchmarkConfig(training_steps=672, horizon_steps=48, step_minutes=30, period_steps=48), earlier_resource=None)[source]#

Construct one forecast using history only; no future observation argument exists.

Invalid historic resource readings stay missing. Solar forecasts use the most recent valid value at the same daily offset, searching older history if the previous day is flagged; wind uses its last valid reading. Unknown future resources are never filled from the held-out measurements.

Parameters:
  • history (DataFrame)

  • future_index (DatetimeIndex)

  • technology (str)

  • config (ForecastBenchmarkConfig)

  • earlier_resource (DataFrame | None)

Return type:

ForecastFold

energy_analysis.forecast_benchmark.forecast_folds(observations, *, config=ForecastBenchmarkConfig(training_steps=672, horizon_steps=48, step_minutes=30, period_steps=48), timestral_covariates='all', extend_resource_history=False)[source]#

Use each test day once, refitting on the preceding fixed-length window.

Parameters:
  • observations (dict[str, DataFrame])

  • config (ForecastBenchmarkConfig)

  • timestral_covariates (str)

  • extend_resource_history (bool)

Return type:

list[ForecastFold]

energy_analysis.forecast_benchmark.capture_timestral_forecasts(folds, connector)[source]#

Run actual model inference for every origin; no fabricated fallback outputs.

Parameters:
Return type:

DataFrame

energy_analysis.forecast_benchmark.load_timestral_forecasts(directory, folds, *, config=ForecastBenchmarkConfig(training_steps=672, horizon_steps=48, step_minutes=30, period_steps=48))[source]#

Reject stale predictions when data, model inputs or issue times change.

Parameters:
Return type:

DataFrame

energy_analysis.forecast_benchmark.predict_comparators(fold)[source]#

Fit the fixed tree/physical comparators using only a prepared history fold.

Parameters:

fold (ForecastFold)

Return type:

dict[str, FloatArray]

energy_analysis.forecast_benchmark.run_forecast_benchmark(data_directory, *, connector=None, config=ForecastBenchmarkConfig(training_steps=672, horizon_steps=48, step_minutes=30, period_steps=48), technologies=('solar', 'wind'), seasonal_baselines=False, timestral_covariates='all', extend_resource_history=False, retain_informative_fit=False)[source]#

Fit LightGBM/XGBoost/physical models locally and replay or run Timestral.

Four models plus the previous-day baseline are evaluated on identical future labels, with common nonnegative clipping. Restriction flags only annotate verification rows; they never filter fitting or forecasting observations.

Parameters:
  • data_directory (str | Path)

  • connector (TimestralConnector | None)

  • config (ForecastBenchmarkConfig)

  • technologies (tuple[str, ...])

  • seasonal_baselines (bool)

  • timestral_covariates (str)

  • extend_resource_history (bool)

  • retain_informative_fit (bool)

Return type:

DataFrame

energy_analysis.forecast_benchmark.benchmark_scores(predictions, *, by_lead=False, models=('Physical', 'LightGBM', 'XGBoost', 'Timestral', 'Previous day'))[source]#

Score every model on exactly the same keys; never drop failed predictions.

Parameters:
  • predictions (DataFrame)

  • by_lead (bool)

  • models (tuple[str, ...])

Return type:

DataFrame