garch-method

GARCH Method — volatility forecasting + position sizing

This skill answers the question retail never asks and every fund asks daily: how much?

It does NOT predict direction. GARCH forecasts the magnitude of moves — how violent tomorrow is likely to be, not which way it goes. Say this to the user whenever presenting results.

The three tools

All scripts live in scripts/ and run with uv run (dependencies resolve automatically via inline metadata — nothing to pip-install).

1. garch_forecast.py — the forecast

Walk-forward GARCH(1,1), zero lookahead (params re-estimated every 21 days on an expanding window; the recursion rolls forward between refits using only past data).

uv run scripts/garch_forecast.py --csv prices.csv --json
uv run scripts/garch_forecast.py --ticker BTC-USD --json

Output: 1-day-ahead vol forecast (daily + annualized), vol percentile vs trailing year, regime (calm / normal / storm).

2. vol_target.py — the size

The entire idea: size = target_vol / forecast_vol, capped at [0.25x, 2.0x].

uv run scripts/vol_target.py --csv prices.csv --target-vol 15 --json

Output: position size multiplier. "Run 0.6x your baseline" — that's the answer.

3. compare.py — the honest test

Runs the same signals twice — fixed size vs vol-targeted — and shows both equity curves plus stats side by side. Ships with an EMA 9/21 crossover demo; accepts any strategy via --signals mine.csv (columns: date, signal in {-1,0,1}).

uv run scripts/compare.py --csv prices.csv --target-vol 58 --chart equity.png --json
uv run scripts/compare.py --csv prices.csv --signals mine.csv

Output: CAGR, ann vol, Sharpe, max drawdown, worst month, final equity — both versions — plus the equity-curve chart with storm regimes shaded.

JSON contract

Every script supports --json. Core output shape:

{
  "as_of": "2026-05-23",
  "forecast_vol_annualized_pct": 41.2,
  "vol_percentile_1y": 78.0,
  "regime": "storm",
  "position_size_multiplier": 0.6,
  "note": "GARCH forecasts magnitude (volatility), not direction."
}