hot-open 0.2.0__py3-none-any.whl

hot_open/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("hot_open")

hot_open/circular_math.py

@@ -0,0 +1,180 @@
+"""Circular math functions missing from numpy/scipy."""
+
+import logging
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+from scipy.stats import circmean
+
+logger = logging.getLogger(__name__)
+
+
+def circdiff_degrees(
+    angle1: float | npt.NDArray | list | pd.Series, angle2: float | npt.NDArray | list | pd.Series
+) -> float | npt.NDArray | pd.Series:
+    """Calculate the circular difference between two angles.
+
+    :param angle1: First angle in degrees.
+    :param angle2: Second angle in degrees.
+    :return: Circular difference between the two angles in degrees
+    """
+    # Convert list to numpy array
+    if isinstance(angle1, list):
+        angle1 = np.array(angle1)
+    if isinstance(angle2, list):
+        angle2 = np.array(angle2)
+
+    return np.mod(angle1 - angle2 + 180, 360) - 180
+
+
+def circ_mean_resample_degrees(df: pd.DataFrame, *, resample_timedelta: pd.Timedelta) -> pd.DataFrame:
+    """Apply resample and ciruclar mean to a DataFrame efficiently.
+
+    Args:
+    ----
+        df: DataFrame where each column contains circular data in degrees from 0 inclusive to 360 exclusive.
+        resample_timedelta: Timebase to resample the data to.
+
+    Returns:
+    -------
+        Resampled DataFrame with circular mean of each column.
+
+    """
+    if not isinstance(df.index, pd.DatetimeIndex):
+        msg = "DataFrame must have a DatetimeIndex."
+        raise TypeError(msg)
+
+    for col in df.columns:
+        if (data_range := df[col].max() - df[col].min()) > 360:  # noqa:PLR2004
+            msg = f"Data in circular column {col} has a range larger than 360: {data_range}."
+            logger.warning(msg)
+        elif (df[col].min() < 0) or (df[col].max() > 360):  # noqa:PLR2004
+            msg = (
+                f"Data in circular column {col} has values outside 0 to 360: "
+                f"min = {df[col].min()}, max = {df[col].max()}."
+            )
+            logger.warning(msg)
+
+    rad_df = np.deg2rad(df)
+    sin_df = pd.DataFrame(np.sin(rad_df), index=df.index, columns=df.columns)
+    cos_df = pd.DataFrame(np.cos(rad_df), index=df.index, columns=df.columns)
+    sin_df_resampled = sin_df.resample(resample_timedelta).mean()
+    cos_df_resampled = cos_df.resample(resample_timedelta).mean()
+    result = (np.rad2deg(np.arctan2(sin_df_resampled, cos_df_resampled)) + 360) % 360
+    return pd.DataFrame(result, index=sin_df_resampled.index, columns=df.columns)
+
+
+def circ_std_resample_degrees(df: pd.DataFrame, *, resample_timedelta: pd.Timedelta) -> pd.DataFrame:
+    """Apply resample and circular standard deviation to a DataFrame efficiently.
+
+    Uses the mean resultant length R of the unit vectors and sqrt(-2 ln R), with R clipped at 1
+    so floating-point overshoot on a tight window gives 0 rather than NaN.
+
+    Args:
+    ----
+        df: DataFrame where each column contains circular data in degrees from 0 inclusive to 360 exclusive.
+        resample_timedelta: Timebase to resample the data to.
+
+    Returns:
+    -------
+        Resampled DataFrame with the circular standard deviation of each column, in degrees.
+
+    """
+    if not isinstance(df.index, pd.DatetimeIndex):
+        msg = "DataFrame must have a DatetimeIndex."
+        raise TypeError(msg)
+
+    rad_df = np.deg2rad(df)
+    sin_resampled = pd.DataFrame(np.sin(rad_df), index=df.index, columns=df.columns).resample(resample_timedelta).mean()
+    cos_resampled = pd.DataFrame(np.cos(rad_df), index=df.index, columns=df.columns).resample(resample_timedelta).mean()
+    resultant_length = np.sqrt(sin_resampled**2 + cos_resampled**2).clip(upper=1.0)
+    result = np.rad2deg(np.sqrt(-2 * np.log(resultant_length)))
+    return pd.DataFrame(result, index=sin_resampled.index, columns=df.columns)
+
+
+def circ_mean_dataframe_columns(df: pd.DataFrame) -> pd.Series:
+    """Apply ciruclar mean to DataFrame columns efficiently.
+
+    Args:
+    ----
+        df: DataFrame where each column contains circular data in degrees from 0 inclusive to 360 exclusive.
+        resample_timedelta: Timebase to resample the data to.
+
+    Returns:
+    -------
+        Resampled DataFrame with circular mean of each column.
+
+    """
+    # warn if data outside 0 to 360
+    if any(df.min() < 0) or any(df.max() >= 360):  # noqa:PLR2004
+        msg = "Data is expected to be between 0 and 360 degrees."
+        logger.warning(msg)
+
+    # check that each column has data where max-min is no more than
+    for col in df.columns:
+        if (data_range := df[col].max() - df[col].min()) > 360:  # noqa:PLR2004
+            msg = f"Data in column {col} has a range larger than 360 degrees: {data_range}."
+            raise ValueError(msg)
+
+    rad_df = np.deg2rad(df)
+    sin_df = np.sin(rad_df)
+    cos_df = np.cos(rad_df)
+    mean_sin_df = sin_df.mean(axis=1)
+    mean_cos_df = cos_df.mean(axis=1)
+    return (np.rad2deg(np.arctan2(mean_sin_df, mean_cos_df)) + 360) % 360
+
+
+def circmedian_degrees(angles: list[float] | npt.NDArray | pd.Series) -> float:
+    """Calculate the circular median of angles in degrees.
+
+    The circular median is defined as the angle in provided angles that minimizes the sum of circular
+    distances to all other provided angles. For a set of angles, this is computed
+    by converting to the unit circle, finding the angle that minimizes the great circle
+    distances, and converting back to degrees.
+
+    If two angles are tied their circular mean is returned.
+
+    Args:
+    ----
+        angles: Array-like object containing angles in degrees
+
+    Returns:
+    -------
+        float: Circular median in degrees, normalized to [0, 360)
+
+    """
+    # Convert to numpy array and handle empty input
+    angles_arr = np.asarray(angles)
+    if len(angles_arr) == 0:
+        msg = "Input array must not be empty"
+        raise ValueError(msg)
+
+    # Remove NaN values
+    valid_angles = angles_arr[~np.isnan(angles_arr)]
+
+    if len(valid_angles) == 0:
+        return np.nan
+
+    # Find the angle that minimizes the sum of absolute circular differences
+    min_sum_diff = float("inf")
+    median_angle = np.nan
+    candidates_which_are_tied = []
+
+    for candidate in valid_angles:
+        # Calculate absolute circular differences to all other angles
+        diffs = np.abs(circdiff_degrees(valid_angles, candidate))
+        sum_diff = np.sum(diffs)
+
+        if sum_diff < min_sum_diff:
+            min_sum_diff = sum_diff
+            median_angle = candidate
+            candidates_which_are_tied = [candidate]
+        elif sum_diff == min_sum_diff:
+            candidates_which_are_tied.append(candidate)
+
+    return float(
+        (median_angle + 360) % 360
+        if len(candidates_which_are_tied) == 1
+        else circmean(candidates_which_are_tied, low=0, high=360)
+    )

