# quant-research

**Repository Path**: ereflect/quant-research

## Basic Information

- **Project Name**: quant-research
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quant Learning Workspace

这个项目已经拆成三条清晰路径：

- `learning/`：基础知识学习入口
- `examples/`：轻量、单主题、可快速运行的示例
- `practice/100-factor-mining/`：完整实战，目标是统一挖掘和评估 110 个候选因子

项目内提供一个 workspace skill：`/quant-learning-practice`。

- 用于基础知识学习、学习路径规划、概念讲解
- 用于因子挖掘实战、CSV 切换、shortlist 解释和结果复盘

后续待办见 `TODO.md`。

工程协作和仓库规则见 `CONTRIBUTING.md` 与 `PRINCIPLES.md`。

项目目标：

- 用 Markdown 管理量化基础知识与研究方法
- 用 Python 提供可解释、可复现的量化研究骨架
- 用自包含数据先跑通全流程，同时保留真实 CSV 接入口
- 把“学概念”“跑示例”“做完整因子挖掘任务”分离开，避免内容混排

## 目录结构

```text
quant/
├── README.md
├── learning/
│   └── README.md
├── examples/
│   ├── README.md
│   ├── 01_generate_synthetic_data.py
│   ├── 02_reversal_alpha.py
│   ├── 03_momentum_alpha.py
│   ├── 04_group_neutralization.py
│   ├── 05_mini_backtest.py
│   ├── 06_advanced_alpha_templates.py
│   ├── 07_parameter_sweep.py
│   ├── 08_alpha_ensemble.py
│   └── 09_csv_market_pipeline.py
├── practice/
│   └── 100-factor-mining/
│       ├── README.md
│       ├── PLAYBOOK.md
│       ├── run_factor_mining.py
│       ├── configs/
│       └── runs/
├── src/
│   └── quant_foundations/
│       ├── operators.py
│       ├── alphas.py
│       ├── research.py
│       ├── registry.py
│       ├── pipeline.py
│       ├── reporting.py
│       └── factors/
├── docs/
│   └── README.md
└── data/
    └── generated/
```

## 快速开始

```bash
cd ~/quant
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## 你现在可以怎么用

### 1. 学基础

从 `learning/README.md` 开始。这个入口会把你带到当前已有的基础知识、WorldQuant 风格表达式和研究方法文档。

### 2. 跑小示例

```bash
cd ~/quant
.venv/bin/python examples/01_generate_synthetic_data.py
.venv/bin/python examples/05_mini_backtest.py
.venv/bin/python examples/07_parameter_sweep.py
.venv/bin/python examples/08_alpha_ensemble.py
```

### 3. 做完整实战

```bash
cd ~/quant
.venv/bin/python practice/100-factor-mining/run_factor_mining.py \
    --config practice/100-factor-mining/configs/synthetic-default.json
```

### 4. 随机拿一个因子发掘主题

```bash
cd ~/quant
.venv/bin/python practice/100-factor-mining/push_factor_theme.py --seed 7
```

默认会使用库内置主题池，并自动合并 `practice/100-factor-mining/configs/factor-theme-pool.json` 里的扩展主题。

## 当前核心能力

- 统一的 `MarketPanel` 数据结构
- 合成多资产 OHLCV 数据与 long-format CSV 加载
- WorldQuant 风格基础算子与高级算子
- 11 个因子家族、110 个候选因子注册与批量运行
- 批量评估、回测摘要、相关性筛选、shortlist 构建
- 参数扫描和 Markdown / CSV 结果输出
- 随机因子主题推送，用来给下一轮候选因子发掘提供切入点

## 工程规则

- Git workflow、分支命名、提交规范和 review checklist 见 `CONTRIBUTING.md`
- 工程原则总览见 `PRINCIPLES.md`
- 详细工程原则见 `docs/engineering-principles.md`

## CSV 输入格式

真实 CSV 目前使用 long-format 结构，基础 OHLCV 形状如下：

```text
date,asset,open,high,low,close,volume,group
2024-01-02,AAPL,187.15,188.44,183.89,185.64,82488700,Tech
2024-01-02,MSFT,372.23,373.55,366.50,370.87,25258600,Tech
```

- `group` 可选，不提供时自动填成 `UNGROUPED`
- 同一个 `(date, asset)` 只保留最后一条记录
- 额外的数值列会自动加载到 `panel.features`
- 当前 `climate` 家族使用的可选列为 `carbon_intensity`、`green_revenue_share`、`climate_sentiment`、`physical_risk_score`、`temperature_anomaly`
- 如果 CSV 不包含这些 climate 列，CSV 模式会自动跳过 `climate` 家族，其余家族照常运行
- `practice/100-factor-mining/run_factor_mining.py` 可以直接切到 CSV 模式复用同一研究流水线

## 项目定位

- `learning/` 解决“先把基础知识学清楚”
- `examples/` 解决“先把一个概念跑通”
- `practice/100-factor-mining/` 解决“把候选因子系统化挖掘、评估、筛选并形成结论”