nrcd 0.1.0__py3-none-any.whl

nrcd/__init__.py

@@ -0,0 +1,28 @@
+"""National Running Club Database — performance standardization library."""
+
+from nrcd.standardize import (
+    PARAMETERS_DOC,
+    RaceContext,
+    XCRaceContext,
+    standardize_indoor_track,
+    standardize_outdoor_track,
+    standardize_result,
+    standardize_road,
+    standardize_seconds,
+    standardize_xc,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PARAMETERS_DOC",
+    "RaceContext",
+    "XCRaceContext",
+    "standardize_indoor_track",
+    "standardize_outdoor_track",
+    "standardize_result",
+    "standardize_road",
+    "standardize_seconds",
+    "standardize_xc",
+    "__version__",
+]

nrcd/data/__init__.py

@@ -0,0 +1,16 @@
+"""NRCD CSV column names and derived field helpers.
+
+Requires ``pip install "nrcd[data]"`` (pandas).
+"""
+
+from nrcd.data.schema import (
+    derive_course_details_fields,
+    meet_altitude_column,
+    meet_altitude_ft_from_record,
+)
+
+__all__ = [
+    "derive_course_details_fields",
+    "meet_altitude_column",
+    "meet_altitude_ft_from_record",
+]

nrcd/data/schema.py

