Source code for energy_methods.country_mapping

"""Country grids, polygon masks, clipped plots and clipped cell exports."""

from __future__ import annotations

import json
from collections.abc import Mapping
from pathlib import Path
from typing import Literal

import numpy as np
import xarray as xr
from matplotlib.axes import Axes
from matplotlib.collections import QuadMesh
from matplotlib.colors import Colormap, Normalize
from matplotlib.patches import PathPatch
from matplotlib.path import Path as PlotPath
from shapely import box, intersection, intersects, intersects_xy
from shapely.geometry import MultiPolygon, Polygon, mapping
from shapely.geometry.polygon import orient

from energy_methods.country_boundaries import CountrySelection, polygons
from energy_methods.mapping import _edges, normalize_grid

REFERENCE_IDS = ("natural_earth_countries", "shapely_documentation", "pyproj_documentation")
type Bounds = tuple[float, float, float, float]


def _bounds(bounds: Bounds) -> Bounds:
    west, south, east, north = bounds
    if not np.isfinite(bounds).all() or not (
        -180 <= west < east <= 180 and -90 <= south < north <= 90
    ):
        raise ValueError("bounds must be (west, south, east, north) in EPSG:4326")
    return bounds


[docs] def country_grid( selection: CountrySelection, *, resolution: float = 0.5, bounds: Bounds | None = None, maximum_cells: int = 250_000, ) -> xr.Dataset: """Build a regular lon/lat grid and an intersecting-cell country mask. Resolution is degrees, not new source information. Cell edges align to -180/-90. The spacing must divide 180 degrees; e.g. 1, .5, .25 or .1. All country parts determine default bounds. Explicit bounds select an area of interest (useful for overseas territories/insets). At least two centres per axis support cell edges and export. Allocation is bounded in advance. """ if ( isinstance(resolution, bool) or not np.isfinite(resolution) or not 1e-6 <= resolution <= 30 or not np.isclose(180 / resolution, round(180 / resolution), rtol=0, atol=1e-7) ): raise ValueError("resolution must be 1e-6..30 degrees and divide 180") if type(maximum_cells) is not int or maximum_cells < 1: raise ValueError("maximum_cells must be a positive integer") west, south, east, north = _bounds(bounds or selection.geometry.bounds) axes = [] for low, high, origin in ((south, north, -90), (west, east, -180)): first = int(np.floor((low - origin) / resolution)) last = int(np.ceil((high - origin) / resolution)) total = round(-2 * origin / resolution) if last - first < 2: first = max(0, min(first, total - 2)) last = first + 2 axes.append((first, last, origin)) if np.prod([last - first for first, last, _ in axes]) > maximum_cells: raise ValueError("Country grid exceeds maximum_cells; reduce extent or use a coarser grid") lat, lon = [ origin + (np.arange(first, last) + 0.5) * resolution for first, last, origin in axes ] template = xr.DataArray( np.zeros((len(lat), len(lon))), dims=("lat", "lon"), coords={"lat": lat, "lon": lon} ) mask = country_mask(template, selection, mode="intersects", maximum_cells=maximum_cells) if not mask.any(): raise ValueError("Selected bounds/grid do not intersect the selected countries") result = mask.to_dataset(name="country_mask") result.attrs = { "country_codes": " ".join(selection.codes), "grid_degrees": resolution, "coordinate_reference_system": "EPSG:4326", "boundary_source": selection.source, } return result
[docs] def country_mask( data: xr.DataArray, selection: CountrySelection, *, mode: Literal["center", "intersects"] = "intersects", maximum_cells: int = 250_000, ) -> xr.DataArray: """Boolean mask on normalized lat/lon coordinates; no interpolation. 'center' includes centres on country boundaries, excludes interior holes. 'intersects' includes cells touching any polygon; this supports retrieval for partial coastal cells. It is not a fractional-area mask. Both modes keep islands. Antimeridian-split countries work on a conventional -180..180 grid; default extents can therefore span the world. Use separate views to zoom. """ source = normalize_grid(data) size = source.sizes["lat"] * source.sizes["lon"] if type(maximum_cells) is not int or not 0 < size <= maximum_cells: raise ValueError("Country mask exceeds maximum_cells or has an empty grid") if mode == "center": values = intersects_xy( selection.geometry, source.lon.values[None, :], source.lat.values[:, None] ) elif mode == "intersects": lat = _edges(source.lat.values.astype(float), 90) lon = _edges(source.lon.values.astype(float), 180) cells = box(lon[:-1][None, :], lat[:-1][:, None], lon[1:][None, :], lat[1:][:, None]) values = intersects(selection.geometry, cells) else: raise ValueError("Mask mode must be center or intersects") return xr.DataArray( values, dims=("lat", "lon"), coords={"lat": source.lat, "lon": source.lon}, attrs={"mask_mode": mode, "country_codes": " ".join(selection.codes)}, )
[docs] def clip_country_grid( data: xr.DataArray, selection: CountrySelection, *, nodata: float = np.nan, mode: Literal["center", "intersects"] = "intersects", crop: bool = True, ) -> xr.DataArray: """Mask outside countries and optionally trim outer empty rows/columns. Partial cells retain their original numerical value; the plotting/export functions clip their polygon footprint. Existing NaN/nodata values stay missing. For integer class maps pass nodata=0 to preserve integer dtype. Supports additional dimensions such as year/month; never resamples classes. """ source = normalize_grid(data) mask = country_mask(source, selection, mode=mode) result = source.where(mask, other=nodata) if crop: rows, cols = np.nonzero(mask.values) if not len(rows): raise ValueError("No selected country cells on this grid; check extent/resolution") slices = {} for axis, indices in (("lat", rows), ("lon", cols)): first, last = int(indices.min()), int(indices.max()) + 1 if last - first == 1 and source.sizes[axis] >= 2: first = max(0, min(first, source.sizes[axis] - 2)) last = first + 2 slices[axis] = slice(first, last) result = result.isel(slices) result.attrs.update(country_codes=" ".join(selection.codes), country_mask_mode=mode) return result
def _plot_path(geometry: Polygon | MultiPolygon) -> PlotPath: paths = [] for polygon in polygons(geometry): polygon = orient(polygon, sign=1.0) # CCW shells / CW holes for nonzero fill. for ring in (polygon.exterior, *polygon.interiors): vertices = np.asarray(ring.coords)[:, :2] codes = np.full(len(vertices), PlotPath.LINETO, dtype=np.uint8) codes[0], codes[-1] = PlotPath.MOVETO, PlotPath.CLOSEPOLY paths.append(PlotPath(vertices, codes)) return PlotPath.make_compound_path(*paths)
[docs] def plot_country_boundaries( selection: CountrySelection, *, ax: Axes, colors: Mapping[str, str] | None = None, facecolor: str = "#e6ecef", edgecolor: str = "#ffffff", linewidth: float = 0.4, zorder: float = 1, ) -> tuple[PathPatch, ...]: """Draw categorical country polygons without inventing a numeric grid. ``colors`` maps exact selected country codes to face colors; other countries receive ``facecolor``. Holes and disconnected islands are preserved. Unknown codes fail instead of silently missing a requested highlight. The caller controls the longitude/latitude view bounds, labels and interpretation of the colors; these polygons are administrative context, not service areas. Returns one Matplotlib patch per country for further styling or export. """ colors = colors or {} if unknown := set(colors) - set(selection.codes): raise ValueError(f"Unknown selected country codes: {', '.join(sorted(unknown))}") if not np.isfinite(linewidth) or linewidth < 0 or not np.isfinite(zorder): raise ValueError("Use a finite nonnegative linewidth and finite zorder") patches = [] for country in selection.countries: patch = PathPatch( _plot_path(country.geometry), facecolor=colors.get(country.code, facecolor), edgecolor=edgecolor, linewidth=linewidth, zorder=zorder, ) ax.add_patch(patch) patches.append(patch) return tuple(patches)
[docs] def plot_country_map( data: xr.DataArray, selection: CountrySelection, *, ax: Axes, bounds: Bounds | None = None, cmap: str | Colormap = "viridis", norm: Normalize | None = None, vmin: float | None = None, vmax: float | None = None, nodata: float | None = None, ) -> QuadMesh: """Draw unsmoothed values clipped to exact country contours and draw borders. Returns a QuadMesh for fig.colorbar. Geographic axes are longitude/latitude, not a metric/equal-area projection. Gray denotes missing data within the supplied boundaries; white/background is outside. Use explicit bounds for mainland/island views. Boundary detail does not change source resolution. """ source = normalize_grid(data).transpose("lat", "lon") lat, lon = ( _edges(source.lat.values.astype(float), 90), _edges(source.lon.values.astype(float), 180), ) values = np.asarray(source.values, dtype=float) values = np.ma.masked_invalid(values) if nodata is not None: values = np.ma.masked_equal(values, nodata) clip = PathPatch( _plot_path(selection.geometry), transform=ax.transData, facecolor="#d9dfe3", edgecolor="none", ) ax.add_patch(clip) mesh = ax.pcolormesh( lon, lat, values, cmap=cmap, norm=norm, vmin=vmin, vmax=vmax, shading="flat", rasterized=True, ) mesh.set_clip_path(clip) for country in selection.countries: ax.add_patch( PathPatch( _plot_path(country.geometry), transform=ax.transData, facecolor="none", edgecolor="#34444f", linewidth=0.65, ) ) west, south, east, north = _bounds(bounds or selection.geometry.bounds) ax.set(xlim=(west, east), ylim=(south, north), xlabel="Longitude (°)", ylabel="Latitude (°)") ax.set_aspect(1 / max(np.cos(np.deg2rad((south + north) / 2)), 0.1)) ax.grid(alpha=0.15, linewidth=0.5) return mesh
[docs] def write_country_geojson( data: xr.DataArray, selection: CountrySelection, path: Path, *, nodata: float | None = None, labels: dict[int, str] | None = None, maximum_features: int = 100_000, ) -> Path: """Export cell-country polygon intersections, retaining each cell's value. Empty/line-only intersections and missing values are omitted. Holes/islands remain in the output. Polygon clipping is planar lon/lat and adds no data resolution. Use geodesic/equal-area calculations for fractional-area totals. """ source = normalize_grid(data).transpose("lat", "lon") mask = country_mask(source, selection).values values = np.asarray(source.values, dtype=float) valid = mask & np.isfinite(values) if nodata is not None: valid &= values != nodata if ( type(maximum_features) is not int or not maximum_features > 0 or valid.sum() > maximum_features ): raise ValueError("Country GeoJSON exceeds maximum_features") lat, lon = ( _edges(source.lat.values.astype(float), 90), _edges(source.lon.values.astype(float), 180), ) features = [] for row, col in zip(*np.nonzero(valid), strict=True): geometry = intersection( box(lon[col], lat[row], lon[col + 1], lat[row + 1]), selection.geometry ) if geometry.is_empty or geometry.area == 0: continue if geometry.geom_type == "GeometryCollection": geometry = MultiPolygon( [ p for g in geometry.geoms if isinstance(g, (Polygon, MultiPolygon)) for p in polygons(g) ] ) 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": mapping(geometry)} ) path = Path(path) path.parent.mkdir(parents=True, exist_ok=True) path.write_text( json.dumps( { "type": "FeatureCollection", "features": features, "metadata": { "name": str(source.name), "units": source.attrs.get("units", ""), "country_codes": list(selection.codes), "boundary_source": selection.source, "coordinate_reference_system": "EPSG:4326", "clipping": "cell-country intersection", }, }, allow_nan=False, separators=(",", ":"), ) + "\n", encoding="utf-8", ) return path