Source code for energy_analysis.timestral_case

"""Reproducible 24-hour Timestral demonstration on an attributed EIA capture.

Input: hourly CISO system generation, not individual plant SCADA. Method:
joint solar/wind prediction using history and known calendar covariates only.
Analysis: one chronological holdout against persistence and daily persistence.
This is a small software demonstration, not a validated forecasting benchmark.
"""

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass
from pathlib import Path

import numpy as np
import pandas as pd

from energy_data_retrieval.sources.eia import parse_balance_csv
from energy_methods._arrays import FloatArray, utc_index
from energy_methods.timestral import TimestralConnector, TimestralForecast

HORIZON = 24
FUEL_TYPES = ("SUN", "WND")
SAMPLE_NAME = "generation_eia_ciso_2024.csv"
SNAPSHOT_NAME = "timestral_ciso_forecast.json"
PROVENANCE_NAME = "timestral_ciso_provenance.json"


[docs] @dataclass(frozen=True) class TimestralCase: """Audited observations and disjoint model context/verification arrays.""" profiles: pd.DataFrame context: FloatArray actual: FloatArray known_covariates: FloatArray source_sha256: str @property def context_sha256(self) -> str: """Stable little-endian float64 digest of the target context.""" return hashlib.sha256(self.context.astype("<f8").tobytes()).hexdigest() @property def covariates_sha256(self) -> str: """Digest of calendar inputs including the known forecast horizon.""" return hashlib.sha256(self.known_covariates.astype("<f8").tobytes()).hexdigest()
[docs] def load_timestral_case(data_directory: str | Path) -> TimestralCase: """Verify the existing EIA source checksum and enforce consecutive UTC hours.""" directory = Path(data_directory) raw = (directory / SAMPLE_NAME).read_bytes() digest = hashlib.sha256(raw).hexdigest() source = json.loads( (directory / f"{SAMPLE_NAME.removesuffix('.csv')}.provenance.json").read_text() ) if digest != source["sample_sha256"]: raise ValueError("EIA source checksum does not match provenance") frame = parse_balance_csv(raw.decode(), respondents=["CISO"], fuel_types=list(FUEL_TYPES)) profiles = frame.pivot(index="timestamp", columns="fueltype", values="value") profiles = profiles.loc[:, list(FUEL_TYPES)].sort_index() profiles.index = utc_index(pd.DatetimeIndex(profiles.index), regular_hourly=True) if len(profiles) != 168 or not np.isfinite(profiles.to_numpy()).all(): raise ValueError("This case requires 168 complete hours of solar and wind observations") values = profiles.to_numpy(dtype=np.float64).T # Daily UTC clock harmonics are known in advance; no future generation or # subsequently observed weather is used as a covariate. phase = 2 * np.pi * pd.DatetimeIndex(profiles.index).hour.to_numpy() / 24 known = np.stack([np.sin(phase), np.cos(phase)])[None, ...] return TimestralCase( profiles, values[None, :, :-HORIZON].copy(), values[:, -HORIZON:].copy(), known, digest )
[docs] def forecast_timestral_case( case: TimestralCase, connector: TimestralConnector ) -> TimestralForecast: """Run real model inference on history only; verification data never enter it.""" return connector.forecast(case.context, HORIZON, known_covariates=case.known_covariates)
[docs] def load_timestral_snapshot(data_directory: str | Path, case: TimestralCase) -> TimestralForecast: """Read saved real inference, checking the output and all model-input digests.""" directory = Path(data_directory) manifest = json.loads((directory / PROVENANCE_NAME).read_text()) raw = (directory / SNAPSHOT_NAME).read_bytes() expected = { "source_sha256": case.source_sha256, "context_sha256": case.context_sha256, "known_covariates_sha256": case.covariates_sha256, "forecast_sha256": hashlib.sha256(raw).hexdigest(), } if any(manifest.get(key) != digest for key, digest in expected.items()): raise ValueError( "Timestral snapshot/input checksums differ; explicitly regenerate the example" ) snapshot = json.loads(raw) result = TimestralForecast( np.asarray(snapshot["quantiles"]), tuple(snapshot["quantile_levels"]) ) if result.quantiles.shape[:3] != (1, len(FUEL_TYPES), HORIZON): raise ValueError("Timestral snapshot has an unexpected batch, target or horizon") return result
[docs] def evaluate_timestral_case(case: TimestralCase, forecast: TimestralForecast) -> pd.DataFrame: """MAE/RMSE/WAPE plus empirical 80% interval coverage, independently per fuel.""" if forecast.median.shape != (1, len(FUEL_TYPES), HORIZON): raise ValueError("Forecast does not match the case targets and horizon") predictions = { "Timestral median": forecast.median[0], "Previous day": case.context[0, :, -HORIZON:], "Last observation": np.repeat(case.context[0, :, -1:], HORIZON, axis=-1), } rows = [] for name, prediction in predictions.items(): for i, fuel in enumerate(FUEL_TYPES): # EIA reports signed net generation (including negative solar at # night). Evaluate the same complete holdout for every model; the # PV-specific energy_metrics helper intentionally excludes negatives # and would produce different, unfair subsets here. residual = prediction[i] - case.actual[i] denominator = float(np.abs(case.actual[i]).sum()) coverage = np.nan if name == "Timestral median": coverage = float( np.mean( (case.actual[i] >= forecast.quantile(0.1)[0, i]) & (case.actual[i] <= forecast.quantile(0.9)[0, i]) ) ) rows.append( { "model": name, "fuel": fuel, "hours": HORIZON, "mae_mwh": float(np.abs(residual).mean()), "rmse_mwh": float(np.sqrt(np.mean(residual**2))), "wape_pct": ( None if denominator == 0 else float(np.abs(residual).sum()) / denominator * 100 ), "p10_p90_coverage": coverage, } ) return pd.DataFrame(rows)