@@ -0,0 +1,94 @@
+"""NRCD export column resolution and derived ``course_details`` fields."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Mapping
+
+from nrcd.standardize.factors import heat_index
+
+
+def _is_na(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, float) and math.isnan(value):
+        return True
+    try:
+        import pandas as pd
+
+        return bool(pd.isna(value))
+    except ImportError:
+        return False
+
+
+def meet_altitude_column(df: Any) -> str:
+    """Return meet-table altitude column name (``altitude`` or legacy ``elevation``)."""
+    import pandas as pd
+
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError("meet_altitude_column expects a pandas DataFrame")
+    if "altitude" in df.columns:
+        return "altitude"
+    if "elevation" in df.columns:
+        return "elevation"
+    raise KeyError("meet table missing altitude/elevation column")
+
+
+def _finite_altitude_ft(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        z = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(z) or z < 0:
+        return None
+    return z
+
+
+def meet_altitude_ft_from_record(
+    row: Mapping[str, Any] | Any,
+    course_details: Mapping[str, Any] | None = None,
+) -> float | None:
+    """Meet venue altitude (ft) from merged result row or ``course_details.altitude``."""
+    elev = None
+    if hasattr(row, "get"):
+        elev = row.get("altitude")
+        if _is_na(elev):
+            elev = row.get("elevation")
+    if _is_na(elev):
+        if course_details:
+            elev = course_details.get("altitude") or course_details.get("meet_elevation")
+            if elev is None:
+                elev = course_details.get("elevation")
+    return _finite_altitude_ft(elev)
+
+
+def derive_course_details_fields(record: Mapping[str, Any]) -> dict[str, Any]:
+    """Compute analysis fields not stored on ``course_details`` export rows."""
+    out: dict[str, Any] = {}
+
+    t = record.get("temperature")
+    d = record.get("dew_point")
+    h = heat_index(t, d)
+    if h is not None:
+        out["heat_index_f"] = h
+
+    race_unix = record.get("openweather_dt_unix")
+    sunrise = record.get("sunrise_unix")
+    sunset = record.get("sunset_unix")
+    if race_unix is not None and sunrise is not None and sunset is not None:
+        try:
+            race_u = int(race_unix)
+            rise_u = int(sunrise)
+            set_u = int(sunset)
+        except (TypeError, ValueError):
+            race_u = rise_u = set_u = None
+        if race_u is not None:
+            out["is_daylight"] = rise_u <= race_u <= set_u
+            if rise_u is not None:
+                out["minutes_after_sunrise"] = max(0.0, (race_u - rise_u) / 60.0)
+            if set_u is not None:
+                out["minutes_before_sunset"] = max(0.0, (set_u - race_u) / 60.0)
+
+    return out

nrcd/enrich/__init__.py

@@ -0,0 +1,53 @@
+"""Fetch meet altitude and course weather from external APIs (optional).
+
+Requires ``pip install nrcd[apis]`` (installs ``requests``).
+
+**Meet altitude** (city/state): OpenWeather geocodes; **USGS EPQS** returns feet.
+OpenWeather does **not** supply altitude — only weather, AQI, and coordinates.
+
+API signup: :data:`nrcd.enrich.API_GUIDE`.
+"""
+
+from nrcd.enrich.altitude import (
+    AltitudeResult,
+    lookup_altitude_detail,
+    lookup_altitude_ft,
+    lookup_elevation_ft,
+)
+from nrcd.enrich.api_usage import (
+    AQI_HISTORY_AVAILABLE_FROM,
+    AQI_HISTORY_AVAILABLE_UNIX,
+    ApiUsage,
+    EnrichResult,
+)
+from nrcd.enrich.batch import EnrichJob, JobResult, run_enrich_jobs
+from nrcd.enrich.cache import cache_stats, clear_enrich_cache
+from nrcd.enrich.config import EnrichConfig, api_keys_from_env
+from nrcd.enrich.context import enrich_race_context, enrich_race_context_result
+from nrcd.enrich.guide import API_GUIDE
+from nrcd.enrich.throttle import reset_throttle_state
+from nrcd.enrich.weather import WeatherData, fetch_weather
+
+__all__ = [
+    "API_GUIDE",
+    "AQI_HISTORY_AVAILABLE_FROM",
+    "AQI_HISTORY_AVAILABLE_UNIX",
+    "AltitudeResult",
+    "ApiUsage",
+    "EnrichConfig",
+    "EnrichResult",
+    "WeatherData",
+    "api_keys_from_env",
+    "EnrichJob",
+    "JobResult",
+    "cache_stats",
+    "clear_enrich_cache",
+    "enrich_race_context",
+    "enrich_race_context_result",
+    "run_enrich_jobs",
+    "fetch_weather",
+    "lookup_altitude_ft",
+    "lookup_altitude_detail",
+    "lookup_elevation_ft",
+    "reset_throttle_state",
+]

nrcd/enrich/altitude.py

@@ -0,0 +1,138 @@
+"""Meet **altitude** (venue elevation) from US city/state.
+
+OpenWeather is used **only to geocode** city/state → lat/lon. Terrain **altitude in feet**
+comes from the free USGS EPQS service (not OpenWeather).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nrcd.enrich.api_usage import ApiUsage
+from nrcd.enrich.cache import altitude_cache_key, get_or_fetch
+from nrcd.enrich.config import EnrichConfig
+from nrcd.enrich.geocode import geocode_us_city_state
+from nrcd.enrich.http import get_with_retries
+from nrcd.enrich.throttle import wait_for_provider
+
+
+@dataclass(frozen=True)
+class AltitudeResult:
+    """Venue altitude lookup result."""
+
+    altitude_ft: int
+    lat: float
+    lon: float
+    city: str
+    state: str
+
+
+def _altitude_from_coords(
+    lat: float,
+    lon: float,
+    city: str,
+    state: str,
+    *,
+    cfg: EnrichConfig,
+    usage: ApiUsage | None = None,
+) -> AltitudeResult | None:
+    wait_for_provider("usgs", cfg.usgs_min_interval_sec)
+    if usage is not None:
+        usage.record("usgs_epqs")
+    url = (
+        "https://epqs.nationalmap.gov/v1/json"
+        f"?x={lon}&y={lat}&units=Feet&includeDate=false"
+    )
+    response = get_with_retries(url, timeout=10.0, retries=cfg.http_retries)
+    response.raise_for_status()
+    data = response.json()
+    value = data.get("value")
+    if value is None:
+        return None
+    return AltitudeResult(
+        altitude_ft=int(round(float(value))),
+        lat=lat,
+        lon=lon,
+        city=city,
+        state=state,
+    )
+
+
+def lookup_altitude_ft(
+    city: str,
+    state: str,
+    *,
+    config: EnrichConfig | None = None,
+    openweather_api_key: str | None = None,
+    use_cache: bool | None = None,
+    lat: float | None = None,
+    lon: float | None = None,
+    usage: ApiUsage | None = None,
+) -> int | None:
+    """Meet altitude in feet for a US city/state (NRCD ``meet.altitude`` column)."""
+    result = lookup_altitude_detail(
+        city,
+        state,
+        config=config,
+        openweather_api_key=openweather_api_key,
+        use_cache=use_cache,
+        lat=lat,
+        lon=lon,
+        usage=usage,
+    )
+    return None if result is None else result.altitude_ft
+
+
+def lookup_altitude_detail(
+    city: str,
+    state: str,
+    *,
+    config: EnrichConfig | None = None,
+    openweather_api_key: str | None = None,
+    use_cache: bool | None = None,
+    lat: float | None = None,
+    lon: float | None = None,
+    usage: ApiUsage | None = None,
+) -> AltitudeResult | None:
+    cfg = config or EnrichConfig()
+    if openweather_api_key:
+        cfg = EnrichConfig(
+            openweather_api_key=openweather_api_key,
+            timezone_api_key=cfg.timezone_api_key,
+            geocode_country_suffix=cfg.geocode_country_suffix,
+            http_timeout_sec=cfg.http_timeout_sec,
+            http_retries=cfg.http_retries,
+            cache_enabled=cfg.cache_enabled,
+            geocode_ttl_sec=cfg.geocode_ttl_sec,
+            altitude_ttl_sec=cfg.altitude_ttl_sec,
+            timezone_ttl_sec=cfg.timezone_ttl_sec,
+            weather_ttl_sec=cfg.weather_ttl_sec,
+            timezone_min_interval_sec=cfg.timezone_min_interval_sec,
+            openweather_min_interval_sec=cfg.openweather_min_interval_sec,
+            usgs_min_interval_sec=cfg.usgs_min_interval_sec,
+        )
+    city = (city or "").strip()
+    state = (state or "").strip()
+    if lat is not None and lon is not None:
+        return _altitude_from_coords(lat, lon, city, state, cfg=cfg, usage=usage)
+    if not city or not state:
+        return None
+
+    cache_on = cfg.cache_enabled if use_cache is None else use_cache
+    cache_key = altitude_cache_key(city, state, cfg.geocode_country_suffix)
+
+    def fetch():
+        coords = geocode_us_city_state(
+            city, state, config=cfg, use_cache=cache_on, usage=usage
+        )
+        if coords is None:
+            return None
+        lat_v, lon_v = coords
+        return _altitude_from_coords(lat_v, lon_v, city, state, cfg=cfg, usage=usage)
+
+    return get_or_fetch(cache_key, fetch, ttl_sec=cfg.altitude_ttl_sec, enabled=cache_on)
+
+
+lookup_elevation_ft = lookup_altitude_ft
+lookup_elevation_detail = lookup_altitude_detail
+ElevationResult = AltitudeResult

