| --- |
| license: mit |
| library_name: xgboost |
| tags: |
| - finance |
| - cryptocurrency |
| - market-microstructure |
| - liquidity-stress |
| - time-series |
| --- |
| |
| # MAIC — Liquidity Stress Detection (XGBoost, Pooled, Binary) |
|
|
| Production model from "An Early Warning System for Liquidity Stress in |
| Cryptocurrency Markets Using Trade Flow Analysis and Machine Learning." |
|
|
| Code: https://github.com/Goodie-Goody/maic |
| Results, labels, logs: https://huggingface.co/datasets/Goooddy/maic-results |
|
|
| ## What this model does |
|
|
| Given seven market-microstructure features (OFI, RV, Kyle's lambda, ILLIQ, |
| VWAP deviation, trade intensity, TCI) plus fractionally differenced price, |
| computed on 300-second bars of Binance BTC/ETH/SOL trade data, predicts the |
| probability the current bar reflects a liquidity-stress regime. |
|
|
| ## Performance (Fold 4, 18.8M training rows, held-out test set) |
|
|
| | Metric | Score | |
| |-----------------|--------| |
| | F1 (weighted) | 0.9706 | |
| | Seed variance | 0.0006 | |
|
|
| 56-108 minutes of advance warning before externally documented crisis |
| timestamps (FTX bankruptcy, Terra-Luna collapse), measured against reference |
| definitions the model never saw during training. |
|
|
| ## Files |
|
|
| - `xgb_binary_pooled_fold4_seed42.pkl` -- production model, pooled across |
| BTC/ETH/SOL with an asset identifier feature. **Recommended default.** |
| - `xgb_multiclass_pooled_fold4_seed42.pkl` -- multiclass variant (calm / |
| elevated / stress), backs Table 2's multiclass row. |
| - `lr_binary_pooled_fold4_seed42.pkl`, `lr_multiclass_pooled_fold4_seed42.pkl` |
| -- logistic regression baselines used for comparison in the paper. |
|
|
| **No Random Forest pickle is published.** `06d_train_production.py` |
| deliberately saves `{"model": None, "scaler": scaler}` for RF rather than the |
| fitted model object, since the underlying cuML RF classifier doesn't reliably |
| reload across different GPU sessions/driver versions. RF's metrics and |
| predictions are still valid and included in the results dataset -- only the |
| serialized model artifact itself doesn't exist in a usable form. |
|
|
| Asset-specific models at the same 5-seed production rigor don't exist: |
| `06d_train_production.py` trains pooled only by design (see code comment). |
| Single-seed asset-specific models exist in the results dataset repo under |
| `v2/results_run1/` but are exploratory, not production-grade. |
|
|
| ## Usage |
|
|
| Load with `pickle.load()`. Expects a dict with `model` (XGBoost classifier) |
| and `scaler` (fitted feature scaler). See `scripts/12_inference.py` in the |
| code repo for the full feature-construction and inference pipeline -- |
| loading the pickle alone is not sufficient without matching feature |
| engineering. |
|
|
| ## Important caveats |
|
|
| - Stress probability reflects liquidity *conditions*, not a price prediction. |
| Price impact is not guaranteed. |
| - Labels are HMM-derived (see paper Section 3.3) with a documented |
| look-ahead in retrospective Viterbi decoding, justified empirically via a |
| three-tier external validation framework (Section 3.4/4.4). |
| - Live inference reconstructs features on a single 300s window; this differs |
| from the multi-scale rolling-window construction used in training. See the |
| code repo for details on this known gap. |
|
|
