# wq-brain

**Repository Path**: lance521/wq-brain

## Basic Information

- **Project Name**: wq-brain
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wq-brain · WorldQuant BRAIN Alpha 研究工程

B 路线（工程派）实现：**本地因子引擎预筛 + 平台批量扫描**。

---

## 一个重要修正

规划阶段我主张"先本地预筛再送平台"。建完引擎后需要修正这个判断的**适用边界**：

| 数据类别 | 能否本地预筛 | 原因 |
|---|---|---|
| Price Volume（价量） | ✅ 可以 | 本地有 OHLCV |
| Fundamental / Analyst / News / Option / Model | ❌ **不能** | 这些是 BRAIN 独有数据，本地根本没有 |

而**后者恰恰是 BRAIN 的真正护城河**（价量已被套利得最狠，最难出高夏普）。

结论：
- **本地引擎** = 价量因子的粗筛工具 + 算子语义验证器，价值中等
- **一阶扫描器**（`run_scan.py`）= 真正的搜索主力，覆盖全部数据类别

所以核心引擎是扫描器，本地引擎是辅助。两者都要，但资源投入的权重是 7:3。

---

## 文件地图

| 文件 | 作用 |
|---|---|
| `credential.json` | **需自行填写**（把 `credential.example.json` 复制改名后填入自己的 BRAIN 邮箱密码）。仅存本地，已 gitignore，**切勿提交** |
| `brain_client.py` | API 客户端：认证、回测、字段拉取、检查提交、门槛判定（含 429 退避、`Retry-After` 浮点兼容） |
| `templates.py` | **一阶模板生成器**（核心）：字段 × 算子 × 窗口 → 候选表达式 |
| `run_scan.py` | 一阶扫描：拉字段 → 生成候选 → 批量回测 → 排序出报告 |
| `fel.py` | FastExpression 本地解释器（词法/语法/求值），支持多语句赋值 |
| `factor_lab.py` | 本地因子评估：IC / ICIR / t 检验 / 分层回测 / 换手 / 逐年稳定性 |
| `seeds.py` | 18 条种子表达式（官方 2 + 社区 4 + IQC 1 + 探针 11） |
| `run_seeds.py` | 跑种子集，验证链路并校准参数手感（默认并发 2 / 提交间隔 8s，防 429） |
| `parse_westock.py` | 解析 westock 落盘的 6 个美股日K JSON → `data/us_panel.pkl`（101 只 / 5 年） |
| `local_screen.py` | 本地 IC 预筛：用真实美股 panel 跑价量种子，产出 `results/local-ic-latest.html` |
| `analyze_fields.py` | 字段样本蓝海分析：alphaCount/coverage/乘数 → `results/field-analysis.csv` |
| `test_engine.py` | 离线自测（合成数据，含注入信号），不联网不烧额度 |
| `00-研究规划.html` | 研究规划文档 |
| `01-alpha种子库.md` | 种子表达式与区域可用性说明 |
| `plans/01-方法论与专家团化设计规划.html` | **怎么想**：研究范式 · Alpha101 分类 · 算子工具箱 · 8 角色专家团 |
| `plans/02-回测流水线规划图与方法论进化机制.html` | **怎么跑 + 怎么净化**：流水线图 · 预算排期 · 门禁图 · 12 条原子规则库 · 置信度升降表 |

环境：`C:\Users\Administrator\.workbuddy\binaries\python\envs\default`

---

## 工作流

### 0. 前置：填账密
```json
// credential.json
{"email": "你的BRAIN邮箱", "password": "你的密码"}
```

### 1. 打通链路（约 10–20 分钟）
```bash
python run_seeds.py --probe                      # 首次：跑 18 条种子 + 拉取账号可用字段/算子清单
python run_seeds.py                               # 复跑：跳过已存的字段清单，只重测 18 条种子
python run_seeds.py --concurrency 2 --submit-interval 8   # 防 429 的稳妥参数（默认即此）
```
产出 `results/latest.html`，确认：账号权限、并发数、哪些数据集可用。
> ⚠️ 普通用户限频严格：并发建议 ≤2、提交间隔 ≥5s，否则会触发 HTTP 429 导致整批失败。
> 已保存 `results/operators.json`(84)、`results/datasets.json`(50)、`results/datafields.json`(2000) 可作扫描原料。

### 2. 一阶扫描（主力）
```bash
python run_scan.py --dry-run --max-fields 30 --budget 100   # 先看量级，不烧额度
python run_scan.py --datasets analyst7 --budget 100          # 分析师数据，最蓝海
python run_scan.py --datasets fundamental6 --max-fields 50 --budget 200
python run_scan.py --datasets pv1 --budget 200               # 价量，最拥挤，放最后
```

数据集扫描优先级（已内置于 `templates.py`）：
`analyst7 → analyst4 → fundamental6 → fundamental2 → news12 → news18 → socialmedia12 → sentiment1 → option9 → option8 → model51 → pv1`