nrcd/enrich/api_usage.py

@@ -0,0 +1,67 @@
+"""Count outbound HTTP calls during enrich lookups (cache misses only)."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+
+# OpenWeather Air Pollution history: earliest date per provider docs.
+AQI_HISTORY_AVAILABLE_FROM = dt.date(2020, 11, 27)
+AQI_HISTORY_AVAILABLE_UNIX = int(
+    dt.datetime(2020, 11, 27, 0, 0, tzinfo=dt.timezone.utc).timestamp()
+)
+
+
+@dataclass
+class ApiUsage:
+    """HTTP calls made during one enrich operation (not cache hits)."""
+
+    openweather_geocode: int = 0
+    """City/state → lat/lon (OpenWeather Geocoding API)."""
+    openweather_timemachine: int = 0
+    """Historical weather for the race hour (One Call 3.0 timemachine)."""
+    openweather_aqi: int = 0
+    """Historical air pollution for the race hour (may retry up to 3 times)."""
+    timezonedb: int = 0
+    """Lat/lon → IANA timezone (local race time → Unix)."""
+    usgs_epqs: int = 0
+    """Terrain altitude in feet (USGS EPQS; free, no API key)."""
+
+    def record(self, name: str, count: int = 1) -> None:
+        if count <= 0 or not hasattr(self, name):
+            raise ValueError(f"unknown api usage field: {name}")
+        setattr(self, name, getattr(self, name) + count)
+
+    def add(self, other: ApiUsage) -> None:
+        for fname in _USAGE_FIELDS:
+            setattr(self, fname, getattr(self, fname) + getattr(other, fname))
+
+    @property
+    def total(self) -> int:
+        return sum(getattr(self, f) for f in _USAGE_FIELDS)
+
+    def to_dict(self) -> dict[str, int]:
+        out = {f: getattr(self, f) for f in _USAGE_FIELDS}
+        out["total"] = self.total
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict[str, int]) -> ApiUsage:
+        return cls(**{f: int(data.get(f, 0)) for f in _USAGE_FIELDS})
+
+
+_USAGE_FIELDS = (
+    "openweather_geocode",
+    "openweather_timemachine",
+    "openweather_aqi",
+    "timezonedb",
+    "usgs_epqs",
+)
+
+
+@dataclass
+class EnrichResult:
+    """Race context after API enrichment plus call accounting."""
+
+    context: object
+    api_usage: ApiUsage = field(default_factory=ApiUsage)

nrcd/enrich/batch.py

@@ -0,0 +1,86 @@
+"""Run many enrich API jobs; optional parallelism with per-item results."""
+
+from __future__ import annotations
+
+import traceback
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Callable, Generic, Iterable, TypeVar
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+@dataclass(frozen=True)
+class JobResult(Generic[R]):
+    job_id: str
+    ok: bool
+    value: R | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class EnrichJob(Generic[R]):
+    """One unit of work (e.g. one meet altitude or one course weather row)."""
+
+    job_id: str
+    run: Callable[[], R]
+
+    def execute(self) -> JobResult[R]:
+        try:
+            return JobResult(job_id=self.job_id, ok=True, value=self.run())
+        except Exception as e:
+            return JobResult(
+                job_id=self.job_id,
+                ok=False,
+                error=f"{type(e).__name__}: {e}",
+            )
+
+
+def run_enrich_jobs(
+    jobs: Iterable[EnrichJob[R]],
+    *,
+    parallel: int = 1,
+    on_result: Callable[[JobResult[R]], None] | None = None,
+) -> list[JobResult[R]]:
+    """Execute jobs; process each result as it finishes (parallel or sequential).
+
+    Parameters
+    ----------
+    parallel
+        ``1`` = one job at a time (safest for rate limits). ``>1`` uses a thread pool
+        but still invokes ``on_result`` once per completed job (order varies).
+    on_result
+        Called immediately when each job completes (success or failure).
+    """
+    job_list = list(jobs)
+    if not job_list:
+        return []
+
+    results: list[JobResult[R]] = []
+
+    def _emit(res: JobResult[R]) -> None:
+        results.append(res)
+        if on_result is not None:
+            on_result(res)
+
+    if parallel <= 1:
+        for job in job_list:
+            _emit(job.execute())
+        return results
+
+    with ThreadPoolExecutor(max_workers=parallel) as pool:
+        future_map = {pool.submit(job.execute): job.job_id for job in job_list}
+        for future in as_completed(future_map):
+            try:
+                res = future.result()
+            except Exception as e:
+                jid = future_map[future]
+                res = JobResult(
+                    job_id=jid,
+                    ok=False,
+                    error=f"{type(e).__name__}: {e}\n{traceback.format_exc()}",
+                )
+            _emit(res)
+
+    return results

nrcd/enrich/cache.py

@@ -0,0 +1,97 @@
+"""In-memory TTL cache for enrich API responses (backfill-style deduplication)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import threading
+import time
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+_lock = threading.Lock()
+_store: dict[str, tuple[Any, float | None]] = {}
+_stats = {"hits": 0, "misses": 0}
+
+
+def _normalize_city_state(city: str, state: str) -> tuple[str, str]:
+    return (city or "").strip().lower(), (state or "").strip().lower()
+
+
+def geocode_cache_key(city: str, state: str, country: str = "US") -> str:
+    c, s = _normalize_city_state(city, state)
+    return f"geocode:{c}:{s}:{country.upper()}"
+
+
+def altitude_cache_key(city: str, state: str, country: str = "US") -> str:
+    c, s = _normalize_city_state(city, state)
+    return f"altitude:{c}:{s}:{country.upper()}"
+
+
+def timezone_cache_key(lat: float, lon: float) -> str:
+    return f"tz:{round(lat, 4)}:{round(lon, 4)}"
+
+
+def weather_cache_key(
+    city: str,
+    state: str,
+    event_date: dt.date,
+    event_time: dt.time,
+    country: str = "US",
+) -> str:
+    c, s = _normalize_city_state(city, state)
+    return f"weather:{c}:{s}:{country.upper()}:{event_date.isoformat()}:{event_time.isoformat()}"
+
+
+def get_cached(key: str) -> Any | None:
+    """Return cached value if present and not expired."""
+    now = time.time()
+    with _lock:
+        entry = _store.get(key)
+        if entry is None:
+            return None
+        value, expires_at = entry
+        if expires_at is not None and now >= expires_at:
+            del _store[key]
+            return None
+        _stats["hits"] += 1
+        return value
+
+
+def set_cached(key: str, value: Any, ttl_sec: float | None) -> None:
+    expires_at = None if ttl_sec is None else time.time() + ttl_sec
+    with _lock:
+        _store[key] = (value, expires_at)
+
+
+def get_or_fetch(
+    key: str,
+    fetch: Callable[[], T],
+    *,
+    ttl_sec: float | None,
+    enabled: bool = True,
+) -> T:
+    """Return cached value or call ``fetch``, store, and return."""
+    if enabled:
+        cached = get_cached(key)
+        if cached is not None:
+            return cached
+    with _lock:
+        _stats["misses"] += 1
+    value = fetch()
+    if enabled and value is not None:
+        set_cached(key, value, ttl_sec)
+    return value
+
+
+def clear_enrich_cache() -> None:
+    """Drop all cached enrich responses (tests / manual refresh)."""
+    with _lock:
+        _store.clear()
+        _stats["hits"] = 0
+        _stats["misses"] = 0
+
+
+def cache_stats() -> dict[str, int]:
+    with _lock:
+        return {"hits": _stats["hits"], "misses": _stats["misses"], "entries": len(_store)}

