Your regime model might be producing different risk labels depending on which features you feed it — and your current validation doesn't catch this. mrv-lib tests for this.
Built for SR 11-7 / Basel IV (FRTB) model risk governance
Most regime models are validated on in-sample fit metrics (BIC, log-likelihood). Nobody asks: do the labels survive a change in input representation?
GMM, HMM, or any clustering method on volatility, drawdown, VaR, CVaR, and other risk factors.
"Low risk", "Medium risk", "Crisis" — neat categories that drive risk limits, capital allocation, and hedging decisions.
Replace max drawdown with realized skewness, and the labels change. Same data, same model, different answers.
If downstream decisions depend on regime labels, but the labels depend on an arbitrary feature choice, then your decisions are not well-founded. SR 11-7 requires you to document this.
Fit the same model on multiple factor sets, then measure pairwise label agreement.
Adjusted Rand Index (ARI) ≥ 0.65
Are the labels the same?
Spearman rank correlation ≥ 0.85
Do they at least rank risk consistently?
A model that fails partition but passes ordering means: exact label boundaries shift, but relative risk ranking is preserved. Less severe, but still a material finding for SR 11-7 documentation.
Everything you need to validate regime model stability.
Volatility, drawdown, max drawdown, VaR, CVaR, realized skewness, vol-of-vol. Extensible registry.
Gaussian Mixture and Hidden Markov built-in. Plug in your own via register_model().
ARI, AMI, NMI, Variation of Information, and Spearman ordering consistency.
JSON → LaTeX → PDF. Professional reports with dashboards, heatmaps, and remediation plan.
Single YAML config. 6-step modular pipeline: download → load → factors → fit → validate → report.
Download 5m/15m/1h/1d bars from Interactive Brokers. Incremental updates, multi-asset.
Three commands to your first representation invariance report. Or use the Python API for full control. No IB account? Use the example notebook with synthetic data.
# Install
pip install mrv-lib[all]
# Download data (requires IB Gateway)
python run.py download config.yaml
# Run representation invariance test + PDF report
python run.py run config.yaml rep
# Regenerate PDF from existing results
python run.py reportfrom mrv.pipeline import run, download
download("config.yaml") # fetch data from IB
run("config.yaml", "rep") # validate + PDF report
# Or step by step (full control)
from mrv.pipeline import load_data, compute_factors
from mrv.pipeline import fit_labels, validate, report
from mrv.utils.config import load
cfg = load("config.yaml")
prices = load_data(cfg, "rep")
factors = compute_factors(prices, cfg, factor_sets)
labels = fit_labels(factors, model="gmm")
result = validate(cfg, "rep", labels=labels)
report(result["json_path"], cfg=cfg)Each release corresponds to a research paper. The library grows with the research.
Do regime labels change when you use different risk factors?
Zheng, Low & Wang (2026). Regime Labels Are Not Representation-Invariant: Implications for Model Risk Governance. Submitted.
Do labels agree across 5m / 1h / 1d frequencies?
Zheng, Low & Wang (2026). Regime Labels Are Not Resolution-Invariant: Evidence from the 2026 US–Iran Escalation. In preparation.
A single score quantifying how stable regime labels are across perturbations.
Zheng, Low & Wang. The Regime Stability Score. In preparation.
mrv-lib is built on peer-reviewed research from
Massey University and Bond University.
Zheng, K., Low, R. & Wang, R. (2026)
SubmittedZheng, K., Low, R. & Wang, R. (2026)
In preparationKai Zheng — School of Mathematical and Computational Sciences, Massey University
A/Prof. Rand Low — Bond Business School, Bond University
Prof. Ruili Wang — School of Mathematical and Computational Sciences, Massey University