| """Method diagram: the live price-range forecaster (model B) next to the |
| volatility-regime classifier, step by step, with how each was tested. |
| |
| Numbers are read from the deployed artifacts where they exist, so the figure |
| matches what is live: btc_deployment_models/price_range/params.json and |
| outputs/price_backtest_fixes.json. |
| |
| Usage: |
| python scripts/make_method_diagram.py |
| """ |
| from __future__ import annotations |
|
|
| import json |
| from pathlib import Path |
|
|
| import matplotlib |
| matplotlib.use("Agg") |
| import matplotlib.pyplot as plt |
| from matplotlib.patches import FancyArrowPatch, FancyBboxPatch |
|
|
| ROOT = Path(__file__).resolve().parents[1] |
| SURFACE, INK, INK_2, GRID = "#fcfcfb", "#0b0b0b", "#52514e", "#e6e5e1" |
| BLUE, ORANGE = "#2a78d6", "#eb6834" |
| FILL = {BLUE: "#eef3fb", ORANGE: "#fdf0ea"} |
|
|
|
|
| def main() -> None: |
| p = json.loads((ROOT / "btc_deployment_models" / "price_range" / "params.json").read_text()) |
| bt = json.loads((ROOT / "outputs" / "price_backtest_fixes.json").read_text())["walk_forward"] |
| hw = p["hour_of_week_variance"] |
| cov = bt["24h | + Fed/CPI calendar"]["coverage"] |
| n = bt["24h | + Fed/CPI calendar"]["n"] |
| q80 = p["quantiles"]["24"]["0.8"] |
|
|
| left = [ |
| ("1 Recent volatility", |
| "Last 168 hourly BTC prices \u2192 \u03c3 = how much\nthe price typically moves per hour"), |
| ("2 Weekly pattern", |
| f"Each of the 168 hours of the week gets a factor:\nweekends {p['weekend_factor']:.2f}\u00d7, " |
| f"range {min(hw):.2f}\u00d7 \u2013 {max(hw):.2f}\u00d7 normal"), |
| ("3 Fed / CPI calendar", |
| f"Release hour {p['k_release']:.1f}\u00d7 variance, next 2 hours " |
| f"{p['k_after']:.2f}\u00d7\n(dates are published months ahead: no look-ahead)"), |
| ("4 Combine over the horizon", |
| "\u03c3\u2095 = \u03c3 \u00d7 \u221a(sum of the factors of the next h hours)"), |
| ("5 Fat tails \u2192 range", |
| f"price \u00d7 exp(\u00b1 q \u00d7 \u03c3\u2095), q learned from 2 years of\nreal outcomes " |
| f"(80%: q = {q80:.2f} instead of the normal 1.28)"), |
| ] |
| vt = json.loads((ROOT / "btc_deployment_models" / "volatility" |
| / "volatility_btc_24h_vaetransformer.json").read_text()) |
| right = [ |
| ("1 Recent market data", |
| "Last 168 hours (+ 90 days for the reference level)\nof hourly price, volume, trades, high/low"), |
| ("2 Features relative to normal", |
| f"{len(vt['features'])} features per hour (volatility 6\u2013168h, ATR, volume \u2026),\n" |
| "volatility ones divided by the 90-day median"), |
| ("3 Question (target)", |
| "Will the next 24h be MORE volatile than\nthe 90-day median? yes / no"), |
| ("4 Model: VAE + Transformer", |
| f"VAE encodes each hour, Transformer reads the {vt['sequence_length']}h\nsequence " |
| f"\u2192 P(high); {vt['seeds']}-seed average, cut-off {vt['decision_threshold']:.2f}"), |
| ("5 Answer", |
| "\u201cHIGH\u201d or \u201cLOW\u201d volatility for the next 24h"), |
| ] |
| |
| outputs = [ |
| (BLUE, "Output: a price range", |
| "live, from \\$81,520, next 24h:\n80% chance between \\$80,519 and \\$82,534"), |
| (ORANGE, "Output: a yes/no regime", |
| "live, next 24h: LOW volatility\n(probability of high: 0.31)"), |
| ] |
| tests = [ |
| (BLUE, "Tested walk-forward 2023 \u2013 2026", |
| f"Refit every quarter on the previous 2 years,\n{n:,} unseen forecasts per horizon\n\n" |
| f"50 / 80 / 95% ranges held\n{cov['50%'] * 100:.1f} / {cov['80%'] * 100:.1f} / " |
| f"{cov['95%'] * 100:.1f}% of the time (24h)\n" |
| "3\u20137% better than plain volatility (1\u201324h)"), |
| |
| |
| (ORANGE, "Tested on unseen hours, Mar \u2013 Sep 2026", |
| f"Last {vt['holdout_rows']:,} hours held out, trained on the {vt['trained_rows']:,} before\n\n" |
| f"Accuracy {vt['holdout_accuracy'] * 100:.1f}% vs \u2248 64.5% for \u201csame as now\u201d\n" |
| f"ROC-AUC {vt['holdout_auc_ensemble']:.2f}\n" |
| "(earlier tree model, 5 walk-forward folds 2022\u201326:\n71.3% \u00b1 2.2 vs 65.6% persistence)"), |
| ] |
|
|
| plt.rcParams.update({"font.family": "DejaVu Sans", "text.color": INK}) |
| fig = plt.figure(figsize=(14, 13.2), facecolor=SURFACE) |
| ax = fig.add_axes([0, 0, 1, 1]) |
| ax.set_xlim(0, 14); ax.set_ylim(0, 13.2); ax.axis("off") |
|
|
| def box(x, y, w, h, title, body, color, strong=False): |
| ax.add_patch(FancyBboxPatch((x, y), w, h, boxstyle="round,pad=0.02,rounding_size=0.12", |
| facecolor=color if strong else FILL[color], |
| edgecolor=color, linewidth=1.6 if strong else 1.1)) |
| ink = "white" if strong else INK |
| ax.text(x + 0.22, y + h - 0.2, title, fontsize=11, fontweight="bold", va="top", color=ink) |
| ax.text(x + 0.22, y + h - 0.58, body, fontsize=9.6, va="top", color="white" if strong else INK_2, |
| linespacing=1.4) |
|
|
| def arrow(x, y0, y1, color): |
| ax.add_patch(FancyArrowPatch((x, y0), (x, y1), arrowstyle="-|>", mutation_scale=13, |
| color=color, linewidth=1.3)) |
|
|
| ax.text(0.5, 12.85, "Two forecasts from the same idea: volatility clusters and is predictable", |
| fontsize=15, fontweight="bold", va="top") |
| ax.text(0.5, 12.38, "Price direction is a coin flip in every test we ran. How much the price " |
| "will move is not, and both models below forecast that, in two different forms.", |
| fontsize=9.8, color=INK_2, va="top") |
|
|
| cols = [(0.5, BLUE, "A Price range (live: \u201cWhere will the price be?\u201d)", left), |
| (7.2, ORANGE, "B Volatility regime (live: 24h volatility panel)", right)] |
| w, h, gap, top = 6.3, 1.12, 0.32, 11.55 |
| for x, color, head, steps in cols: |
| ax.text(x, top + 0.42, head, fontsize=12, fontweight="bold", color=color, va="center") |
| y = top |
| for i, (title, body) in enumerate(steps): |
| box(x, y - h, w, h, title, body, color) |
| arrow(x + w / 2, y - h, y - h - gap, color) |
| y -= h + gap |
| k = 0 if color == BLUE else 1 |
| oc, ot, ob = outputs[k] |
| box(x, y - 1.05, w, 1.05, ot, ob, oc, strong=True) |
| arrow(x + w / 2, y - 1.05, y - 1.05 - gap, color) |
| y -= 1.05 + gap |
| tc, tt, tb = tests[k] |
| box(x, y - 2.15, w, 2.15, tt, tb, tc) |
|
|
| fig.savefig(ROOT / "outputs" / "figures" / "fig14_method_diagram.png", dpi=150, facecolor=SURFACE) |
| plt.close(fig) |
| print("written: outputs/figures/fig14_method_diagram.png") |
|
|
|
|
| if __name__ == "__main__": |
| main() |
|
|
