Skip to content

Forecast → Historical-Analog Matcher

Rev: v2.0  ·  Updated: 2026-05-29

Given a forecast, returns the ranked past races that most resemble it — and what the winners did. Encoded against the 6-race set (2012, 2014, 2016, 2018, 2022, 2024) using the W-* taxonomy. 2014 is held out as a seed/check year (--include-seed to add it).

TL;DR

  • The pipeline is fetch → classify → match → brief, all one command (scripts/daily_brief.py).
  • Default scoring is period-aware + confidence-weighted: a forecast period is scored only against the same period of each year, so a year that matches the right pattern at the right time wins over one that merely shares tags.
  • Output always shows the raw model numbers + model-agreement confidence — the match is a starting point, not an instruction.

The pipeline

Stage Script What it does
Fetch scripts/forecast_monitor/fetcher.py Open-Meteo GFS+ECMWF+ICON wind/gust/MSLP/CAPE + Marine SST/current/waves at 5 corridor waypoints → dated JSON. No key.
Classify scripts/forecast_monitor/classify.py Transparent rule-based forecast → W-* tags per period P1 (start), P2 (Stream ~+42 h), P3 (approach ~+70 h), with model-agreement confidence. Declines honestly past the horizon.
Match scripts/analysis/analog_matcher.py Scores each historical year against the classified periods (below).
Brief scripts/daily_brief.py Runs the whole chain → dated plain-language brief in data/daily-brief/.

No model reaches race day until ~T-10/T-14 — the brief states this and the Gulf Stream is the only genuinely predictive signal before then.

Running the matcher directly

# Period-aware (recommended): different pattern at start / Stream / approach
.venv/bin/python scripts/analysis/analog_matcher.py \
    --period1 W-PF \
    --period2 W-PF --period2-sec W-RC \
    --period3 W-BH --explain

# Whole-race shorthand (legacy mode)
.venv/bin/python scripts/analysis/analog_matcher.py --primary W-PF --secondary W-SQ

# JSON for the brief / tooling
.venv/bin/python scripts/analysis/analog_matcher.py --period1 W-LA --period3 W-PL --json

--explain prints the per-period source citation behind each contributing score.

Scoring

Period-aware (default). Forecast period Pₙ is scored only against the same year's Pₙ — this is what kills the score-dilution tie:

Per-period match Points
forecast primary = year's primary +3.0 × w
forecast primary = one of year's secondaries +1.5 × w
each forecast secondary matching year primary/secondary +1.0 × w

w is the year's own per-period classification confidence: HIGH 1.0 · MEDIUM 0.85 · LOW 0.7 (CONF_WEIGHT in analog_matcher.py). Ties break to the more recent year. Whole-race mode (--primary/--secondary) uses the same point values without period position.

Pre-computed scenarios

Corridor medians below are from scripts/analysis/stream_corridor_analysis.py over YB tracker data 2012–2024 (strict 40–45 ft cohort).

  • W-BH — Bermuda-High reaching race. Top analogs 2024, 2012. Decided on reaching VMG + Stream current. Default T-RH + T-CL; confirmed meander → T-ME upgrade.
  • W-PF + W-SQ — post-frontal squalls / forming ring (2022). East corridor 59.4 h median (best in set); west cost 15.7 h — but only with SST + AVISO altimetry confirmation, never RTOFS alone.
  • W-LA — light-air parking lot (2018). Light air collapses corridor differences; find the Stream core (up to 5 kt favorable). T-CF + T-CL.
  • W-PF + W-CC — cold-core ring trap (2016). T-RH unless 3-source confirmation (SST + AVISO + RTOFS); the 2016 cohort lost ~5 h chasing an RTOFS-only signal.

Tactic codes (T-*) are defined in the Routing Tactic Catalog.

Maintaining it

When a race year completes: add its section to winner_route_summary.md, add a classification row to weather_analog_framework.md, run scripts/analysis/stream_corridor_analysis.py for the new corridor stats, and add the year (with per-period tags + confidence + source) to the YEARS dict in analog_matcher.py (validated at import).

Caveats

  • 6 races is a small sample; single-occurrence patterns (W-WE, W-BS) have no analog.
  • Scoring is heuristic — combine with live RTOFS/SST/altimetry and the Stream Corridor Decision.
  • A high-confidence analog still doesn't guarantee the winning tactic works this year.

Sources

  • Pipeline code — scripts/forecast_monitor/fetcher.py, scripts/forecast_monitor/classify.py, scripts/analysis/analog_matcher.py, scripts/daily_brief.py.
  • W-* taxonomy & per-year classification — weather_analog_framework.md.
  • Winner tactics & per-period encoding — winner_route_summary.md.
  • Corridor medians — scripts/analysis/stream_corridor_analysis.py over YB tracker binaries 2012–2024.

PRE-RACE RESEARCH — not race-period routing advice. Updated 2026-05-29.