"""Portable climate classifications and bounded, frozen cluster prediction.
Zero is always missing; positive IDs are local to a scheme/model version.
Distances and training-range flags are diagnostics, not probabilities.
"""
from __future__ import annotations
import json
from dataclasses import dataclass
from typing import Any
import numpy as np
from numpy.typing import ArrayLike, NDArray
REFERENCE_IDS = ("ascencio_vasquez_2021_thesis",)
[docs]
@dataclass(frozen=True)
class ClimateProvenance:
"""Caller-declared source support, retained in every result and fitted state."""
source: str
period: str
resolution: str
status: str = "application"
def __post_init__(self) -> None:
if any(not isinstance(v, str) or not v.strip() for v in vars(self).values()):
raise ValueError("Source, period, resolution and status must be nonempty strings")
[docs]
@dataclass(frozen=True)
class ClimateZones:
"""Class IDs, scientific codes, readable labels and source metadata."""
scheme: str
class_id: NDArray[np.int64]
codes: tuple[str, ...]
labels: tuple[str, ...]
provenance: ClimateProvenance
reference_ids: tuple[str, ...]
outside_training_range: NDArray[np.bool_] | None = None
def __post_init__(self) -> None:
ids = np.asarray(self.class_id)
if (
not np.issubdtype(ids.dtype, np.integer)
or len(self.codes) != len(self.labels)
or not self.codes
or self.codes[0] != ""
or len(set(self.codes)) != len(self.codes)
or np.any((ids < 0) | (ids >= len(self.codes)))
):
raise ValueError("IDs must index a unique code/label catalogue starting with missing")
copied = np.array(ids, dtype=np.int64, copy=True)
copied.setflags(write=False)
object.__setattr__(self, "class_id", copied)
if self.outside_training_range is not None:
outside = np.array(self.outside_training_range, dtype=bool, copy=True)
if outside.shape != ids.shape:
raise ValueError("Training-range flags must match class IDs")
outside.setflags(write=False)
object.__setattr__(self, "outside_training_range", outside)
@property
def zone(self) -> NDArray[np.str_]:
"""Scientific code for each cell; empty string means unclassified."""
return np.asarray(self.codes)[self.class_id]
[docs]
@dataclass(frozen=True)
class ClimateClusterModel:
"""Validated numerical state; no executable pickle or runtime estimator needed.
Input columns must follow ``features`` and the recorded training convention.
NaN prediction rows stay unclassified; infinity is rejected. Training bounds
diagnose extrapolation but do not measure cluster confidence.
"""
scheme: str
features: tuple[str, ...]
offset: NDArray[np.float64]
scale: NDArray[np.float64]
weights: NDArray[np.float64]
centers: NDArray[np.float64]
lower: NDArray[np.float64]
upper: NDArray[np.float64]
codes: tuple[str, ...]
labels: tuple[str, ...]
provenance: ClimateProvenance
reference_ids: tuple[str, ...]
settings: dict[str, Any]
def __post_init__(self) -> None:
d = len(self.features)
if not d or len(set(self.features)) != d:
raise ValueError("Feature names must be nonempty and unique")
for name in ("offset", "scale", "weights", "centers", "lower", "upper"):
value = np.array(getattr(self, name), dtype=float, copy=True)
if not np.isfinite(value).all():
raise ValueError("Model state must be finite")
expected = (len(self.codes) - 1, d) if name == "centers" else (d,)
if value.shape != expected:
raise ValueError(f"Invalid {name} shape")
value.setflags(write=False)
object.__setattr__(self, name, value)
if (
np.any(self.scale <= 0)
or np.any(self.weights < 0)
or not np.any(self.weights > 0)
or np.any(self.lower > self.upper)
or len(self.codes) < 2
):
raise ValueError("Invalid model scale, weights, bounds or cluster count")
ClimateZones(
self.scheme,
np.array([], dtype=np.int64),
self.codes,
self.labels,
self.provenance,
self.reference_ids,
)
object.__setattr__(self, "settings", json.loads(json.dumps(self.settings, allow_nan=False)))
[docs]
def predict(self, values: ArrayLike, *, batch_size: int = 8192) -> ClimateZones:
"""Predict without refitting; memory is bounded by batch size by cluster count."""
x = np.asarray(values, dtype=float)
if x.ndim < 1 or x.shape[-1] != len(self.features) or np.isinf(x).any():
raise ValueError("Expected finite/NaN feature rows in the recorded column order")
if isinstance(batch_size, bool) or not isinstance(batch_size, int) or batch_size < 1:
raise ValueError("batch_size must be a positive integer")
shape = x.shape[:-1]
flat = x.reshape(-1, len(self.features))
ids = np.zeros(len(flat), dtype=np.int64)
outside = np.zeros(len(flat), dtype=bool)
for start in range(0, len(flat), batch_size):
rows = flat[start : start + batch_size]
good = np.isfinite(rows).all(axis=1)
indices = np.flatnonzero(good) + start
if not len(indices):
continue
transformed = (rows[good] - self.offset) / self.scale * self.weights
distance = np.sum((transformed[:, None, :] - self.centers) ** 2, axis=2)
ids[indices] = np.argmin(distance, axis=1) + 1
outside[indices] = ((rows[good] < self.lower) | (rows[good] > self.upper)).any(axis=1)
return ClimateZones(
self.scheme,
ids.reshape(shape),
self.codes,
self.labels,
self.provenance,
self.reference_ids,
outside.reshape(shape),
)
[docs]
def to_dict(self) -> dict[str, Any]:
"""JSON-compatible state including scaling, units/conventions and attribution."""
result: dict[str, Any] = {"format_version": 1}
for name, value in vars(self).items():
result[name] = (
value.tolist()
if isinstance(value, np.ndarray)
else vars(value).copy()
if isinstance(value, ClimateProvenance)
else value
)
return json.loads(json.dumps(result, allow_nan=False))
[docs]
@classmethod
def from_dict(cls, state: dict[str, Any]) -> ClimateClusterModel:
"""Restore and validate a versioned numerical model."""
data = dict(state)
if data.pop("format_version", None) != 1:
raise ValueError("Unsupported climate model format")
data["provenance"] = ClimateProvenance(**data["provenance"])
for name in ("features", "codes", "labels", "reference_ids"):
data[name] = tuple(data[name])
return cls(**data)
[docs]
def validate_training(values: ArrayLike, features: int, clusters: int) -> NDArray[np.float64]:
"""Require explicit complete training rows and enough distinct locations."""
x = np.asarray(values, dtype=float)
if (
isinstance(clusters, bool)
or not isinstance(clusters, int)
or clusters < 2
or x.ndim != 2
or x.shape[1] != features
or not np.isfinite(x).all()
or len(np.unique(x, axis=0)) < clusters
):
raise ValueError("Training requires finite feature rows and at least K distinct rows")
if np.any(np.std(x, axis=0) == 0):
raise ValueError("Training features must have nonzero variance")
return x
[docs]
def class_target_rmse(
zones: ClimateZones, target: ArrayLike, sample_weight: ArrayLike | None = None
) -> float:
"""Weighted within-class target dispersion, not held-out prediction accuracy.
Compare on the same locations/period and also at equal class counts. Missing
target values and class zero are excluded; no area weighting is inferred.
"""
y = np.asarray(target, dtype=float)
w = np.ones(y.shape) if sample_weight is None else np.asarray(sample_weight, dtype=float)
if (
y.shape != zones.class_id.shape
or w.shape != y.shape
or np.isinf(y).any()
or not np.isfinite(w).all()
or np.any(w < 0)
):
raise ValueError("Targets and nonnegative finite weights must match the classifications")
good = (zones.class_id > 0) & np.isfinite(y) & (w > 0)
if not good.any():
raise ValueError("No qualified target observations")
total = 0.0
for class_id in np.unique(zones.class_id[good]):
mask = good & (zones.class_id == class_id)
mean = np.average(y[mask], weights=w[mask])
total += float(np.sum(w[mask] * (y[mask] - mean) ** 2))
return float(np.sqrt(total / w[good].sum()))