市场状态智能检测器 (Regime Detector)
概述
市场状态智能检测器是一个基于隐马尔可夫模型(HMM)和变点检测算法的量化金融分析工具。它通过分析A股市场真实数据（akshare接口），自动识别市场的牛市、熊市、震荡、危机等状态切换，并生成可视化HTML报告。
核心算法
| 算法 | 说明 | 实现库 |
|---|---|---|
| 高斯HMM | 隐马尔可夫模型，Baum-Welch训练+Viterbi解码 | hmmlearn |
| CUSUM | 累积和变点检测，检测均值漂移 | 自实现 |
| PELT | 精确线性时间变点检测 | ruptures |
| 贝叶斯在线变点 | 运行长度后验分布检测 | 自实现 |
| GARCH(1,1) | 条件异方差波动率建模 | arch |
支持的市场状态
| 状态数 | 状态标签 | 适用场景 |
|---|---|---|
| 2 | 熊市、牛市 | 简单牛熊判断 |
| 3 | 熊市、震荡、牛市 | 标准市场状态分析（默认） |
| 4 | 危机、熊市、震荡、牛市 | 精细化状态识别 |
安装
# 克隆项目
git clone <repository-url>
cd regime-detector
# 安装依赖
pip install -r requirements.txt
依赖列表
- akshare >= 1.12.0 （A股数据获取）
- hmmlearn >= 0.3.0 （HMM模型）
- ruptures >= 1.1.0 （PELT变点检测）
- arch >= 5.0.0 （GARCH模型）
- numpy, pandas, scipy, scikit-learn （数据处理）
- matplotlib >= 3.7.0 （可视化）
- rich >= 13.0.0 （终端美化）
使用方法
基本用法
# 检测个股市场状态（3状态HMM，默认全部方法）
python detect.py --ticker 000001 --states 3 --start 20200101
# 检测沪深300指数（仅HMM方法）
python detect.py --index sh000300 --method hmm
# 检测上证指数（全部分析，4状态）
python detect.py --index sh000001 --method all --states 4 --start 20200101
# 仅波动率分析
python detect.py --ticker 600519 --method volatility --start 20210101
# 指定特征子集
python detect.py --ticker 000001 --features log_return,rolling_vol,rsi --start 20200101
参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
| --ticker | 个股代码（与--index互斥） | - |
| --index | 指数代码（与--ticker互斥） | - |
| --method | 分析方法: hmm/changepoint/volatility/all | all |
| --states | HMM状态数: 2/3/4 | 3 |
| --start | 开始日期 YYYYMMDD | 20200101 |
| --end | 结束日期 YYYYMMDD | 今天 |
| --freq | 数据频率: daily/weekly/monthly | daily |
| --output | 输出目录 | output/ |
| --features | 指定HMM特征（逗号分隔） | 全部 |
支持的指数代码
| 代码 | 名称 |
|---|---|
| sh000001 | 上证指数 |
| sh000300 | 沪深300 |
| sh000016 | 上证50 |
| sh000905 | 中证500 |
| sz399001 | 深证成指 |
| sz399006 | 创业板指 |
| sh000688 | 科创50 |
输出示例
运行后将在 output/ 目录生成以下文件：
1. HTML报告 (report_*.html)
自包含的HTML文件，包含：
- 分析摘要（当前状态、关键指标卡片）
- HMM状态分析（状态统计表、转移矩阵、持续时间分析）
- 价格走势+状态着色图
- 状态转移概率热力图
- 变点检测标注图
- 波动率状态图（含GARCH条件波动率）
- GARCH(1,1)模型参数表
- 波动率聚集效应分析
2. 状态数据CSV (states_*.csv)
包含日期、收盘价、对数收益率、HMM状态编号和状态标签。
终端输出示例
╭─────────────────────────────────────────────╮
│ 市场状态智能检测器 │
│ 标的: 指数 sh000001 (上证指数) │
│ 方法: all │
│ 状态数: 3 │
│ 数据范围: 20200101 ~ 20260708 │
│ 频率: daily │
╰─────────────────────────────────────────────╯
获取数据: 1582 条记录
特征计算完成: 8 个特征
HMM训练完成: 对数似然=3245.7
变点检测完成: 12 个变点
波动率分析完成: 年化波动率=18.52%
图表生成完成: 4 张
当前状态: 震荡 (置信度: 78.3%)
状态概率分布:
熊市: 5.2% █
震荡: 78.3% ████████████████
牛市: 16.5% ███
能力边界说明
能做到
- 真实数据获取：通过akshare获取A股真实历史数据（指数和个股），支持日/周/月频率。
- HMM状态检测：使用标准Baum-Welch和Viterbi算法，支持2-4状态市场状态识别，输出转移概率矩阵和状态统计。
- 变点检测：三种独立算法（CUSUM、PELT、贝叶斯在线），检测收益率均值/方差的结构性变化。
- 波动率建模：GARCH(1,1)条件波动率拟合，波动率聚集效应检验（Ljung-Box），波动率状态分类。
- 可视化报告：自包含HTML报告，matplotlib图表以base64嵌入，无需外部依赖。
不能做到
- 实时交易信号：本工具是分析工具，不提供实时交易信号或自动交易功能。
- 预测未来价格：HMM状态预测是概率性的，不预测具体价格走势。
- 多资产组合分析：当前版本仅支持单一标的分析，不支持组合层面的状态检测。
- 期权隐含波动率：akshare不提供期权IV数据，波动率对比使用GARCH条件波动率代替隐含波动率。
- 高频数据分析：当前仅支持日/周/月频率，不支持tick级或分钟级数据。
- 保证盈利：市场状态检测是统计分析，不保证任何投资收益。
数据限制
- 依赖akshare接口稳定性，网络问题可能导致数据获取失败。
- 个股数据默认使用前复权（qfq），可能影响绝对价格水平但不影响收益率分析。
- 历史数据长度受akshare接口限制，一般可获取近10-20年数据。
FAQ
Q1: HMM状态数应该选2、3还是4？
A: 取决于分析需求：
- 2状态：适合简单的牛熊判断，状态区分度高但粒度粗。
- 3状态（推荐）：增加"震荡"状态，更贴近真实市场，是大多数分析的最佳选择。
- 4状态：增加"危机"状态，适合需要识别极端行情的研究，但需要更多数据支撑（建议至少3年以上）。
如果不确定，建议先用3状态运行，观察状态统计后再决定是否调整。
Q2: 为什么有时HMM训练会失败或结果不理想？
A: 常见原因及解决方案：
1. 数据量不足：HMM至少需要50个有效样本（去除NaN后）。建议至少使用1年以上数据。
2. 特征过多导致过拟合：尝试使用 --features log_return,rolling_vol 减少特征数。
3. 数据频率问题：月线数据样本量少，建议使用日线或周线。
4. 收敛问题：HMM可能陷入局部最优。代码使用 random_state=42 保证可复现，可尝试调整特征组合获得不同结果。
Q3: 三种变点检测算法有什么区别？应该用哪个？
A:
- CUSUM：检测均值漂移，适合检测趋势性变化。计算快，但只检测均值变化。
- PELT：精确算法，可检测均值和方差变化（使用rbf核）。推荐作为主力算法。
- 贝叶斯在线：提供变点概率，适合需要不确定性量化的场景。计算较慢。
- 建议：使用 --method all 同时运行三种算法，综合判断变点位置。
Q4: GARCH模型的alpha+beta参数接近1意味着什么？
A: alpha+beta是GARCH的持续性参数：
- 接近1（如0.95-0.99）：波动率聚集效应强，当前波动对未来的影响持续时间长。这是A股市场的典型特征。
- 小于0.9：波动率聚集较弱，冲击消退快。
- 大于1：模型不平稳，说明数据可能不适合GARCH建模或存在结构性变化。
代码中会自动检测平稳性并标注。
Q5: 报告中的"状态置信度"是什么意思？
A: 置信度是当前时间点处于该状态的后验概率 P(z_t = k | X)，由HMM的前向-后向算法计算。它表示在给定所有观测特征的情况下，市场处于某个特定状态的概率。置信度越高，状态判断越可靠。低于50%的置信度表示状态不明确，可能处于状态转换的过渡期。
Q6: 可以用这个工具做回测吗？
A: 本工具本身不提供回测框架，但生成的状态序列CSV可以导入到回测系统中。常见用法：
- 根据HMM状态调整仓位（牛市满仓、熊市空仓、震荡半仓）
- 在变点位置设置风控触发条件
- 根据波动率状态调整止损宽度
Q7: 如何自定义特征？
A: 通过 --features 参数指定特征子集：
python detect.py --ticker 000001 --features log_return,rolling_vol,rsi,momentum
可选特征：log_return（对数收益率）、rolling_vol（滚动波动率）、squared_return（平方收益率）、volume_change（成交量变化率）、turnover_indicator（换手率指标）、momentum（动量）、rsi（RSI）、price_accel（价格加速度）。
技术架构
detect.py (CLI入口)
│
├── data.py → akshare数据获取
├── features.py → 特征工程（8个特征）
├── hmm_model.py → HMM状态检测（hmmlearn）
├── changepoint.py → 变点检测（CUSUM/PELT/Bayesian）
├── volatility.py → 波动率分析（GARCH）
└── report.py → HTML报告生成（matplotlib）
许可证
MIT License - 详见项目根目录 LICENSE 文件。
免责声明
本工具仅供学术研究和教育目的使用，不构成任何投资建议。金融市场分析存在固有风险，历史数据表现不代表未来结果。使用者需自行承担投资决策的全部责任。
