Source code for energy_data_retrieval.hydro_catalogue.iha

"""Historical IHA India evidence; explicit reviewed crosswalks, never fuzzy merges."""

import copy
import csv
import io
import json
import math
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json


[docs] def parse_inventory(data: bytes) -> list[dict[str, Any]]: """Read Windows-1252 CSV with original row locators and distinct asset classes.""" reader = csv.DictReader(io.StringIO(data.decode("cp1252"))) required = { "ID", "Database Status", "Hydropower Station Name", "Lat (hydropower station 1)", "Long (hydropower station 1)", "HPP_elec_cap", "River", "Main_basin", } if not required.issubset(reader.fieldnames or []): raise ValueError("Missing IHA columns") result, seen = [], set() for index, row in enumerate(reader, 2): if None in row or any(value is None for value in row.values()): raise ValueError(f"Malformed IHA row {index}") identity = int(row["ID"]) if identity < 1 or identity in seen: raise ValueError("Invalid or duplicate IHA identity") seen.add(identity) result.append({"id": identity, "row": index, "raw": dict(row)}) return sorted(result, key=lambda r: r["id"])
[docs] def enrich( existing: dict[str, Any], item: dict[str, Any], *, source_id: str, reviewed_record_id: str, now: str, ) -> dict[str, Any]: """Apply an explicitly reviewed name/capacity/station-location crosswalk. Keep source status, capacity, ownership and hydraulic ratings as historical raw evidence. Do not infer current operation, reservoir energy or plant scope. """ raw = item["raw"] if existing["record_id"] != reviewed_record_id or existing["country_code"] != "IND": raise ValueError("Explicit identity review required") if raw["Database Status"].strip() != "Matched with hydro station": raise ValueError("Not a matched generating station") if existing["name"].strip().casefold() != raw["Hydropower Station Name"].strip().casefold(): raise ValueError("Name requires review") for field, column in [ ("latitude", "Lat (hydropower station 1)"), ("longitude", "Long (hydropower station 1)"), ]: value = float(raw[column]) if ( not math.isfinite(value) or existing.get(field) is None or abs(existing[field] - value) > 0.001 ): raise ValueError("Station coordinates require review") capacity = float(raw["HPP_elec_cap"]) if not math.isfinite(capacity) or capacity != existing.get("historical_capacity_mw"): raise ValueError("Historical capacity/scope requires review") row = copy.deepcopy(existing) ext = json.loads(row["extensions_json"]) obs = {**item, "source_id": source_id, "release_year": 2019} history = ext.setdefault("iha_india_historical_inventory", []) prior = [x for x in history if x["source_id"] == source_id] if prior: if prior != [obs]: raise ValueError("Immutable IHA observation changed") return row history.append(obs) ids = json.loads(row["external_ids_json"]) if ids.get("iha_india_2019", str(item["id"])) != str(item["id"]): raise ValueError("Conflicting IHA identity") ids["iha_india_2019"] = str(item["id"]) facts = {"extensions_json": canonical_json(ext), "external_ids_json": canonical_json(ids)} for field, column in [("river", "River"), ("basin", "Main_basin")]: value = raw[column].strip() if value and value.casefold() not in {"local", "local stream"}: if row.get(field) not in (None, "", value): raise ValueError("Conflicting hydraulic metadata") facts[field] = value fs, ev = json.loads(row["field_sources_json"]), json.loads(row["evidence_json"]) for field, value in facts.items(): row[field] = value fs[field] = sorted({*fs.get(field, []), source_id}) ev[field] = { "locator": f"IHA CSV row {item['row']}; ID={item['id']}", "confidence": "high", "original_value": value, "normalization": ( "Explicit name/capacity/station-coordinate review; historical 2019 evidence" ), } 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