{"id":50808138,"url":"https://github.com/AccursedGalaxy/wasserstein-btc","last_synced_at":"2026-06-30T10:00:49.138Z","repository":{"id":359866990,"uuid":"1247562088","full_name":"AccursedGalaxy/wasserstein-btc","owner":"AccursedGalaxy","description":"Distributional crypto-return forecasting via Wasserstein-geodesic extrapolation in quantile-function space. WGeo family wins 12/12 (asset × horizon) cells over 6.75y walk-forward CRPS vs GARCH and classical baselines. v0.4.","archived":false,"fork":false,"pushed_at":"2026-05-24T10:36:35.000Z","size":12044,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-29T15:31:26.950Z","etag":null,"topics":["backtesting","bitcoin","caviar","crps","cryptocurrency","diebold-mariano","distributional-forecasting","econometrics","financial-modeling","forecasting","garch","har-rv","optimal-transport","python","quantile-regression","research","risk-management","time-series","wasserstein","wasserstein-barycenter"],"latest_commit_sha":null,"homepage":"https://accursedgalaxy.github.io/wasserstein-btc/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccursedGalaxy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T13:35:18.000Z","updated_at":"2026-05-25T12:37:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AccursedGalaxy/wasserstein-btc","commit_stats":null,"previous_names":["accursedgalaxy/wasserstein-btc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/AccursedGalaxy/wasserstein-btc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccursedGalaxy%2Fwasserstein-btc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccursedGalaxy%2Fwasserstein-btc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccursedGalaxy%2Fwasserstein-btc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccursedGalaxy%2Fwasserstein-btc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccursedGalaxy","download_url":"https://codeload.github.com/AccursedGalaxy/wasserstein-btc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccursedGalaxy%2Fwasserstein-btc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34961549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backtesting","bitcoin","caviar","crps","cryptocurrency","diebold-mariano","distributional-forecasting","econometrics","financial-modeling","forecasting","garch","har-rv","optimal-transport","python","quantile-regression","research","risk-management","time-series","wasserstein","wasserstein-barycenter"],"created_at":"2026-06-13T03:00:26.860Z","updated_at":"2026-06-30T10:00:49.132Z","avatar_url":"https://github.com/AccursedGalaxy.png","language":"Python","funding_links":[],"categories":["Time Series Analysis"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# wasserstein-btc\n\n### Distributional forecasting for crypto returns via geodesics on the 2-Wasserstein manifold of probability measures\n\n**A small, falsifiable, interpretable distributional forecaster — ~4 hyperparameters, no learned weights, no neural net.**\n\n[![tests](https://github.com/AccursedGalaxy/wasserstein-btc/actions/workflows/test.yml/badge.svg)](https://github.com/AccursedGalaxy/wasserstein-btc/actions/workflows/test.yml)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Live dashboard](https://img.shields.io/badge/live%20dashboard-online-7c83f2)](https://accursedgalaxy.github.io/wasserstein-btc/)\n[![Research report](https://img.shields.io/badge/research-report-orange)](docs/RESEARCH_REPORT.md)\n[![Cite](https://img.shields.io/badge/cite-CITATION.cff-purple)](CITATION.cff)\n\n[**Live dashboard**](https://accursedgalaxy.github.io/wasserstein-btc/) ·\n[**Theory**](docs/THEORY.md) ·\n[**Research report**](docs/RESEARCH_REPORT.md) ·\n[**Results**](docs/RESULTS_LONG.md) ·\n[**Roadmap**](ROADMAP.md)\n\n![WGeo-Ensemble vs GARCH-N vs Static on ETH/USDT h=21d — cumulative-mean CRPS over 6.75 years of walk-forward out-of-sample, showing the WGeo-Ensemble curve below both baselines](assets/social_preview.png)\n\n\u003c/div\u003e\n\n`wasserstein-btc` forecasts the *whole conditional distribution* of future\nlog-returns — not the mean and not the variance — for liquid crypto\npairs at horizons of 1, 5 and 21 days. The market is modelled as a\ntrajectory on the 2-Wasserstein manifold of probability measures, the\nforecast is the tangent-space extrapolation of recent quantile vectors,\nand the result is scored with strictly proper rules (CRPS) against an\nexplicit panel of baselines (Static, RW-Drift, Historical-Simulation\nBootstrap, GARCH-N, GARCH-t, GJR-GARCH-t).\n\n\u003e **What it is:** a small, falsifiable, interpretable distributional\n\u003e forecaster — ~4 hyperparameters, no learned weights, no neural net.\n\u003e **What it is not:** a trading-signal generator, a multivariate risk\n\u003e system, or a benchmark against state-of-the-art realised-volatility\n\u003e models (see [`docs/RESEARCH_REPORT.md §6`](docs/RESEARCH_REPORT.md)\n\u003e for what is *not* claimed, and [`ROADMAP.md`](ROADMAP.md) for the\n\u003e v0.4 priorities that would close that gap).\n\n## Contents\n\n- [Headline result](#headline-result) · what the panel shows\n- [Install](#install) · `uv sync` or `pip install wbtc`\n- [Quick start — CLI](#quick-start--cli) · one-line forecasts and backtests\n- [Quick start — Python](#quick-start--python) · the `forecast()` API\n- [What's novel](#whats-novel) · the four contributions\n- [Documents](#documents) · where to read the theory and the numbers\n- [Honest limitations](#honest-limitations) · what is *not* claimed\n- [Citation](#citation) · how to cite\n\n## Headline result\n\nOn the v0.4 panel (BTC + ETH + SOL + BNB × h ∈ {1, 5, 21} × 6.75 years\nwalk-forward; 1380–2470 test days per cell), the WGeo family beats the\nbest non-WGeo baseline (best of Static / RW-Drift / HS-Bootstrap /\nGARCH-N / GARCH-t / GJR-GARCH-t) in **12 / 12 cells** by 0.1% to 3.2%\nmean CRPS.\n\nThe v0.4 cycle adds (a) `WGeoEnsemble`, the W₂ barycentre of the v0.3\ntrio in quantile-function coordinates — guaranteed by Jensen's\ninequality on convex CRPS to weakly dominate the component average; and\n(b) a residualised Diebold-Mariano test (Giacomini-White 2006) that\nprojects out shared volatility-clustering noise via |y|, y², y plus\npeer-method losses, preserving the EPA null while strictly reducing\nHAC variance. Together these lift the panel's statistical evidence:\n\n| | v0.3 | v0.4 |\n|---|---:|---:|\n| Cells WGeo-family wins on CRPS | 12 / 12 | 12 / 12 |\n| Cells with **vanilla DM** p\u003c0.05 | 1 / 12 (8%) | **4 / 12 (33%)** |\n| Cells with **residualised DM** p_r\u003c0.05 | — | **8 / 12 (67%)** |\n\nPer-cell headline numbers, regime-conditional DM tables, and the full\nfalsification verdict against [`docs/THEORY.md §4`](docs/THEORY.md) are\nin [`docs/RESULTS_LONG.md`](docs/RESULTS_LONG.md). Methods-paper-style\nwriteup in [`docs/RESEARCH_REPORT.md`](docs/RESEARCH_REPORT.md).\n\n## Install\n\nThe supported workflow uses [`uv`](https://docs.astral.sh/uv/) (fast and\nreproducible). The package itself works under any Python ≥3.11.\n\n```bash\ngit clone https://github.com/AccursedGalaxy/wasserstein-btc\ncd wasserstein-btc\nuv sync          # creates .venv with locked deps\nuv run wbtc test # 53 tests, ~10 seconds\n```\n\nA PyPI release (`pip install wbtc`) is wired up via\n[`.github/workflows/publish-pypi.yml`](.github/workflows/publish-pypi.yml)\nand ships on the next signed tag — see [`ROADMAP.md`](ROADMAP.md).\n\n## Quick start — CLI\n\n```bash\nuv run wbtc info                              # what data do I have?\nuv run wbtc fetch                             # fetch / update default panel from Binance\nuv run wbtc forecast BTC/USDT -H 5 --plot     # forecast \u0026 fan-chart PNG\nuv run wbtc forecast BTC/USDT -H 5 --json     # JSON for scripting\nuv run wbtc backtest --quick                  # fast single-symbol backtest\nuv run wbtc backtest-long                     # full multi-asset (~30 min)\nuv run wbtc extended-baselines                # HAR-RV/CAViaR/MS/FIGARCH/SV/BVAR vs WGeo on BTC (~2h)\nuv run wbtc sweep                             # hyperparameter robustness\n```\n\n## Quick start — Python\n\n```python\nfrom wbtc import forecast, available_symbols, default_forecaster\n\navailable_symbols()\n# ['BNB/USDT', 'BTC/USDT', 'ETH/USDT', 'SOL/USDT', 'XRP/USDT']\n\nfc = forecast(\"BTC/USDT\", horizon=5)\nfc.median, fc.quantile(0.05), fc.quantile(0.95)\nfc.to_dict()  # JSON-safe summary\n\n# Pick a specific variant explicitly:\nfrom wbtc import WassersteinGeodesicEWMA\nfc = forecast(\"BTC/USDT\", horizon=5,\n              forecaster=WassersteinGeodesicEWMA(window=90, lookback=20))\n```\n\n`default_forecaster(horizon)` returns the recommended variant per\nhorizon (see `RESEARCH_REPORT.md §7`).\n\n## What's novel\n\n- **Per-quantile time-regression on the W₂ manifold.** The 1D-W₂-as-\n  quantile-function isometry is textbook (Villani 2009 ch. 6); applying\n  it to *time-series tangent extrapolation* of return distributions\n  appears to be under-published. The closest published method\n  (Saluzzi \u0026 Soize 2025, [arXiv:2507.07570](https://arxiv.org/abs/2507.07570))\n  uses a Koopman/EDMD-spectral approach with no regime adaptation,\n  applied to housing prices.\n- **Cosine-curvature gate.** Continuous, non-Markovian gating that\n  blends geodesic extrapolation with a static-empirical fallback when\n  consecutive tangent vectors become orthogonal. Pays off at h=1.\n- **Theil-Sen robust slope on the tangent.** 29.3% breakdown point;\n  robust to recent-history outliers without explicit regime modelling.\n- **Quantile-coordinate ensemble with GARCH.** Convex combination in\n  quantile-function space is an *exact W₂-geodesic interpolation*\n  (McCann 1997) — not a moment-matched or kernel-mixed surrogate.\n\n## Documents\n\n```\ndocs/\n  THEORY.md           math (§2.6–2.8 are the v0.3 sections, §4 lists\n                      explicit falsification criteria)\n  RESEARCH_REPORT.md  paper-style writeup of the v0.3 contributions\n  RESULTS_LONG.md     auto-regenerated 4-asset × 3-horizon evidence\n  RESULTS.md          legacy v0.1 single-year report (superseded)\n  INDEX.md            one-paragraph orientation to every doc\nROADMAP.md            v0.4 + v0.5 priorities (what would make it\n                      competitive vs. production risk systems)\nCONTRIBUTING.md       the conventions PRs must follow\nCHANGELOG.md          v0.1 → v0.2 → v0.3 history\n```\n\n## Honest limitations\n\n- We have benchmarked against **textbook baselines** as headline (Static\n  / RW / HS / GARCH-N / GARCH-t / GJR-GARCH-t across 4 assets × 3\n  horizons in [`docs/RESULTS_LONG.md`](docs/RESULTS_LONG.md)) and against\n  a broader **named-econometric panel** on BTC in\n  [`docs/RESULTS_EXTENDED.md`](docs/RESULTS_EXTENDED.md): HAR-RV (Corsi\n  2009), CAViaR-SAV (Engle-Manganelli 2004), 2-state Markov-switching\n  Normal (Hamilton 1989), FIGARCH(1,d,0) (Baillie-Bollerslev-Mikkelsen\n  1996), AR(1) Stochastic Volatility (Taylor 1982 / Harvey-Ruiz-Shephard\n  1994 via Kalman QML), and a bivariate VAR+GARCH using BTC + ETH\n  jointly. Any *production*-risk-system claim is still unsupported —\n  this rounds out the academic panel.\n- **Daily-only.** Intraday volatility dynamics are different.\n- **Univariate only.** The 1D-W₂ isometry doesn't extend cleanly to\n  higher dimensions; multivariate is a v0.5 research item.\n- **No trading P\u0026L claim.** Distributional-forecast quality is\n  necessary but not sufficient for tradeable alpha.\n- **Heteroskedastic-dispersion variant (`WGeo-Hetero`) was a\n  documented dead end** — see `RESEARCH_REPORT.md §4.4` for *why*\n  (empirical-quantile-based dispersion already encodes the regime;\n  multiplying by GARCH double-counts). The boundary is reusable.\n\n## Citation\n\nIf you use this software in academic work, please cite it.\n[`CITATION.cff`](CITATION.cff) is the structured form; the BibTeX-shaped\nquick form:\n\n```bibtex\n@software{wasserstein_btc_2026,\n  author       = {Robin Bohrer (AccursedGalaxy)},\n  title        = {wasserstein-btc: tangent-space Wasserstein-geodesic\n                  distributional forecasting for crypto returns},\n  version      = {0.4.0},\n  year         = {2026},\n  url          = {https://github.com/AccursedGalaxy/wasserstein-btc}\n}\n```\n\n## License\n\n[MIT](LICENSE).\n\n## Disclaimer\n\nThis is research code. **Not financial advice.** Falsification criteria\nare documented in `docs/THEORY.md §4` and tested against the full\nlong-horizon backtest in `docs/RESULTS_LONG.md`. Documented failures are\nin `docs/RESEARCH_REPORT.md §4.2`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAccursedGalaxy%2Fwasserstein-btc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAccursedGalaxy%2Fwasserstein-btc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAccursedGalaxy%2Fwasserstein-btc/lists"}