是什么(一句话)

对具名 ticker 的单轴日频条件波动读数——GARCH(1,1) σ 路径(带持续性与冲击半衰期)、同种子 RiskMetrics EWMA 对照、申明式规则的波动状态(爬升/高/低/normal)。

怎么用

设 ticker(或上游接 price_factor——per-symbol 语义)后运行。读条件波动头牌与波动状态徽章,再看 GARCH σ 序列图(EWMA 对照在 CSV 里)。persistence(α+β)与冲击半衰期=波动冲击停留多久;长期波动=σ 的均值回归位。接到 risk_management(波动缩放)、casa_strategy 或 meta_strategy 上游。⬇ CSV 导出整条日轴:GARCH、EWMA、分位、状态。

核心公式

GARCH:  σ²_t = ω + α·ε²_{t-1} + β·σ²_{t-1};Gaussian QMLE(手写 NM vs SLSQP golden)
        persistence = α+β;半衰期 = ln0.5/ln(α+β);长期方差 = ω/(1−α−β)
EWMA:   σ²_t = λ·σ²_{t-1} + (1−λ)·ε²_{t-1};λ = 0.94(RiskMetrics 日频基准)
状态:   动量优先——σ 较 21 日前上行 ≥10% → 爬升;
        否则扩展分位 ≥75 高 / ≤25 低 / 其余 normal

假设与适用性

假设:Gaussian QMLE(厚尾下一致非高效);收盘-收盘百分比收益;共享样本方差种子;申明式确定性状态规则;persistence 封 0.999、贴界如实 None。

适用:≥250 个日收盘的流动性标的;条件波动水平、持续性与状态读数。

不适用:隐状态体制估计(用 markov_regime_v1 并对照)、隐含波动/曲面、波动目标 P&L、日内估计器。

输入/输出契约

输入:symbol(默认 SPY)、lookback_days(默认 756,最少 250)、ewma_lambda(默认 0.94)。

输出:metrics(garch_vol_ann、ewma_vol_ann、long_run_vol_ann、alpha、beta、omega、persistence、half_life_days、regime、vol_percentile、converged、n_days)+ 单轴命名空间 series(dates、garch_vol_ann、ewma_vol_ann、vol_percentile、regime——收益轴上全等长),外加 provenance 块申报收益标度、种子约定、估计器、状态规则原文与年化口径。

已知局限

1. 状态标签是透明申明式规则——转折期会与隐状态模型不一致,这是设计使然;与 markov_regime_v1 对照读,别把任一侧当 ground truth。
2. 参数报到优化器精度(似然沿 ω 平坦);golden 的 LL 支配闸——而非参数接近——才是质量线。
3. 仅收盘-收盘:隔夜跳空与日内振幅在族 B2 高低价估计器建成前不可见。
4. 价格史缺失或过短诚实降级(status: unavailable + 原因)——本卡绝不编造 σ。