qlfactor 0.1.0

A 股因子研究工具：Tushare 日线数据下载与因子分析引擎（IC、分组收益、换手率、成本扣减、HTML 报告）

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. 项目结构

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）：

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

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

3.3 配置环境变量

在项目根目录创建 .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：合并为总表

推荐顺序：

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.。

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

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

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

示例（项目内置）：

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

然后调用：

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

在项目根目录运行测试：

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