Source code for energy_analysis.chile_fleet.reference

"""Fleet accounting for externally supplied frozen generation references."""

from __future__ import annotations

import shutil
import tempfile
from datetime import datetime
from pathlib import Path
from typing import Literal

import pandas as pd

from .config import utc_datetime
from .fleet import ComparisonConfig, compare_site, summarize_fleet
from .io import (
    SiteDataSource,
    fingerprint,
    load_sites,
    row_mapping,
    validate_output_location,
    write_fleet_csv,
    write_json,
)


[docs] def compare_references( hourly_path: Path, sites_path: Path, output_path: Path, *, start: datetime, end: datetime, reference: Literal[ "expected_mwh", "expected_final_mwh", "expected_heldout_mwh" ] = "expected_mwh", minimum_reference_coverage: float = 0.8, relative_tolerance: float = 0.2, data_kind: Literal["unspecified", "synthetic", "observational"] = "unspecified", ) -> dict[str, object]: """Use supplied expected values unchanged; never fit or fill a missing reference.""" start, end = utc_datetime(start), utc_datetime(end) if data_kind not in {"unspecified", "synthetic", "observational"}: raise ValueError("data_kind must be unspecified, synthetic or observational") if start >= end: raise ValueError("Start must precede the exclusive end") if output_path.exists(): raise FileExistsError(f"Refusing to overwrite comparison: {output_path}") validate_output_location(output_path, hourly_path) output_path.parent.mkdir(parents=True, exist_ok=True) registry = load_sites(sites_path) if registry.empty: raise ValueError("The site registry is empty") source = SiteDataSource(hourly_path) settings = ComparisonConfig(minimum_reference_coverage, relative_tolerance) temporary = Path(tempfile.mkdtemp(prefix=f".{output_path.name}-", dir=output_path.parent)) try: rows: list[dict[str, object]] = [] for site in row_mapping(registry): frame = source.site(str(site["site_id"])) if reference not in frame: raise ValueError(f"Input is missing requested frozen reference column: {reference}") frame = frame.loc[(frame.timestamp >= start) & (frame.timestamp < end)].copy() frame["expected_mwh"] = frame[reference] row = compare_site(frame, settings) row.update({key: site.get(key, "") for key in ("site_id", "name", "region")}) rows.append(row) fleet = pd.DataFrame(rows) fleet.to_parquet(temporary / "fleet.parquet", index=False, compression="zstd") write_fleet_csv(fleet, temporary / "fleet.csv") summary = summarize_fleet(fleet) write_json(temporary / "summary.json", summary) result: dict[str, object] = { "schema": "energy-data-insights-frozen-reference-comparison-v1", "complete": True, "data_kind": data_kind, "model_retrained": False, "expected_values_modified": False, "start_inclusive": start, "end_exclusive": end, "reference_column": reference, "minimum_reference_coverage": minimum_reference_coverage, "relative_tolerance": relative_tolerance, "inputs": {"hourly": fingerprint(hourly_path), "sites": fingerprint(sites_path)}, "summary": summary, "scope": ( "Supplied frozen predictions are used unchanged. This command performs energy " "accounting only; it does not recreate training support or operational states." ), } write_json(temporary / "manifest.json", result) temporary.rename(output_path) return result except BaseException: shutil.rmtree(temporary, ignore_errors=True) raise