Source code for energy_methods.ml21

"""Seven-feature, yield-weighted PV clustering following de las Heras et al.

Published ML21 map labels are available through the separate source connector.
This module fits new clusters; their numeric IDs are not the paper's zone IDs.
"""

from __future__ import annotations

from importlib.metadata import version

import numpy as np
from numpy.typing import ArrayLike
from sklearn.cluster import KMeans
from threadpoolctl import threadpool_limits

from energy_methods.climate_zones import ClimateClusterModel, ClimateProvenance, validate_training

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "triana_2026_ml_climates")
FEATURES = ("Tann", "Tmax", "Tmin", "GHIann", "GHImax", "GHImin", "UVann")
PUBLISHED_CODES = (
    "",
    "Tro1",
    "Tro2",
    "Tro3",
    "Tro4",
    "Des1",
    "Des2",
    "Des3",
    "Mou1",
    "Mou2",
    "Mou3",
    "Tem1",
    "Tem2",
    "Tem3",
    "Tem4",
    "Tem5",
    "Col1",
    "Col2",
    "Col3",
    "Col4",
    "Pol1",
    "Pol2",
)
_NAMES = {
    "Tro": "Tropical",
    "Des": "Desert",
    "Mou": "Mountainous",
    "Tem": "Temperate",
    "Col": "Cold",
    "Pol": "Polar",
}
PUBLISHED_LABELS = (
    "Unclassified",
    *(f"{_NAMES[code[:3]]}; published subtype {code[3:]}" for code in PUBLISHED_CODES[1:]),
)


[docs] def fit_ml21( values: ArrayLike, specific_yield: ArrayLike, *, provenance: ClimateProvenance, feature_convention: str, n_clusters: int = 21, random_seed: int = 42, n_init: int = 20, ) -> ClimateClusterModel: """Fit standardization, yield regression weights and k-means on training rows. ``values`` follows FEATURES. ``specific_yield`` is a corresponding training target (kWh/kWp/year). The feature convention must declare units and source aggregation; the paper's radiation statistics are retained natively by its workbook connector. It is unsafe to substitute physical annual totals into a model trained on a different radiation-statistic convention. Fit only training sites; reuse this frozen model on holdouts or new regions. This refits regression coefficients rather than copying rounded Table 4. """ x = validate_training(values, 7, n_clusters) y = np.asarray(specific_yield, dtype=float) if ( y.shape != (len(x),) or not np.isfinite(y).all() or np.any(y < 0) or np.std(y) == 0 or not feature_convention.strip() ): raise ValueError("Finite nonconstant nonnegative training yield and convention required") if np.any(x[:, 3:] < 0) or np.any(x[:, :3] <= -273.15): raise ValueError("Physical climate features required") if not 1 <= n_init <= 1000: raise ValueError("n_init must be between 1 and 1000") offset, scale = np.mean(x, axis=0), np.std(x, axis=0) z = (x - offset) / scale coefficients, _, rank, _ = np.linalg.lstsq(np.column_stack((np.ones(len(z)), z)), y, rcond=None) if rank != 8: raise ValueError("Yield-weight regression requires full-rank training features") weights = np.abs(coefficients[1:]) if weights.max() <= 0: raise ValueError("Yield regression has no nonzero climate weights") weights /= weights.max() # Global factor leaves Euclidean cluster assignments unchanged. with threadpool_limits(limits=1): km = KMeans( n_clusters=n_clusters, n_init=n_init, random_state=random_seed, algorithm="lloyd" ).fit(z * weights) # Stable order by the actual mean irradiation and temperature of each fitted cluster. raw = np.stack([x[km.labels_ == i].mean(axis=0) for i in range(n_clusters)]) order = np.lexsort((raw[:, 0], raw[:, 3])) labels = tuple( f"Mean air {row[0]:.1f} °C; irradiation statistic {row[3]:.3g}" for row in raw[order] ) return ClimateClusterModel( "ml21-refit", FEATURES, offset, scale, weights, km.cluster_centers_[order], x.min(axis=0), x.max(axis=0), ("", *(f"ML{i:02}" for i in range(1, n_clusters + 1))), ("Unclassified", *labels), provenance, REFERENCE_IDS, { "software": {name: version(name) for name in ("numpy", "scikit-learn")}, "random_seed": random_seed, "n_init": n_init, "training_rows": len(x), "feature_convention": feature_convention, "regression_coefficients": coefficients.tolist(), "target_units": "kWh/kWp/year", "published_map_reproduction": False, }, )