FrancoisRost1/volatility-regime-engine

# 波动率制度引擎 *Systematic multi-asset allocation driven by regime detection and volatility targeting.*    ## 它做什么 一个用于四资产组合（SPY、TLT、GLD、PDBC）的两层系统性配置引擎。**第一层**运行两个并行 regime 分类器：一个基于 8 特征向量的 3 状态高斯隐马尔可夫模型（仅使用滤波概率，不包含未来信息），以及一个基于趋势、波动压力、回撤和信用信号的透明规则组合检测器。两者均输出三种状态之一：RISK_ON、NEUTRAL 或 RISK_OFF。**第二层**接收 regime 标签与混合的 EWMA + 实现波动率估计，在 regime 条件下的战略倾斜内计算逆波动率权重，并将总组合敞口缩放至 regime 特定的目标波动率（15% / 10% / 6%）。引擎仅在确认 regime 变化（3 天持续过滤）或组合波动率偏离上次再平衡水平超过 20% 时再平衡，以保持低换手率和实际成本。 ## 关键结果 | Metric | Full Strategy | SPY B&H | 60/40 | Static Vol-Parity | Regime Only | |--------|:------------:|:-------:|:-----:|:-----------------:|:-----------:| | **CAGR** | **10.9%** | 10.2% | 7.8% | 6.5% | 8.7% | | **Sharpe** | **1.03** | 0.58 | 0.62 | 0.71 | 0.74 | | **Max DD** | **-21.9%** | -33.7% | -25.1% | -18.4% | -28.3% | 109 个测试通过。由 Codex 审核。 ## 仪表板 **Overview**  **Regimes**  **Portfolio**  **Analytics**  **Attribution**  ## 架构 ``` yfinance ──→ data_loader ──→ feature_builder ──→ regime_detector ──→ vol_estimator (prices, (8 features, (HMM filtered (EWMA + realized log returns) z-scored on + composite blend per asset, expanding rule-based) EWMA covariance) window) │ │ ▼ ▼ position_sizer ◄───────────┘ (strategic tilt + inverse-vol + vol-target scalar + leverage cap) │ ▼ rebalancer (regime change OR vol drift trigger, turnover-based cost) │ ▼ backtester (walk-forward, expanding window, signal at t → trade at t+1) │ ▼ analytics (tearsheet, regime conditional stats, stress tests, benchmark attribution) ``` ## 设计决策 - **仅使用过滤后的 HMM 概率。** 使用前向算法进行 regime 分类，绝不使用 Viterbi 平滑。这确保了日期 *t* 的 regime 标签仅使用截至 *t* 的数据，消除前瞻偏差。 - **信号在 *t*，交易在 *t+1*。** 严格禁止同日执行。所有信号在当日收盘时形成，交易在下一交易日收盘时执行。这是不可协商的。 - **基于换手率的交易成本。** 成本 = 5 个基点 × 再平衡日的实现换手率。波动率漂移触发的再平衡成本低于完全的 regime 翻转，符合实际执行。 - **3 天持续过滤。** 仅在新的状态持续 3 天或更长时间时才采取行动，以消除噪声驱动的翻转和虚假换手。 ## 项目结构 ``` volatility-regime-engine/ ├── main.py # Orchestrator only ├── config.yaml # All parameters ├── CLAUDE.md # Full project spec │ ├── engine/ │ ├── data_loader.py # yfinance fetch, adj close, log returns │ ├── feature_builder.py # 8-feature vector + expanding-window z-scoring │ ├── regime_detector.py # HMMRegimeDetector + CompositeRegimeDetector │ ├── vol_estimator.py # EWMA vol + realized vol blend, EWMA covariance │ ├── position_sizer.py # Inverse-vol weights + vol-targeting scalar │ ├── rebalancer.py # Trigger logic + transaction cost calculation │ ├── backtester.py # Walk-forward loop, NAV, trade log │ ├── analytics.py # Full tearsheet: CAGR, Sharpe, drawdown, Calmar │ ├── analytics_regime.py # Regime-conditional stats + transition matrix │ └── benchmarks.py # SPY B&H, 60/40, Static Vol-Parity, Regime Only │ ├── app/ │ └── streamlit_app.py # Bloomberg dark mode, 5 tabs │ ├── tests/ # 109 tests ├── data/ │ ├── raw/ # Cached yfinance downloads │ └── processed/ # Features, regime labels, NAV series ├── outputs/ │ └── tearsheet.csv └── docs/ └── analysis.md # Investment thesis + methodology ``` ## 设置 ``` git clone https://github.com/FrancoisRost1/volatility-regime-engine.git cd volatility-regime-engine pip3 install -r requirements.txt ``` 运行回测流水线： ``` python3 main.py ``` 启动仪表板： ``` python3 -m streamlit run app/streamlit_app.py ``` 数据在首次运行时从 yfinance 获取并本地缓存。无需 API 密钥。 ## 简化假设 - **忽略税收和保证金成本。** 实际杠杆组合存在融资成本（联邦基金利率 + 利差），未建模。 - **无滑点模型。** 交易成本 = 换手率 × 5 个基点。PDBC 和 GLD 的实际冲击会更大。 - **LQD 作为信用压力代理，非真实 OAS。** 与 IEF 的基于价格的相对收益，而非从债券现金流推导的利差。 - **逆波动率加权，非完全风险平价。** 基于协方差矩阵的风险平价推迟到 Project 8（portfolio-optimization-engine）。 - **风险中性利率 = 0%**。Sharpe 计算中现金在去风险期间不产生收益。 ## 技术栈 | Library | Purpose | |---------|---------| | pandas / numpy | 数据操作与数值计算 | | yfinance | 价格历史（无需 API 密钥） | | hmmlearn | 高斯 HMM 用于 regime 检测 | | scipy | 统计计算 | | PyYAML | 配置加载 | | streamlit | 交互式仪表板 | | plotly | 图表 | | pytest | 109 测试套件 | *Project 5 of 11 in a systematic finance GitHub series, [github.com/FrancoisRost1](https://github.com/FrancoisRost1)* ## 作者 Francois Rostaing, [GitHub](https://github.com/FrancoisRost1)

标签：109次测试, 3日持久性过滤, 3状态分类, 8特征向量, CAGR, Codex审计, Dashboard, EWMA, GLD, GMM, HMM, MIT License, PDBC, Python 3.9, SEO, SPY, Streamlit, TLT, Walk-forward, Walk-forward backtest, yfinance, 中性风险, 交易成本, 再平衡, 周转率控制, 回溯测试, 因子择时, 夏普比率, 多资产组合, 安全规则引擎, 实现波动率, 开源策略, 恶意代码分类, 扩展窗口, 指数加权移动平均, 最大回撤, 波动率滤波, 波动率目标, 滚动窗口, 状态分类, 系统性策略, 规则复合, 访问控制, 资产配置, 逆向工具, 透明可解释, 量化投资, 隐含风险平价, 隐马尔可夫模型, 风险偏好, 风险平价, 风险开关, 风险规避, 高斯隐马尔可夫模型