Source code for energy_data_retrieval.hydro_catalogue.kengen

"""Read KenGen 2025 statistics with explicit rating and fiscal-year boundaries."""

import copy
import json
import math
import re
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json

SOURCE_ID = "kengen-annual-2025-20261106"
NAMES = (
    "Tana",
    "Masinga",
    "Kamburu",
    "Gitaru",
    "Kindaruma",
    "Kiambere",
    "Turkwel",
    "Sondu Miriu",
    "Sang\u2019oro",
    "Sagana",
    "Mesco",
    "Wanjii",
    "Gogo",
)


[docs] def parse_statistics(text: str) -> list[dict[str, Any]]: """Parse pdftotext -layout output of printed pp. 246 and 249, fail closed. Totals and Small Hydros are deliberately excluded: they overlap named plants. A dash is missing, never zero. Sold energy and effective capacity retain their own fields; neither is substituted for generation or installed capacity. """ result: dict[str, dict[str, Any]] = {} for heading, fields, unit, page in ( ( "Installed vs Effective Capacity (MW)", ("installed_capacity_mw", "effective_capacity_mw"), "MW", 246, ), ("Units Sent out (GWh)", ("annual_generation_gwh", "sold_energy_gwh"), "GWh", 249), ): sections = text.split(heading) matches = [part.split("\f")[0] for part in sections[1:] if "HYDRO" in part.split("\f")[0]] if len(matches) != 1: raise ValueError("Expected exactly one hydro statistics page per table") section = matches[0] if not re.search(r"2025\s+2024\s+2023\s+2022\s+2021", section): raise ValueError("Unexpected statistics year order") labels = r"Installed\s+Effective" if unit == "MW" else r"Generated\s+Sales" if not re.search(r"Power Plant\s+" + labels, section): raise ValueError("Unexpected paired statistics column order") found = set() for line in section.splitlines(): for name in NAMES: match = re.fullmatch(r"\s*" + re.escape(name) + r"\s{2,}(.+?)\s*", line) if not match: continue if name in found: raise ValueError("Duplicate plant statistics row") found.add(name) cells = match[1].split() if len(cells) != 10: raise ValueError("Expected five paired annual values") item = result.setdefault(name, {"source_name": name, "observations": []}) for i, token in enumerate(cells): value = None if token == "-" else float(token.replace(",", "")) if value is not None and (not math.isfinite(value) or value < 0): raise ValueError("Invalid nonnegative statistics value") year = 2025 - i // 2 item["observations"].append( { "field": fields[i % 2], "value": value, "unit": unit, "kind": "reported", "period": f"FY ended {year}-06-30", "boundary": ( "Named station; owner statistical table; not current operation" ), "source_id": SOURCE_ID, "locator": ( f"Printed p. {page}; {heading}; {name}; {year}; column {i % 2 + 1}" ), "original_value": token, "uncertainty": "Not quantified by publisher", } ) expected = set(NAMES[:9] if unit == "MW" else NAMES) if found != expected: raise ValueError("Missing or unexpected named hydro statistics rows") return list(result.values())
[docs] def enrich_reviewed(existing: dict[str, Any], entry: dict[str, Any], *, now: str) -> dict[str, Any]: """Apply an explicit owner/name/UUID crosswalk without overwriting ratings.""" if ( existing["record_id"] != entry["record_id"] or existing["country_code"] != "KEN" or existing["name"] != entry["canonical_name"] or existing.get("owner_names") != ["Kenya Electric Generating Company"] or entry.get("decision") != "accepted_owner_identity" ): raise ValueError("Explicit KenGen owner identity review required") item = entry["inventory"] expected_name = {"Sondu Miru": "Sondu Miriu"}.get(existing["name"], existing["name"]) if ( item["source_name"] != expected_name or item["source_name"] not in NAMES or len(item["observations"]) != 20 ): raise ValueError("Expected reviewed complete station statistics") row = copy.deepcopy(existing) ext = json.loads(row["extensions_json"]) evidence = { "source_id": SOURCE_ID, "source_name": item["source_name"], "identity_basis": entry["identity_basis"], } if "kengen_2025_identity" in ext: prior = [o for o in json.loads(row["observations_json"]) if o.get("source_id") == SOURCE_ID] if ext["kengen_2025_identity"] != evidence or prior != item["observations"]: raise ValueError("Changed owner statistics require conflict review") return row ext["kengen_2025_identity"] = evidence observations = json.loads(row["observations_json"]) observations.extend(item["observations"]) fs, ev = json.loads(row["field_sources_json"]), json.loads(row["evidence_json"]) for field, value in { "extensions_json": canonical_json(ext), "observations_json": canonical_json(observations), }.items(): row[field] = value fs[field] = sorted(set([*fs.get(field, []), SOURCE_ID])) ev[field] = { "locator": "KenGen 2025 printed pp. 246, 249; per-cell locators in observations_json", "confidence": "high", "original_value": value, "normalization": ( "Fiscal years; separate installed/effective MW and generated/sold GWh; " "historical values preserved" ), } row.update( field_sources_json=canonical_json(fs), evidence_json=canonical_json(ev), sources=sorted(set(row["sources"] + [SOURCE_ID])), updated_at=now, last_verified_at=now, ) return row