Source code for energy_data_retrieval.sources.open_meteo.snow

"""ERA5-Land physical ground snow depth via Open-Meteo's historical API."""

from __future__ import annotations

from dataclasses import dataclass
from datetime import date, timedelta

import numpy as np
import pandas as pd

from energy_data_retrieval.sources.open_meteo.client import Site
from energy_data_retrieval.transport import (
    HTTPClient,
    RequestRecord,
    RetrievalError,
    array_value,
    object_value,
)


[docs] @dataclass(frozen=True, slots=True) class SnowDepthChunk: site: Site frame: pd.DataFrame request: RequestRecord cell_latitude: float cell_longitude: float
[docs] @dataclass(slots=True) class OpenMeteoSnowClient: http: HTTPClient
[docs] def hourly_depth(self, site: Site, start: date, end: date) -> SnowDepthChunk: """Fetch 1-366 days of ERA5-Land instantaneous physical depth, m -> cm. Explicit era5_land model, nearest cell, no elevation downscaling and UTC. No endpoint averaging or extra day: the thesis sums hourly depth samples. ERA5-Land is an alternative to the ERA5 product used by the thesis; never describe this as unconverted native ERA5 snow water equivalent. Open-Meteo documents snow-depth overestimation. Public service terms apply. """ if start < date(1950, 1, 1) or not 1 <= (end - start).days + 1 <= 366: raise ValueError("Request 1-366 days from 1950 onward") response = self.http.get_json( "https://archive-api.open-meteo.com/v1/archive", { "latitude": str(site.latitude), "longitude": str(site.longitude), "start_date": start.isoformat(), "end_date": end.isoformat(), "hourly": "snow_depth", "models": "era5_land", "timezone": "UTC", "timeformat": "unixtime", "cell_selection": "nearest", "elevation": "nan", }, ) payload = object_value(response.value) hourly = object_value(payload.get("hourly")) units = object_value(payload.get("hourly_units")) if payload.get("utc_offset_seconds") != 0 or units != { "time": "unixtime", "snow_depth": "m", }: raise RetrievalError("Unexpected snow source units or clock") raw_time = array_value(hourly.get("time")) expected = pd.date_range( start, end + timedelta(days=1), freq="h", inclusive="left", tz="UTC" ) if not all(type(t) is int for t in raw_time) or not np.array_equal( np.asarray(raw_time), expected.as_unit("s").to_numpy(dtype="int64") ): raise RetrievalError("Snow response has missing, duplicate or unexpected hourly labels") raw = array_value(hourly.get("snow_depth")) if len(raw) != len(expected) or not all(v is None or type(v) in (int, float) for v in raw): raise RetrievalError("Snow value/time lengths differ or values are nonnumeric") depth = np.asarray(raw, dtype=float) if np.isinf(depth).any() or np.any(depth < 0): raise RetrievalError("Snow depth must be nonnegative, finite or missing") lat, lon = payload.get("latitude"), payload.get("longitude") if ( isinstance(lat, bool) or isinstance(lon, bool) or not isinstance(lat, (float, int)) or not isinstance(lon, (float, int)) or not np.isfinite(float(lat)) or not np.isfinite(float(lon)) or not -90 <= float(lat) <= 90 or not -180 <= float(lon) <= 180 ): raise RetrievalError("Missing or invalid selected snow grid coordinates") return SnowDepthChunk( site, pd.DataFrame({"timestamp": expected, "snow_depth_cm": depth * 100}), response.record, float(lat), float(lon), )