Source code for energy_data_retrieval.wind_catalogue.identity

"""Conservative EIA identity review signals, never automatic additions or merges."""

from __future__ import annotations

import difflib
import json
import math
import re
import unicodedata
from typing import Any

_STOP = frozenset(
    [
        "wind",
        "windfarm",
        "windpower",
        "farm",
        "farms",
        "energy",
        "project",
        "llc",
        "ltd",
        "power",
        "center",
        "facility",
        "inc",
        "lp",
        "corp",
        "renewable",
        "generation",
        "the",
        "company",
    ]
)


[docs] def distinctive_name(value: str) -> str: """Remove generic site/legal words, retaining phase numbers and directions.""" plain = unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode().lower() return " ".join(w for w in re.sub(r"[^a-z0-9 ]", " ", plain).split() if w not in _STOP)
def _point(lat: Any, lon: Any) -> tuple[float, float] | None: if lat is None or lon is None or isinstance(lat, bool) or isinstance(lon, bool): return None try: lat, lon = float(lat), float(lon) except (ValueError, TypeError): return None if not math.isfinite(lat) or not math.isfinite(lon) or abs(lat) > 90 or abs(lon) > 180: return None return lat, lon def _distance(a: tuple[float, float], b: tuple[float, float]) -> float: lat1, lon1, lat2, lon2 = map(math.radians, (*a, *b)) h = ( math.sin((lat2 - lat1) / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin((lon2 - lon1) / 2) ** 2 ) return 6371.0088 * 2 * math.asin(math.sqrt(min(1.0, h)))
[docs] def screen_eia_sites( candidates: list[dict[str, Any]], existing: list[dict[str, Any]] ) -> list[dict[str, Any]]: """Return registry, name, alias and 10-km point flags for manual review. Distinctive-name similarity >=0.8 is a triage threshold, not identity proof. Missing coordinates, phases and cohort neighbours remain visible. No record is accepted, merged or assigned a farm boundary by this function. """ codes = [c["plant_code"] for c in candidates] if len(set(codes)) != len(codes) or any(type(c) is not int or c <= 0 for c in codes): raise ValueError("Require unique positive EIA plant codes") projects = [ r for r in existing if r["entity_type"] == "projects" and r["country_code"] == "USA" ] result = [] for c in candidates: code, name = c["plant_code"], distinctive_name(c["name"]) p = _point(c["plant_context"]["Latitude"], c["plant_context"]["Longitude"]) ids, names, nearby, peers = [], [], [], [] for r in projects: external = json.loads(r.get("external_ids_json") or "{}") if ( str(external.get("eia_plant_code")) == str(code) or external.get("wri_gppd") == f"USA{code:07d}" ): ids.append(r["record_id"]) for alias in [r["name"], *r.get("aliases", [])]: other = distinctive_name(alias) ratio = difflib.SequenceMatcher(None, name, other).ratio() if name and other and ratio >= 0.8: names.append( { "record_id": r["record_id"], "matched_name": alias, "ratio": round(ratio, 4), } ) q = _point(r.get("latitude"), r.get("longitude")) if p and q and (distance := _distance(p, q)) <= 10: nearby.append({"record_id": r["record_id"], "distance_km": round(distance, 4)}) for peer in candidates: if peer["plant_code"] == code: continue other = distinctive_name(peer["name"]) q = _point(peer["plant_context"]["Latitude"], peer["plant_context"]["Longitude"]) similar = bool( name and other and difflib.SequenceMatcher(None, name, other).ratio() >= 0.8 ) near = bool(p and q and _distance(p, q) <= 10) if similar or near: peers.append( {"plant_code": peer["plant_code"], "similar_name": similar, "nearby": near} ) result.append( { "plant_code": code, "name": c["name"], "distinctive_name": name, "existing_registry_ids": sorted(ids), "name_matches": names, "nearby_projects": nearby, "cohort_peers": peers, "missing_coordinate": p is None, "phase_or_direction_flag": bool( re.search( r"\b([ivx]+|\d+|repower\w*|phase|hybrid|east|west|north|south)\b", c["name"], re.I, ) ), "empty_distinctive_name": not name, "decision": "manual_review_required", } ) return result