File size: 3,170 Bytes
66f566e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | ---
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.
|