nrcd/enrich/config.py

@@ -0,0 +1,37 @@
+"""API keys for enrichment (pass explicitly or via environment)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class EnrichConfig:
+    """Credentials for :mod:`nrcd.enrich`."""
+
+    openweather_api_key: str | None = None
+    timezone_api_key: str | None = None
+    geocode_country_suffix: str = "US"
+    http_timeout_sec: float = 20.0
+    http_retries: int = 3
+
+    # In-memory TTL cache (NRCD backfill dedupes by city/state per batch).
+    cache_enabled: bool = True
+    geocode_ttl_sec: float = 7 * 86400
+    altitude_ttl_sec: float = 30 * 86400
+    timezone_ttl_sec: float = 365 * 86400
+    weather_ttl_sec: float = 86400
+
+    # Provider spacing (seconds between HTTP calls, per process).
+    timezone_min_interval_sec: float = 1.5  # TimeZoneDB free tier (~1 req/s)
+    openweather_min_interval_sec: float = 0.0
+    usgs_min_interval_sec: float = 0.0
+
+
+def api_keys_from_env() -> EnrichConfig:
+    """Read ``NRCD_OPENWEATHER_API_KEY`` and ``NRCD_TIMEZONE_API_KEY``."""
+    return EnrichConfig(
+        openweather_api_key=os.environ.get("NRCD_OPENWEATHER_API_KEY") or None,
+        timezone_api_key=os.environ.get("NRCD_TIMEZONE_API_KEY") or None,
+    )