Source code for energy_methods.climatology
"""Streaming, equal-year monthly climatologies with explicit coverage gates."""
from __future__ import annotations
import json
from collections.abc import Iterable
import numpy as np
import pandas as pd
import xarray as xr
REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "ascencio_vasquez_2019_kgpv")
[docs]
def monthly_climatology(
batches: Iterable[xr.DataArray],
*,
start_year: int,
end_year: int,
minimum_valid_years: int | None = None,
) -> xr.Dataset:
"""Consume one monthly archive at a time, retaining twelve sums/counts per cell.
Every calendar month in the requested period must be present exactly once.
By default each cell also needs every year for every month. Relaxing the cell
gate is explicit; the returned counts expose unequal sampling. Temperature
monthly means and precipitation monthly totals are averaged across years,
never summed across the baseline. No interpolation or missing-to-zero fill.
"""
if (
type(start_year) is not int
or type(end_year) is not int
or not 1 <= start_year <= end_year <= 9998
):
raise ValueError("Use ordered integer baseline years")
years = end_year - start_year + 1
required = years if minimum_valid_years is None else minimum_valid_years
if type(required) is not int or not 1 <= required <= years:
raise ValueError("minimum_valid_years must be within the baseline length")
expected = set(pd.period_range(f"{start_year}-01", f"{end_year}-12", freq="M"))
seen: set[pd.Period] = set()
total: xr.DataArray | None = None
count: xr.DataArray | None = None
attrs: dict[str, object] = {}
files: list[str] = []
name = ""
for batch in batches:
if "time" not in batch.dims or not batch.name:
raise ValueError("Each batch needs a named variable and a time dimension")
if batch.sizes["time"] == 0:
continue
periods = pd.DatetimeIndex(batch.time.values).to_period("M")
if periods.has_duplicates or periods.hasnans or not periods.is_monotonic_increasing:
raise ValueError("Duplicate or unordered calendar months")
keep = np.array([period in expected for period in periods])
batch = batch.isel(time=np.flatnonzero(keep))
selected = set(periods[keep])
if not selected:
continue
if seen & selected:
raise ValueError("Overlapping calendar months between input archives")
seen.update(selected)
if total is None:
name = str(batch.name)
attrs = dict(batch.attrs)
template = batch.isel(time=0, drop=True).astype(float)
total = xr.zeros_like(template).expand_dims(month=np.arange(1, 13)).copy()
count = xr.zeros_like(total, dtype=np.int32)
else:
if batch.name != name or batch.attrs.get("units") != attrs.get("units"):
raise ValueError("Batches must have the same variable and units")
for key in ("source", "product_version", "infilled"):
if batch.attrs.get(key) != attrs.get(key):
raise ValueError(f"Batches disagree on {key}")
if set(batch.dims) - {"time"} != set(total.dims) - {"month"}:
raise ValueError("Batches must have identical spatial dimensions")
xr.align(total.isel(month=0, drop=True), batch.isel(time=0, drop=True), join="exact")
assert count is not None
finite = batch.where(np.isfinite(batch))
sums = (
finite.groupby("time.month")
.sum("time", skipna=True)
.reindex(month=np.arange(1, 13), fill_value=0)
)
counts = (
finite.groupby("time.month").count("time").reindex(month=np.arange(1, 13), fill_value=0)
)
total = total + sums
count = count + counts
if "source_file" in batch.attrs:
files.append(str(batch.attrs["source_file"]))
if total is None or count is None or seen != expected:
raise ValueError(f"Incomplete baseline: {len(expected - seen)} calendar months missing")
mean = (total / count.where(count > 0)).where(count >= required).rename(name)
attrs.pop("source_file", None)
mean.attrs.update(
attrs,
baseline_start_year=start_year,
baseline_end_year=end_year,
minimum_valid_years=required,
aggregation="equal-year monthly climatology",
)
result = xr.Dataset({name: mean, "valid_years": count.astype(np.int32)})
result.attrs.update(
baseline_start_year=start_year,
baseline_end_year=end_year,
source_files=json.dumps(files),
minimum_valid_years=required,
)
result.valid_years.attrs.update(units="1", long_name="valid years per calendar month and cell")
return result