"""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