Add residual chart: Toto vs NWS error for past 48h temp predictions

We log every forecast snapshot, so we already have everything needed to
visualize accuracy over time — not just an aggregate MAE. New chart
under the scoreboard headline:

- For each hourly target in the last 48 h, pick each model's prediction
whose forecast_made_at is closest to (target − 3 h). Fixed lag = like-
for-like comparison.
- Plot signed residual (prediction − actual). Zero line = perfect.

Two lines (Toto blue, NWS red dashed) so the viewer can read 'Toto was
+5°F off at 3 AM, NWS was +1°F' at a glance.

- forecast_log.residuals(metric, window_hours, lag_hours)
- weather_ui.residual_figure(df)
- app.py wires it under the scoreboard

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app.py

@@ -23,6 +23,7 @@ from src.weather_ui import (
     aligned_comparison_markdown,
     combined_figure,
     hero_markdown,
+    residual_figure,
 )
 
 AUTO_REFRESH_SECONDS = 15 * 60          # background tick + archive sync
@@ -280,8 +281,12 @@ def refresh():
         comparison_md = ""
     scoreboard = render_scoreboard(log_conn)
 
+    # Residual chart — past 48h of 3h-ahead temperature predictions vs actual.
+    resid_df = forecast_log.residuals(log_conn, metric="temp_f", window_hours=48, lag_hours=3.0)
+    resid_fig = residual_figure(resid_df) if not resid_df.empty else None
+
     persist.push_db_async()
-    return hero, comparison_md, week["fig"], scoreboard
+    return hero, comparison_md, week["fig"], scoreboard, resid_fig
 
 
 # --- scoreboard ----------------------------------------------------------
@@ -418,6 +423,7 @@ with gr.Blocks(title="Toto Weather Forecast", theme=gr.themes.Soft()) as demo:
     )
 
     scoreboard_md = gr.Markdown()
+    residual_plot = gr.Plot(label="Forecast residual")
 
     gr.Markdown(f"### 📅 {VIEW_WEEK['label']}")
     week_plot = gr.Plot(label="Weekly")
@@ -464,7 +470,7 @@ with gr.Blocks(title="Toto Weather Forecast", theme=gr.themes.Soft()) as demo:
             "Full spec: [`docs/toto-inference.md`](https://huggingface.co/spaces/bitsofchris/time-series-ai-weather-forecast/blob/main/docs/toto-inference.md)."
         )
 
-    outputs = [hero_md, comparison_md, week_plot, scoreboard_md]
+    outputs = [hero_md, comparison_md, week_plot, scoreboard_md, residual_plot]
     demo.load(refresh, outputs=outputs)
 
 

src/forecast_log.py

@@ -277,6 +277,61 @@ def historical_predictions(
     return df
 
 
+def residuals(
+    conn: sqlite3.Connection,
+    metric: str,
+    window_hours: int = 48,
+    lag_hours: float = 3.0,
+) -> pd.DataFrame:
+    """For each hourly target_ts in the last `window_hours`, return Toto's
+    and NWS's predictions and the Ecowitt actual side-by-side, plus signed
+    residuals (prediction − actual).
+
+    Both predictions are selected at a fixed lag from target_ts so the
+    residual time series compares like-with-like: 'how far off was each
+    model's N-hours-ahead prediction for this hour?'.
+    """
+    import time as _time  # noqa: PLC0415
+    now = int(_time.time())
+    cutoff = now - window_hours * 3600
+    lag_seconds = int(lag_hours * 3600)
+    sql = """
+    WITH ranked AS (
+        SELECT source, target_ts, p50,
+               ROW_NUMBER() OVER (
+                   PARTITION BY source, target_ts
+                   ORDER BY ABS(forecast_made_at - (target_ts - ?))
+               ) AS rk
+        FROM forecast_snapshots
+        WHERE metric = ?
+          AND forecast_made_at <= target_ts
+          AND target_ts BETWEEN ? AND ?
+    ),
+    picked AS (
+        SELECT source, target_ts, p50 FROM ranked WHERE rk = 1
+    )
+    SELECT a.target_ts,
+           MAX(CASE WHEN p.source='toto' THEN p.p50 END) AS toto_p50,
+           MAX(CASE WHEN p.source='nws'  THEN p.p50 END) AS nws_p50,
+           a.value AS actual
+    FROM actuals a
+    LEFT JOIN picked p USING (target_ts)
+    WHERE a.metric = ?
+      AND a.target_ts BETWEEN ? AND ?
+    GROUP BY a.target_ts
+    ORDER BY a.target_ts
+    """
+    params = [lag_seconds, metric, cutoff, now, metric, cutoff, now]
+    df = pd.read_sql_query(sql, conn, params=params)
+    if df.empty:
+        return df
+    df.index = pd.to_datetime(df["target_ts"], unit="s", utc=True)
+    df = df.drop(columns=["target_ts"])
+    df["toto_residual"] = df["toto_p50"] - df["actual"]
+    df["nws_residual"] = df["nws_p50"] - df["actual"]
+    return df
+
+
 def scoreboard_summary(
     conn: sqlite3.Connection,
     metric: str = "temp_f",

src/weather_ui.py

@@ -181,6 +181,41 @@ def emoji_strip_markdown(nws_df: pd.DataFrame, tz: str, n: int = 12) -> str:
     return f"| {hours} |\n{sep}\n| {glyphs} |\n| {temps} |"
 
 
+def residual_figure(
+    df: pd.DataFrame,
+    title: str = "Forecast residual — 3h-ahead prediction minus Ecowitt actual (°F)",
+) -> go.Figure:
+    """Plot signed residuals over time for Toto and NWS. Zero is perfect."""
+    fig = go.Figure()
+    fig.add_hline(y=0, line=dict(color="#888", width=1))
+    fig.add_trace(
+        go.Scatter(
+            x=df.index, y=df["toto_residual"],
+            name="🤖 Toto residual", mode="lines+markers",
+            line=dict(color="#1f77b4", width=2),
+            marker=dict(size=5),
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df.index, y=df["nws_residual"],
+            name="🌎 NWS residual", mode="lines+markers",
+            line=dict(color="#d62728", width=2, dash="dash"),
+            marker=dict(size=5),
+        )
+    )
+    fig.update_layout(
+        title=title,
+        height=320,
+        hovermode="x unified",
+        yaxis_title="°F (signed error)",
+        margin=dict(l=50, r=20, t=50, b=50),
+        legend=dict(orientation="h", yanchor="bottom", y=1.04, xanchor="right", x=1),
+    )
+    fig.update_xaxes(tickformat="%b %-d\n%-I %p", showgrid=True)
+    return fig
+
+
 def combined_figure(
     history: pd.DataFrame,
     totos: dict[str, TotoForecast],