aec64b4058
Score how far a location's last 6 years have drifted from its full 45-year record. For each metric and percentile category (p10/p25/p50/p75/p90), the recent-years value is placed on the baseline distribution and the gap from the expected percentile is the divergence — unit-free, so metrics compare directly. Scored per meteorological season plus annual, weighted into per-metric and overall scores (temps, humidity and feels-like weighted heaviest). - backend/scoring.py: divergence math, seasonal slicing, precip zero-inflation split (wet-day frequency + amount), tier mapping onto the existing temp scale. - climate.py: derive a wet-bulb column (Stull 2011) at the read boundary, before the humidity column is converted to absolute — via a shared _derive_metrics wrapper at all four read sites. - api/v2/score endpoint + build_score payload, cached on the history token with a scoring-version key. - frontend score page: overall hero, per-metric cards, by-season chips, and a button-revealed summary (sentences + metrics×season table + per-percentile detail). Score nav link across all headers. - Tests for the scoring math, wet-bulb formula, payload shape and route.
186 lines
8.6 KiB
Python
186 lines
8.6 KiB
Python
"""The payload layer: pure builders, span clamping, and the layering guarantee
|
|
that offline callers (migrate) can use it without dragging in the web stack."""
|
|
import datetime
|
|
import os
|
|
import subprocess
|
|
import sys
|
|
|
|
import polars as pl
|
|
import pytest
|
|
|
|
import climate
|
|
import views
|
|
|
|
CELL = {"id": "1642_-4223", "center_lat": 47.6087, "center_lon": -122.29377}
|
|
|
|
|
|
def test_views_and_migrate_import_without_the_web_stack():
|
|
"""migrate.py must stay runnable offline: importing the payload layer may
|
|
not construct the FastAPI app or start the places-index download."""
|
|
code = ("import sys; import views, migrate; "
|
|
"assert 'fastapi' not in sys.modules, 'views/migrate pulled in FastAPI'; "
|
|
"assert 'app' not in sys.modules, 'views/migrate imported the web app'; "
|
|
"import places; assert places._load_started is False")
|
|
backend = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
subprocess.run([sys.executable, "-c", code], cwd=backend, check=True)
|
|
|
|
|
|
# ---- cache identity --------------------------------------------------------------
|
|
# These formats are shared by the endpoints, the /cell bundle and migrate; pin
|
|
# them so a change is always deliberate (an accidental drift silently strands
|
|
# every existing derived row — change them only alongside a PAYLOAD_VER bump).
|
|
|
|
def test_cache_identity_formats_are_pinned(history):
|
|
t = datetime.date(2026, 6, 15)
|
|
assert views.grade_key(t, 14, 7) == "2026-06-15:14:7"
|
|
assert views.calendar_key(t, datetime.date(2026, 6, 20), 24) == "2026-06-15:2026-06-20:24"
|
|
assert views.day_key(t) == "2026-06-15"
|
|
assert views.forecast_key(t, 7) == "2026-06-15:7"
|
|
assert views.history_token(history) == f"{views.PAYLOAD_VER}:{views.hist_end(history)}"
|
|
|
|
|
|
def test_recent_token_composes_history_and_stamp(history, monkeypatch):
|
|
monkeypatch.setattr(climate, "recent_stamp", lambda cid: "stamp")
|
|
assert views.recent_token(history, "1_2") == f"{views.history_token(history)}:stamp"
|
|
|
|
|
|
def test_day_token_expires_hourly_only_beyond_the_archive(history):
|
|
last = history["date"].max()
|
|
assert views.day_token(history, last) == views.history_token(history)
|
|
future = views.day_token(history, last + datetime.timedelta(days=1))
|
|
assert future.startswith(views.history_token(history) + ":h")
|
|
|
|
|
|
# ---- cal_span clamping ---------------------------------------------------------
|
|
|
|
def _hist(start, end):
|
|
# cal_span only reads the record's min/max date, so two rows pin the span.
|
|
return pl.DataFrame({"date": [datetime.date.fromisoformat(start),
|
|
datetime.date.fromisoformat(end)]})
|
|
|
|
|
|
def test_cal_span_defaults_to_months_back_same_day_of_month():
|
|
start_ts, end_ts = views.cal_span(_hist("2020-01-01", "2026-06-29"), None, None, 24)
|
|
assert end_ts == datetime.date(2026, 6, 29)
|
|
assert start_ts == datetime.date(2024, 6, 29)
|
|
|
|
|
|
def test_cal_span_clamps_to_the_record():
|
|
h = _hist("2025-03-01", "2026-06-29") # record shorter than the 2-year cap
|
|
start_ts, end_ts = views.cal_span(h, "2020-01-01", None, 24)
|
|
assert start_ts == datetime.date(2025, 3, 1) # can't start before the record
|
|
_, end_ts = views.cal_span(h, None, "2030-01-01", 24)
|
|
assert end_ts == datetime.date(2026, 6, 29) # nor end past it
|
|
|
|
|
|
def test_cal_span_caps_at_two_years():
|
|
start_ts, end_ts = views.cal_span(_hist("2018-01-01", "2026-06-29"),
|
|
"2018-01-01", "2026-06-29", 24)
|
|
assert (end_ts - start_ts).days == views.CAL_MAX_SPAN_DAYS - 1
|
|
|
|
|
|
def test_cal_span_never_inverts():
|
|
start_ts, end_ts = views.cal_span(_hist("2020-01-01", "2026-06-29"),
|
|
"2026-06-01", "2021-01-01", 24)
|
|
assert start_ts == end_ts
|
|
|
|
|
|
def test_months_before_clamps_month_end_and_leap():
|
|
"""Calendar-aware month subtraction (replaces pandas DateOffset): land on the
|
|
same day-of-month, clamped to the target month's last valid day."""
|
|
assert views._months_before(datetime.date(2026, 3, 31), 1) == datetime.date(2026, 2, 28)
|
|
assert views._months_before(datetime.date(2024, 3, 31), 1) == datetime.date(2024, 2, 29)
|
|
assert views._months_before(datetime.date(2026, 1, 15), 14) == datetime.date(2024, 11, 15)
|
|
|
|
|
|
def test_attach_dry_streaks_prefers_the_fresher_source_on_shared_dates():
|
|
"""De-dup keeps the recent/forecast row over the archive one for a shared date
|
|
(concat archive-first, keep='last') — the fresher precip drives the streak."""
|
|
d = datetime.date(2026, 1, 1)
|
|
hist = pl.DataFrame({"date": [d], "precip": [1.0]}) # archive: it rained (streak resets)
|
|
rec = pl.DataFrame({"date": [d], "precip": [0.0]}) # fresher: dry (streak counts)
|
|
graded = [{"date": d.isoformat()}]
|
|
views._attach_dry_streaks(graded, hist, rec) # archive first, recent last
|
|
assert graded[0]["dsr"] == 1 # recent (dry) won
|
|
|
|
|
|
# ---- builders -------------------------------------------------------------------
|
|
|
|
def test_build_grade_window_and_shape(history, recent):
|
|
target = datetime.date.today()
|
|
payload = views.build_grade(CELL, target, 14, history, recent,
|
|
{"cached": True}, "Testville")
|
|
assert payload["target_date"] == target.isoformat()
|
|
days = [d["date"] for d in payload["recent"]]
|
|
assert days == sorted(days, reverse=True) # newest first
|
|
assert payload["climatology"]["tmax"] is not None
|
|
assert all(d["dsr"] is not None for d in payload["recent"])
|
|
|
|
|
|
def test_build_day_pulls_future_obs_from_recent(history, recent):
|
|
today = datetime.date.today()
|
|
payload = views.build_day(CELL, history, today, "Testville", recent=recent)
|
|
assert payload["detail"]["date"] == today.isoformat()
|
|
assert payload["detail"]["metrics"]["tmax"]["obs"] is not None
|
|
|
|
|
|
def test_build_day_survives_recent_fetch_failure(history, monkeypatch):
|
|
def boom(cell):
|
|
raise RuntimeError("upstream down")
|
|
monkeypatch.setattr(climate, "get_recent_forecast", boom)
|
|
today = datetime.date.today()
|
|
payload = views.build_day(CELL, history, today, "Testville")
|
|
assert payload["detail"]["metrics"]["tmax"]["obs"] is None # climatology only
|
|
assert payload["detail"]["metrics"]["tmax"]["ladder"] is not None
|
|
|
|
|
|
def test_build_forecast_only_future_days(history, recent):
|
|
today = datetime.date.today()
|
|
payload = views.build_forecast(CELL, 7, history, recent, today, None)
|
|
days = [d["date"] for d in payload["recent"]]
|
|
assert days == sorted(days, reverse=True) # furthest-out first
|
|
assert min(days) > today.isoformat()
|
|
assert payload["forecast"] is True
|
|
|
|
|
|
# ---- build_score ---------------------------------------------------------------
|
|
|
|
def _full_history(years=45, seed=5):
|
|
"""A 45-year all-metric record — enough span for the climate score (the shared
|
|
20-year `history` fixture is intentionally below MIN_BASELINE_YEARS)."""
|
|
import numpy as np
|
|
end = datetime.date(2026, 7, 11)
|
|
start = datetime.date(end.year - years, end.month, end.day)
|
|
dates = [start + datetime.timedelta(days=i) for i in range((end - start).days + 1)]
|
|
n = len(dates)
|
|
rng = np.random.default_rng(seed)
|
|
doy = np.array([d.timetuple().tm_yday for d in dates])
|
|
tmax = 55 + 30 * np.sin((doy - 100) / 366.0 * 2 * np.pi) + rng.normal(0, 8, n)
|
|
return pl.DataFrame({
|
|
"date": dates, "tmax": np.round(tmax, 1), "tmin": np.round(tmax - 15, 1),
|
|
"feels": np.round(tmax + 1, 1), "humid": np.round(np.clip(12 + rng.normal(0, 3, n), 1, None), 1),
|
|
"wetbulb": np.round(tmax - 12, 1), "wind": np.round(np.clip(8 + rng.normal(0, 3, n), 0, None), 1),
|
|
"gust": np.round(np.clip(16 + rng.normal(0, 5, n), 0, None), 1),
|
|
"precip": np.where(rng.random(n) < 0.3, 0.2, 0.0),
|
|
}).with_columns(pl.col("date").dt.ordinal_day().cast(pl.Int16).alias("doy"))
|
|
|
|
|
|
def test_build_score_shape():
|
|
hist = _full_history()
|
|
payload = views.build_score(CELL, hist, "Testville")
|
|
assert payload["api_version"] == "v2"
|
|
assert payload["cell"] == CELL and payload["place"] == "Testville"
|
|
assert payload["latest"] == views.hist_end(hist)
|
|
s = payload["scores"]
|
|
assert set(s["slices"]) == {"annual", "djf", "mam", "jja", "son"}
|
|
ann = s["slices"]["annual"]
|
|
assert ann["overall"]["score"] is not None
|
|
assert ann["metrics"]["tmax"]["score"] is not None
|
|
assert ann["metrics"]["wetbulb"]["score"] is not None # derived metric flows through
|
|
|
|
|
|
def test_score_key_is_the_version():
|
|
assert views.score_key() == views.SCORE_VER
|
|
# Score payloads are history-only, so they ride the plain history token.
|
|
hist = _full_history()
|
|
assert views.history_token(hist) == f"{views.PAYLOAD_VER}:{views.hist_end(hist)}"
|