Source code for energy_methods.mapping

"""Reusable rectilinear geographic mapping, alignment, area and GeoJSON utilities."""

from __future__ import annotations

import json
from pathlib import Path
from typing import Literal

import numpy as np
import xarray as xr
from numpy.typing import ArrayLike, NDArray

REFERENCE_IDS = (
    "ascencio_vasquez_2021_thesis",
    "ascencio_vasquez_2019_kgpv",
    "xarray_documentation",
)


[docs] def normalize_grid(data: xr.DataArray) -> xr.DataArray: """Return sorted lat/lon coordinates, lon in [-180,180), rejecting duplicate seams.""" for axis, limit in (("lat", 90), ("lon", 360)): if axis not in data.coords or data[axis].dims != (axis,): raise ValueError("Mapping requires one-dimensional lat/lon coordinates") if not np.isfinite(data[axis]).all() or (np.abs(data[axis]) > limit).any(): raise ValueError(f"Invalid {axis} coordinates") result = data.assign_coords(lon=(data.lon + 180) % 360 - 180).sortby(["lat", "lon"]) if not result.indexes["lat"].is_unique or not result.indexes["lon"].is_unique: raise ValueError("Duplicate grid coordinates (including cyclic seam)") return result
[docs] def regrid( data: xr.DataArray, latitude: ArrayLike, longitude: ArrayLike, *, method: Literal["linear", "nearest"] = "linear", categorical: bool = False, ) -> xr.DataArray: """Bilinear/nearest interpolation of a rectilinear grid; no extrapolation. Categorical layers require nearest neighbour. Missing source cells are not filled. There is no cyclic seam interpolation; targets outside the source centre extent remain NaN. Regrid climate inputs before classification. """ if method not in {"linear", "nearest"} or (categorical and method != "nearest"): raise ValueError("Categorical layers require nearest; continuous use linear or nearest") source = normalize_grid(data) lat = np.asarray(latitude, dtype=float) lon = np.asarray(longitude, dtype=float) for values, limit in ((lat, 90), (lon, 180)): if ( values.ndim != 1 or not len(values) or not np.isfinite(values).all() or np.any(np.abs(values) > limit) or np.any(np.diff(values) <= 0) ): raise ValueError("Target coordinates must be finite, unique, increasing and geographic") if np.array_equal(lat, source.lat.values) and np.array_equal(lon, source.lon.values): return source.copy() if source.sizes["lat"] < 2 or source.sizes["lon"] < 2: raise ValueError("Interpolation requires at least two source centres per axis") result = source.interp(lat=lat, lon=lon, method=method) result.attrs.update(source.attrs, regridding=method) return result
def _edges(centres: NDArray[np.float64], limit: float) -> NDArray[np.float64]: if ( len(centres) < 2 or not np.isfinite(centres).all() or np.any(np.diff(centres) <= 0) or not np.allclose(np.diff(centres), np.diff(centres)[0]) ): raise ValueError("Cell export requires a regular grid with at least two centres per axis") edges = np.r_[ centres[0] - (centres[1] - centres[0]) / 2, (centres[1:] + centres[:-1]) / 2, centres[-1] + (centres[-1] - centres[-2]) / 2, ] return np.clip(edges, -limit, limit)
[docs] def cell_areas_km2(data: xr.DataArray) -> xr.DataArray: """Spherical cell areas from regular centre coordinates; Earth radius 6371.0088 km.""" source = normalize_grid(data) lat = _edges(np.asarray(source.lat.values, dtype=float), 90) lon = _edges(np.asarray(source.lon.values, dtype=float), 180) areas = 6371.0088**2 * np.diff(np.sin(np.deg2rad(lat)))[:, None] * np.deg2rad(np.diff(lon)) return xr.DataArray( areas, dims=("lat", "lon"), coords={"lat": source.lat, "lon": source.lon}, name="cell_area_km2", attrs={"units": "km2"}, )
[docs] def class_area_summary(data: xr.DataArray, *, nodata: int = 0) -> dict[int, float]: """Area by numeric class, excluding nodata/NaN; not a count of equally sized cells.""" source = normalize_grid(data) if set(source.dims) != {"lat", "lon"}: raise ValueError("Area summaries require a two-dimensional class map") areas = cell_areas_km2(source) values = source.values valid = values[np.isfinite(values) & (values != nodata)] if np.any(valid != np.floor(valid)): raise ValueError("Class IDs must be integers") return {int(value): float(areas.where(source == value, 0).sum()) for value in np.unique(valid)}
[docs] def write_geojson( data: xr.DataArray, path: Path, *, nodata: float | None = None, labels: dict[int, str] | None = None, maximum_features: int = 100_000, ) -> Path: """Export bounded regular grid cell polygons in EPSG:4326 for GIS/web maps. Missing cells are omitted; boundaries are cell midpoints clipped at the poles and antimeridian. Use NetCDF for large global layers; GeoJSON is for subsets. """ source = normalize_grid(data).transpose("lat", "lon") values = np.asarray(source.values, dtype=float) valid = np.isfinite(values) if nodata is not None: valid &= values != nodata if maximum_features < 1 or np.count_nonzero(valid) > maximum_features: raise ValueError("GeoJSON exceeds maximum_features; subset the grid or use NetCDF") lat = _edges(np.asarray(source.lat.values, dtype=float), 90) lon = _edges(np.asarray(source.lon.values, dtype=float), 180) features = [] for row, col in zip(*np.nonzero(valid), strict=True): west, east = float(lon[col]), float(lon[col + 1]) south, north = float(lat[row]), float(lat[row + 1]) value = float(values[row, col]) properties: dict[str, object] = {"value": value} if labels is not None: if not value.is_integer() or int(value) not in labels: raise ValueError("Every exported class must have a label") properties["label"] = labels[int(value)] features.append( { "type": "Feature", "properties": properties, "geometry": { "type": "Polygon", "coordinates": [ [[west, south], [east, south], [east, north], [west, north], [west, south]] ], }, } ) document = { "type": "FeatureCollection", "features": features, "metadata": { "name": str(source.name), "units": source.attrs.get("units", ""), "coordinate_reference_system": "EPSG:4326", }, } path.parent.mkdir(parents=True, exist_ok=True) path.write_text(json.dumps(document, allow_nan=False, separators=(",", ":")), encoding="utf-8") return path