### 3. 二阶优化（扫描胜出者）
对一阶胜出者施加：子行业中性化、`trade_when` 条件触发、decay 调优、`regression_neut` 提纯。
目标：把 Sharpe 0.8 抬到 1.25+，换手压进 70%。

### 4. 本地预筛（可选，仅价量）
```python
from factor_lab import FactorLab
lab = FactorLab(panel)
df = lab.screen(["-rank(ts_delta(close, 5))", "rank(ts_mean(close,30) - close)"])
```

**真实数据实测结论（101 只美股 / 2021–2026 / 5 年，14 条价量种子）**
- 全部因子 **|IC| < 0.02、ICIR < 0.07、多空夏普多为负** → 价量因子在这批大盘股上**无横截面信号**
- 印证方法论修正：本地预筛只能覆盖价量（红海）；**真护城河在分析师/AI/财报/情绪数据集**
- 因此扫描阶段主线是 `run_scan.py --datasets analyst7`（蓝海），价量（pv1）放最后
- 复现：`python parse_westock.py`（需 westock 落盘 JSON）→ `python local_screen.py`

---

## 门槛速查

| 指标 | 要求 |
|---|---|
| Sharpe | > 1.25 |
| Fitness | > 1.0 （= Sharpe × sqrt(\|Returns\| / max(Turnover, 0.125))） |
| Turnover | 1% – 70% |
| 自相关 | < 0.7（若夏普比历史相似 alpha 高 10%+，即 >1.375，可豁免） |
| 单股权重 | < 10% |

`gate_check()` 会自动判定，失败时 `gate_reason()` 直接告诉你卡在哪一项。

> ✅ **链路已打通（2026-08-30）**：认证 → 提交 → 轮询 → 完成 → 指标，端到端验证通过。
> 实测 `-rank(returns)`：Sharpe 1.78 / Fitness 0.76 / 换手 84.6%（换手拖垮 fitness）。
> **关键修正**：`simulations` 完成响应不含指标，`alpha` 字段才是真 alpha id，须二次 `GET /alphas/{id}`（含官方 15 项 checks 清单：LOW_SHARPE / LOW_FITNESS / HIGH_TURNOVER / LOW_SUB_UNIVERSE_SHARPE / CLUSTER_TEST / SELF_CORRELATION / DATA_DIVERSITY / PROD_CORRELATION / LOW_2Y_SHARPE / MATCHES_PYRAMID 等）。
> ⏸️ **当前状态**：按用户要求暂停批量研发，进入「方法论 + 专家团化设计规划」阶段，见 `plans/01-方法论与专家团化设计规划.html`。

---

## 本地数据池与回测流水线（2026-08-30 新增）

| 文件 | 作用 |
|---|---|
| `data/sp500_tickers.txt` | S&P500 成分列表（两源合并去重，329 只，当前真实市值序） |
| `build_panel.py` | 合并全部 westock dump → `data/us_panel.pkl`（**478 只 × 5 年日线**，中位 1255 交易日） |
| `batch_backtest.py` | 价量因子批量回测流水线：14 种子 + 12 模板 × 7 字段 × 5/20 窗口 = **158 条因子**，输出 IC/ICIR/t/换手/**自相关(lag-1)**/分层多空 → CSV+HTML+**SQLite 落库** |
| `backtest_store.py` | **SQLite 持久化层**（`data/wqbrain.db`）：`local_backtests`（本地预筛）/ `platform_backtests`（平台 PASS）/ `failed_pool`（失败池，含原因，可归档）——净化机制的结构化证据底座；run_seeds/run_scan 已接入（PASS→平台表，FAIL→失败池） |
| `rules.yaml` + `rules_update.py` | 方法论规则库 v1.0（12 条原子规则 × 5 元数据）+ 置信度自动更新器（support/refute/review/stale-check/new/reestimate） |

**纯本地闭环实证结论（478 只 S&P500 × 5 年，不烧额度）**：
- 158 条价量因子 **|ICIR|≥0.25 为 0 条**，|IC| 全部 <0.025 → 价量因子在 S&P500 大票池**无横截面信号**（101 只样本扩大 4.7 倍后结论不变）
- **自相关结构性淘汰**：82/158（52%）因子自相关 ≥0.9（慢变量如 ts_mean 偏离、250 日动量，平台必拒）；仅 50/158（32%）<0.7 达标
- **换手**：113/158（72%）落在 BRAIN 1%–70% 区间
- **战略含义**：本地流水线 10 分钟判死 158 个想法（平台需约 5 小时）——价值在于**快速证伪**；要出 alpha 必须走平台字段数据（分析师/AI/情绪，D 路径）

---

## 自测状态

```
解释器          9/9 通过
解析器回归      6/6 通过
注入信号检出    PASS（反转 IC=+0.0437 / 动量 IC=-0.0437，量级接近真实因子）
模板生成        4 字段 → 92 条候选
扫描器离线估算  正常
```

运行 `python test_engine.py` 可复现。