Metadata-Version: 2.4
Name: qlfactor
Version: 0.1.0
Summary: A 股因子研究工具：Tushare 日线数据下载与因子分析引擎（IC、分组收益、换手率、成本扣减、HTML 报告）
Author-email: joshuaxql <qiuleiustc@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/joshuaxql/qlfactor
Project-URL: Issues, https://github.com/joshuaxql/qlfactor/issues
Keywords: quant,factor,a-shares,tushare,backtest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: pyecharts>=2.1.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: scipy>=1.17.1
Requires-Dist: tqdm>=4.66
Requires-Dist: tushare>=1.4.29
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# qlfactor

一个基于 A 股日线数据的因子研究项目，包含两条主线：

- 数据下载与整理：通过 Tushare 拉取交易日历、股票基础信息、日线行情并落地为 Parquet。
- 因子分析引擎：完成因子分组收益、IC 分析、换手率分析、交易成本扣减与多空净值分析。

## 1. 当前能力

### 1.1 数据侧

- 下载交易日历（SSE 开市日）
- 下载两市股票基础信息（上市/退市/暂停）
- 下载单只股票日线、复权因子、日线估值与换手指标
- 合并历史证券简称（namechange）
- 合并所有个股文件为总表 stocks_daily.parquet

### 1.2 因子分析侧

- 去极值：3sigma、MAD
- 标准化：截面 Z-Score
- 远期收益计算与分位分组
- IC、IC 累加、IC 分布、T 检验
- 分组收益、多空组合收益
- 分组换手率、因子整体换手率
- 换手率分位统计（P25/P50/P75）
- 换手率与收益相关性
- 按换手率扣交易成本后的净收益分析
- 输出 HTML 可视化报告

## 2. 项目结构

```text
qlfactor/
├─ data/
│  ├─ stocks_daily/
│  └─ stocks_data.duckdb
├─ output/
│  └─ 因子分析报告.html
├─ src/
│  ├─ __init__.py
│  ├─ config.py
│  ├─ download.py
│  └─ factor_engine.py
├─ pyproject.toml
├─ requirement.md
├─ README.md
└─ API.md
```

## 3. 环境准备

### 3.1 Python 版本

- 建议 Python 3.12+

### 3.2 安装依赖

项目使用 pyproject 管理依赖，建议使用 uv 或 pip。

示例（pip）：

```bash
pip install -U pyarrow pyecharts python-dotenv scipy tushare tqdm
```

说明：当前代码实际使用了 tqdm，请确保环境中已安装。

### 3.3 配置环境变量

在项目根目录创建 .env：

```env
TUSHARE_TOKEN=你的tushare_token
DB_NAME=./data/
```

含义：

- TUSHARE_TOKEN：Tushare Pro Token
- DB_NAME：数据目录（默认 ./data/）

## 4. 数据下载流程

入口文件：src/download.py

Download 类提供 4 个步骤：

1. calendar：下载交易日历
2. stocks_info：下载股票基础信息
3. stocks_daily：逐股票下载日线与扩展指标
4. merge：合并为总表

推荐顺序：

```python
from config import pro, db_path
from download import Download

d = Download(pro, db_path)
d.calendar()
d.stocks_info()
d.stocks_daily()
d.merge()
```

## 5. 因子分析流程

入口文件：src/factor_engine.py

你需要定义一个继承 Factor 的子类，并实现 caculate 方法返回 MultiIndex(date, symbol) 的因子值 Series。

### 5.1 公式写法（推荐）

`Factor` 已内置常用字段别名与公式函数，可直接用 `FORMULA("MA(CLOSE, 20)")` 风格，不必在表达式里写 `self.`。

```python
class my_factor(Factor):
    def caculate(self):
        return self.FORMULA("MA(CLOSE, 20) / CLOSE - 1")
```

如果不想写字符串，也可先绑定后调用：

```python
class my_factor(Factor):
    def caculate(self):
        MA, CLOSE = self.BIND("MA", "CLOSE")
        return MA(CLOSE, 20) / CLOSE - 1
```

示例（项目内置）：

```python
class ma(Factor):
	def caculate(self):
		return (
			self.data["turnover_rate"]
			.groupby(level="symbol")
			.transform(lambda x: x.rolling(20).mean() / x)
		)
```

然后调用：

```python
ma_factor.create_factor_analysis_report(
	winsorize="3sigma",
	standardize=True,
	transaction_cost_bps=10,
)
```

### 5.2 已内置字段（大写）

- OPEN, HIGH, LOW, CLOSE
- PRE_CLOSE, CHANGE, PCT_CHG
- VOLUME, AMOUNT, ADJ_FACTOR
- TURNOVER_RATE, TURNOVER_RATE_F, VOLUME_RATIO
- PE, PE_TTM, PB, PS, PS_TTM
- DV_RATIO, DV_TTM
- TOTAL_SHARE, FLOAT_SHARE, FREE_SHARE
- TOTAL_MV, CIRC_MV

### 5.3 已内置公式函数

- 基础：MA, EMA, RANK, REF, DELTA, STD, SUM
- 通达信风格：ABS, MAX, MIN, IF, COUNT, EVERY, EXIST, HHV, LLV, TSRANK, SMA, CROSS
- 数学：LOG, EXP, SQRT

## 6. 关键参数说明

- quantiles：分组数，默认 5
- period：远期收益周期（天），默认 1
- winsorize：去极值方式，可选 3sigma 或 mad
- winsorize_param：去极值参数
- standardize：是否做截面 Z-Score
- transaction_cost_bps：单边交易成本（bps）

### 6.1 单边 10bps 是什么

- 1 bps = 0.01% = 0.0001
- 10 bps = 0.10% = 0.001
- 单边表示一次交易动作（买入或卖出）收一次成本

在本项目里，transaction_cost_bps=10 表示：

- 分组净收益 = 分组毛收益 - 分组换手率 × 0.001
- 多空净收益 = 多空毛收益 - (多头换手率 + 空头换手率) × 0.001

## 7. 输出结果

### 7.1 控制台输出

- 分组绩效指标
- 多空组合指标
- IC 统计与 T 检验
- 分组换手率统计（含分位数）
- 因子换手率统计（含分位数）
- 换手率与收益相关系数
- 扣成本后的分组净绩效、多空净绩效

### 7.2 报告文件

- output/因子分析报告.html

报告包含累计收益、IC 图、换手率图、相关性图、毛净收益对比图等。

## 8. API 文档

完整函数文档见：API.md

## 9. 注意事项

- Tushare 接口有频率和积分限制，批量下载时建议分批执行。
- 首次全量下载耗时较长，建议先缩小时间区间调试。
- stocks_daily 下载过程可能因网络抖动失败，代码内已做重试。
- 因子计算请保证索引与价格数据严格对齐（date, symbol）。

## 10. 日志与测试

- `src/config.py` 导入时会初始化日志到仓库根目录 `debug.log`。
- 因子计算链路（公式执行、预处理、报告生成）已增加日志打点，异常会记录 traceback，便于定位。
- 公式函数测试文件：`tests/test_formula_functions.py`

在项目根目录运行测试：

```bash
.\.venv\Scripts\python -m unittest tests/test_formula_functions.py
```
