Source code for energy_data_retrieval.gas_catalogue.ons

"""ONS nominal generating-unit inventory; gas-only, conservative boundary staging.

Attribution: Operador Nacional do Sistema Elétrico (ONS), CC-BY as stated
on the dataset page. No natural-gas subtype or turbine technology is inferred.
"""

from __future__ import annotations

import csv
import io
import json
import math
from datetime import date
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json

from .catalogue import stable_id
from .gppd import evidence_record


[docs] def parse_ons( text: str, *, source_id: str, now: str, observed: str, states: set[str] ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: """Stage exact equipment identities, holding mixed fuels and unknown boundaries. ``observed`` is the actual daily inventory revision, not retrieval time. All accepted units remain non-additive until plant/block reconciliation. ONS's dictionary defines blank deactivation as active. Commercial-operation release is retained separately and does not become a commissioning date. """ date.fromisoformat(observed) if observed > now[:10]: raise ValueError("Future inventory revision") reader = csv.DictReader(io.StringIO(text.lstrip("\ufeff")), delimiter=";") required = { "cod_equipamento", "ceg", "nom_usina", "nom_unidadegeradora", "nom_combustivel", "id_estado", "nom_estado", "nom_agenteproprietario", "nom_agenteoperador", "dat_entradaoperacao", "dat_desativacao", "val_potenciaefetiva", "nom_tipousina", } if not required <= set(reader.fieldnames or []): raise ValueError("Missing ONS headers") rows, ledger, seen = [], [], set() for line, raw in enumerate(reader, 2): r = {k: v.strip() for k, v in raw.items() if k is not None} if r["id_estado"] not in states: continue fuel = r["nom_combustivel"] decision = { "locator": f"CSV line {line}", "equipment_id": r["cod_equipamento"], "ceg": r["ceg"], "fuel": fuel, } if fuel != "GÁS": ledger.append( { **decision, "decision": "held" if "GÁS" in fuel or fuel == "RESÍDUO CICLO COMBINADO" else "excluded", "reason": "Mixed gas capability / CC component requires block reconciliation" if "GÁS" in fuel or fuel == "RESÍDUO CICLO COMBINADO" else "Outside gas-only partition", } ) continue ident = r["cod_equipamento"] if not ident or ident in seen: raise ValueError("Missing/duplicate ONS equipment identity") seen.add(ident) if not r["ceg"] or not r["nom_usina"] or r["nom_tipousina"] != "TÉRMICA": raise ValueError("Missing plant identity or nonthermal gas row") mw = float(r["val_potenciaefetiva"]) if not math.isfinite(mw) or mw < 0: raise ValueError("Invalid nominal MW") for key in ("dat_entradaoperacao", "dat_desativacao"): if r[key]: date.fromisoformat(r[key]) retired = bool(r["dat_desativacao"] and r["dat_desativacao"] <= observed) operating = bool( not retired and r["dat_entradaoperacao"] and r["dat_entradaoperacao"] <= observed ) locator = f"CSV line {line}; cod_equipamento={ident}; ceg={r['ceg']}" values: dict[str, Any] = { "record_id": stable_id("projects", "ONS-equipment", ident), "entity_type": "projects", "record_scope": "unit", "name": r["nom_usina"] + " — " + ident, "aliases": [r["nom_unidadegeradora"]], "country_code": "BRA", "external_ids_json": canonical_json({"ons_equipment": ident}), "aggregation_role": "unresolved", "overlap_group": "ANEEL-CEG:" + r["ceg"], "capacity_scope": "ONS individual generating unit; " "parent/CC block and WRI plant crosswalk unresolved; not additive", "status": "decommissioned" if retired else "operational" if operating else "unknown", "status_as_of": observed, "status_date_basis": "ONS daily inventory revision; " "dictionary defines blank deactivation as active; commercial release required", "technology": "unknown", "fuel_type": "gas_unspecified", "owner_names": [r["nom_agenteproprietario"]] if r["nom_agenteproprietario"] else None, "operator_names": [r["nom_agenteoperador"]] if r["nom_agenteoperador"] else None, "extensions_json": canonical_json( { "aneel_ceg": r["ceg"], "state_code": r["id_estado"], "state_name": r["nom_estado"], "commercial_operation_release": r["dat_entradaoperacao"] or None, "deactivation_date": r["dat_desativacao"] or None, } ), "observations_json": canonical_json( [ { "field": "nominal_electrical_capacity", "value": mw, "unit": "MW", "kind": "reported", "period": observed, "boundary": ident, "source_id": source_id, "locator": locator + "; val_potenciaefetiva", "electrical_basis": "unspecified", } ] ), "notes": "ONS nominal electrical MW is not a gas-only allocation or net rating. " "No technology, gas subtype, coordinates or CHP inferred. " "Commercial release is not commissioning.", } if operating: values.update( installed_capacity_mw=mw, installed_capacity_basis="unspecified", installed_capacity_as_of=observed, ) row = evidence_record(values, source_id=source_id, now=now, locator=locator) evidence = json.loads(row["evidence_json"]) columns = { "name": ["nom_usina", "cod_equipamento"], "aliases": ["nom_unidadegeradora"], "owner_names": ["nom_agenteproprietario"], "operator_names": ["nom_agenteoperador"], "installed_capacity_mw": ["val_potenciaefetiva"], "observations_json": ["val_potenciaefetiva"], "status": ["dat_entradaoperacao", "dat_desativacao"], "fuel_type": ["nom_combustivel"], "extensions_json": [ "ceg", "id_estado", "nom_estado", "dat_entradaoperacao", "dat_desativacao", ], } for field, item in evidence.items(): item["original_columns"] = { k: r[k] for k in columns.get(field, ["cod_equipamento", "ceg"]) } item["revision"] = observed row["evidence_json"] = canonical_json(evidence) rows.append(row) ledger.append( { **decision, "decision": "accepted", "record_id": row["record_id"], "reason": "Gas-only unit identity; unresolved aggregation explicitly excluded", } ) return rows, ledger