Source code for energy_data_retrieval.hydro_catalogue.aha_provenance

"""Expose historical AHA field bases without promoting model inputs to measurements."""

import copy
import json
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json

FIELDS = {
    "Status": (None, "Source_status", "historical inventory classification"),
    "Latitude": ("degree", "Source_location", "dataset station coordinate"),
    "Longitude": ("degree", "Source_location", "dataset station coordinate"),
    "Capacity": ("MW", "Source_capacity", "historical rated capacity; physical scope unresolved"),
    "Reservoir Size": (
        "million m3",
        "Source_reservoir_size",
        "reservoir volume; usable fraction unknown",
    ),
    "Mean Annual Discharge": (
        "m3/s",
        "Source_mean_annual_discharge",
        "multiannual river discharge; not turbine design flow",
    ),
    "Design Discharge": (
        "m3/s",
        "Source_design_discharge",
        "design discharge; not measured operating flow",
    ),
    "First Year": ("year", None, "earliest expected entry year; not verified commissioning"),
    "Availability": (
        None,
        "Source_availability",
        "availability profile selection; not operational status",
    ),
    "River Name": (None, "Source_river", "dataset river name"),
    "River Basin": (None, "Source_river_basin", "dataset basin name"),
}


[docs] def enrich_provenance(existing: dict[str, Any], *, now: str) -> dict[str, Any]: """Retain raw values, per-field upstream citations and explicit unverified bases.""" row = copy.deepcopy(existing) ext = json.loads(row["extensions_json"]) history = ext.get("aha_historical_inventory", []) if not history: raise ValueError("Requires accepted AHA identity evidence") observations = [] for obs in history: raw = obs["raw"] for field, (unit, source_column, basis) in FIELDS.items(): if raw.get(field) in (None, ""): continue observations.append( { "column": field, "value": raw[field], "unit": unit, "basis": basis, "source_id": obs["source_id"], "excel_row": obs["row"], "upstream_reference": raw.get(source_column) if source_column else None, "fallback_reference": raw.get("SingleSource"), "upstream_independently_verified": False, "uncertainty": ( "Source-specific uncertainty unknown; historical/model input, " "not current measured evidence" ), } ) key = "aha_field_provenance" if key in ext: if ext[key] != observations: raise ValueError("Changed AHA field evidence requires review") return row ext[key] = observations row["extensions_json"] = canonical_json(ext) fs, ev = json.loads(row["field_sources_json"]), json.loads(row["evidence_json"]) fs["extensions_json"] = sorted(set(fs["extensions_json"] + [o["source_id"] for o in history])) ev["extensions_json"] = { "locator": "AHA technical sheet; per-column Excel rows retained in aha_field_provenance", "confidence": "high", "original_value": row["extensions_json"], "normalization": ( "Explicit dataset units/bases and unverified upstream citations; " "no rating/status promotion" ), } row.update( field_sources_json=canonical_json(fs), evidence_json=canonical_json(ev), updated_at=now, last_verified_at=now, ) return row