Historical Analog Finder

historical-analog-finder

You hand over K (default 20) and horizon_days (default [30, 60, 90, 252]) and get back the K historical periods most similar to today's market regime, plus the forward SPY return distribution across those analogs.

Regime-conditional forecasting. The mean is not a point forecast; the IQR is the honest read.

When to invoke

• The operator asks "what usually happens after a setup like this", "any historical analogs to now", "regime analog"
• Portfolio-review workflow: after market-regime tells you WHAT, this tells you WHAT USUALLY FOLLOWS
• Sizing / cash-management decisions where forward return distribution matters more than a point estimate

What you need

• MASSIVE_API_KEY (Stocks Starter). One SPY range-aggs call for the full history window (default 20 years).

What you get back

Layer 1 JSON matching output-schema.json. Current regime feature snapshot (raw + z-scores), the K analogs with distance + forward returns per horizon, forward return distribution stats per horizon (p10, p25, median, p75, p90, mean, hit rate > 0).

Layer 2 rendered note. Current-regime snapshot block, forward- distribution table across horizons, top-analog date list with per- horizon returns. See references/rendering.md.

How it works

1. Fetch SPY over history_years (default 20).
2. Compute a daily feature panel: for every day with enough history (>= 260 bars), build a 9-dim vector:
   • 5/20/60/120-day return (4 features)
   • Above 50-day SMA (binary)
   • Above 200-day SMA (binary)
   • RSI 14
   • 20-day realized vol
   • Drawdown from 252-day high
3. Z-score the panel column-wise. Today's z-score vector is the reference.
4. Compute Euclidean distance from today to every prior day.
5. Rank by distance, then dedupe: reject any candidate within min_gap_days (default 30) of an already-accepted analog so one historical window doesn't dominate.
6. Look up forward SPY returns at each requested horizon for each accepted analog.
7. Aggregate to distribution stats per horizon.

Endpoints used

• GET /v2/aggs/ticker/SPY/range/1/day/{from}/{to} (one call, 20yr history)

Doesn't handle (yet)

• SPY-only feature set. Sector rotation and rates aren't captured. A richer analog would fold in sector-rotation-signal + fixed-income-context features. Documented as a caveat.
• Regime-conditional forecasting works UNTIL the world changes structurally. Analog periods pre-2008, pre-QE, or pre-2020 sample from different macro machinery.
• The mean is not a forecast. Every render surfaces the IQR and hit-rate-above-zero as the honest reads.
• K < requested when history is thin. With 20-year history and 30-day dedupe, K=20 is achievable, but a caller passing K=50 will often see fewer than 50 accepted. The payload reports the actual count.