hot_open/era5_helpers.py

@@ -0,0 +1,142 @@
+"""ERA5 reanalysis data fetching via Open-Meteo API."""
+
+import hashlib
+import json
+import logging
+from pathlib import Path
+
+import openmeteo_requests
+import pandas as pd
+import requests_cache
+from retry_requests import retry
+from wind_up.reanalysis_data import ReanalysisDataset
+
+from .parquet_io import write_parquet_atomic
+from .settings import get_cache_dir
+
+logger = logging.getLogger(__name__)
+
+HOT_LAT: float = 57.50
+HOT_LON: float = -3.25
+HOT_ERA5_START: str = "2000-01-01"
+HOT_ERA5_END: str = "2026-05-01"
+ERA5_DEFAULT_FIELDS: list[str] = [
+    "temperature_2m",
+    "relative_humidity_2m",
+    "dew_point_2m",
+    "apparent_temperature",
+    "pressure_msl",
+    "surface_pressure",
+    "precipitation",
+    "rain",
+    "snowfall",
+    "cloud_cover",
+    "shortwave_radiation",
+    "direct_radiation",
+    "diffuse_radiation",
+    "wind_speed_10m",
+    "wind_speed_100m",
+    "wind_direction_10m",
+    "wind_direction_100m",
+    "wind_gusts_10m",
+    "weather_code",
+]
+HOT_ERA5_FIELDS: list[str] = ERA5_DEFAULT_FIELDS
+
+_era5_cache_dir = get_cache_dir() / "era5_data"
+_era5_cache_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _build_era5_df(response: object, fields: list[str]) -> pd.DataFrame:
+    """Build a tidy hourly DataFrame from a single Open-Meteo response object."""
+    hourly_data = response.Hourly()  # type: ignore[attr-defined]  # openmeteo_requests has no type stubs
+    return pd.DataFrame(
+        {
+            "timestamp": pd.date_range(
+                start=pd.to_datetime(hourly_data.Time(), unit="s", utc=True),
+                end=pd.to_datetime(hourly_data.TimeEnd(), unit="s", utc=True),
+                freq=pd.Timedelta(seconds=hourly_data.Interval()),
+                inclusive="left",
+            )
+        }
+        | {field: hourly_data.Variables(i).ValuesAsNumpy() for i, field in enumerate(fields)}
+    ).set_index("timestamp")
+
+
+def _era5_cache_path(*, lat: float, lon: float, start_date: str, end_date: str, fields: list[str]) -> Path:
+    """Build a deterministic parquet cache path from the request args."""
+    args_blob = json.dumps(
+        {"lat": lat, "lon": lon, "start_date": start_date, "end_date": end_date, "fields": list(fields)},
+        sort_keys=True,
+    )
+    args_hash = hashlib.sha256(args_blob.encode("utf-8")).hexdigest()[:16]
+    return _era5_cache_dir / f"ERA5_{lat:.2f}_{lon:.2f}_{start_date}_{end_date}_{args_hash}.parquet"
+
+
+def get_era5_hourly_df(
+    *,
+    lat: float,
+    lon: float,
+    start_date: str = "2000-01-01",
+    end_date: str | None = None,
+    fields: list[str] = ERA5_DEFAULT_FIELDS,
+) -> pd.DataFrame:
+    """Fetch hourly ERA5 data from Open-Meteo for any location and return as a DataFrame.
+
+    ``end_date`` defaults to today (UTC) when ``None``. Each unique combination of arguments
+    is cached to its own parquet file keyed by a hash of the arguments. Delete the cache file
+    to force a refetch.
+    """
+    if end_date is None:
+        end_date = pd.Timestamp.now(tz="UTC").normalize().strftime("%Y-%m-%d")
+    cache_path = _era5_cache_path(lat=lat, lon=lon, start_date=start_date, end_date=end_date, fields=fields)
+    if cache_path.exists():
+        logger.info("Reading: %s", cache_path)
+        return pd.read_parquet(cache_path)
+
+    openmeteo = openmeteo_requests.Client(
+        session=retry(
+            requests_cache.CachedSession(
+                str(get_cache_dir() / "openmeteo_requests_cache"),
+                expire_after=3600,
+            ),
+            retries=5,
+            backoff_factor=0.2,
+        )
+    )
+    responses = openmeteo.weather_api(
+        url="https://archive-api.open-meteo.com/v1/archive",
+        params={
+            "latitude": lat,
+            "longitude": lon,
+            "start_date": start_date,
+            "end_date": end_date,
+            "hourly": fields,
+            "models": "era5",
+            "wind_speed_unit": "ms",
+        },
+    )
+    df = _build_era5_df(responses[0], fields)
+    logger.info("Writing: %s", cache_path)
+    write_parquet_atomic(df, cache_path)
+    return df
+
+
+def get_hot_era5_hourly_df(
+    *,
+    start_date: str = HOT_ERA5_START,
+    end_date: str = HOT_ERA5_END,
+    fields: list[str] = HOT_ERA5_FIELDS,
+) -> pd.DataFrame:
+    """Fetch hourly ERA5 data for the HOT site (convenience wrapper over :func:`get_era5_hourly_df`)."""
+    return get_era5_hourly_df(lat=HOT_LAT, lon=HOT_LON, start_date=start_date, end_date=end_date, fields=fields)
+
+
+def get_hot_reanalysis_datasets() -> list[ReanalysisDataset]:
+    """Return a list of ReanalysisDataset objects for the HOT site."""
+    return [
+        ReanalysisDataset(
+            id=f"ERA5_{HOT_LAT:.2f}_{HOT_LON:.2f}",
+            data=get_hot_era5_hourly_df(),
+        )
+    ]