"""Complete-year processing and labelled maps for soiling and snow shading."""
from __future__ import annotations
import json
import numpy as np
import pandas as pd
import xarray as xr
from energy_methods.mapping import normalize_grid
from energy_methods.weather_risk import (
REFERENCE_IDS,
RISK_LABELS,
SNOW_EDGES,
SOILING_EDGES,
snow_loss_from_exposure,
snow_risk_classes,
soiling_rate_from_aod,
soiling_risk_classes,
)
def _time_grid(data: xr.DataArray, *, year: int, frequency: str, units: str) -> xr.DataArray:
if isinstance(year, bool) or not isinstance(year, int) or not 1678 <= year <= 2261:
raise ValueError("year must be an integer within the datetime64[ns] range")
if set(data.dims) != {"time", "lat", "lon"} or data.attrs.get("units") != units:
raise ValueError(f"Expected (time, lat, lon) with units={units!r}")
if data.attrs.get("time_zone") != "UTC":
raise ValueError("Time labels must declare time_zone='UTC'")
expected = pd.date_range(f"{year}-01-01", f"{year + 1}-01-01", freq=frequency, inclusive="left")
if not np.issubdtype(data.time.dtype, np.datetime64) or not np.array_equal(
data.time.values, expected.values
):
raise ValueError("A complete, ordered UTC calendar year is required; no gaps or duplicates")
if np.isinf(data.values).any() or np.any(data.values < 0):
raise ValueError("Inputs must be nonnegative and finite, or NaN")
return normalize_grid(data).transpose("time", "lat", "lon")
[docs]
def map_weather_risks(annual_inputs: xr.Dataset) -> xr.Dataset:
"""Map annual-mean soiling rates and annual snow losses over consecutive years.
Require aod550_mean [1] and snow_depth_sum [cm h] on (year, lat, lon).
Apply each nonlinear equation to EACH year's indicator, then average the
resulting rates/losses with skipna=False before assigning labels. This explicit
repository convention is not specified in full in the thesis's global maps.
Annual estimates are retained so aggregation is inspectable. The caller masks
oceans and supplies a validated baseline; this function never fills gaps.
"""
if "year" not in annual_inputs.coords or annual_inputs.year.dims != ("year",):
raise ValueError("A one-dimensional year coordinate is required")
years = np.asarray(annual_inputs.year.values)
if (
len(years) == 0
or not np.issubdtype(years.dtype, np.integer)
or np.any((years < 1678) | (years > 2261))
or np.any(np.diff(years) != 1)
):
raise ValueError("Years must be consecutive, unique, increasing integers")
fields = []
for name, units in (("aod550_mean", "1"), ("snow_depth_sum", "cm h")):
data = annual_inputs[name]
if set(data.dims) != {"year", "lat", "lon"} or data.attrs.get("units") != units:
raise ValueError(f"{name} requires (year, lat, lon) and units={units!r}")
fields.append(normalize_grid(data).transpose("year", "lat", "lon"))
aod, snow = xr.align(*fields, join="exact")
if aod.attrs.get("wavelength_nm") != 550:
raise ValueError("AOD must explicitly declare wavelength_nm=550")
if snow.attrs.get("snow_depth_kind") != "physical_ground":
raise ValueError("Snow must declare physical_ground depth, not water equivalent")
annual_soiling = aod.copy(data=soiling_rate_from_aod(aod.values))
annual_snow = snow.copy(data=snow_loss_from_exposure(snow.values))
annual_soiling.attrs = {"units": "% day-1", "equation": "thesis 3.2"}
annual_snow.attrs = {"units": "%", "equation": "thesis 3.3-3.4"}
soiling = annual_soiling.mean("year", skipna=False, keep_attrs=True)
snow_loss = annual_snow.mean("year", skipna=False, keep_attrs=True)
result = xr.Dataset(
{
"annual_soiling_rate": annual_soiling,
"annual_snow_loss": annual_snow,
"soiling_rate": soiling,
"snow_loss": snow_loss,
"soiling_risk": soiling.copy(data=soiling_risk_classes(soiling.values)),
"snow_risk": snow_loss.copy(data=snow_risk_classes(snow_loss.values)),
}
)
for name, edges, units in (
("soiling_risk", SOILING_EDGES, "% day-1"),
("snow_risk", SNOW_EDGES, "%"),
):
result[name].attrs = {
"units": "1",
"nodata": 0,
"upper_edges": list(edges),
"bin_units": units,
"edge_ownership": "upper-inclusive",
"class_labels": json.dumps(dict(enumerate(RISK_LABELS))),
}
result.attrs = {
**annual_inputs.attrs,
"baseline_start_year": int(years[0]),
"baseline_end_year": int(years[-1]),
"reference_ids": " ".join(REFERENCE_IDS),
"aggregation": (
"equations on each annual input, then mean annual rates/losses; no missing years"
),
"interpretation": (
"empirical screening indicators; not independently validated global losses "
"or event probabilities"
),
}
return result