因子 - 快速开始

jh_quant.factors 是多因子模型计算框架，支持 11 种主流学术因子模型的因子收益率计算、个股暴露度估计和统计验证。

核心特性

11 种因子模型：CAPM、FF3、FF5、Carhart、Novy-Marx、Hou-Xue-Zhang、DHS、CH3、SY4、Reversal、Low Vol
两种计算方法：SIMPLE（简化版，等权 + 中位数分组）和 CLASSIC（经典版，市值加权 + 分位数分组）
日频/月频：支持月度和日度因子计算
高性能：支持 Polars 加速 + joblib 多进程并行
暴露度估计：OLS 回归计算个股在因子上的 Beta 暴露
因子验证：截距项 t 检验 + Fama-MacBeth 两步回归

核心入口

入口	适用场景
`calculate_factor_returns()`	最简洁，一次性计算因子收益率
`FactorEngine`	需要复用实例、批量计算多个模型
`GeneralFactorCalculator`	已有股票收益率和基本面数据

数据准备

因子核心不直接拉取 Tushare 或 AkShare 数据，需要先准备符合 schema 的 DataFrame。最简单的 TS 数据准备方式是使用 load_ts_factor_inputs()：

from jh_quant.factors import calculate_factor_returns, load_ts_factor_inputs

inputs = load_ts_factor_inputs(
    start_date="2020-01-01",
    end_date="2024-12-31",
    period="M",             # 默认直接使用 TS_MONTHLY_* 月频行情
    price_adjust="qfq",     # 默认使用前复权价格
    lag_features=True,      # 默认将特征滞后一收益期，避免同月 look-ahead
)

返回值可以直接传给 calculate_factor_returns()：

factor_returns = calculate_factor_returns("ff3", **inputs)

注意：symbols 参数可省略，省略时加载全部 A 股（请求省略 ts_code，服务端返回全市场）。如需限定股票范围，传入 ts_codes 列表即可，如 symbols=['000001.SZ', '600000.SH']。

月频（period="M"）时，市值、PB 等基本面数据直接使用月度衍生表 TS_MONTHLY_BASIC（每只股票每月取当月最后一个交易日，约日线数据量的 1/20），无需拉取全量日线 TS_DAILY_BASIC 再本地降频，能显著减少内存与耗时。该表不可用时自动回退日线降频。更多参数见 DataTypes 说明。

方式一：便捷函数（推荐入门）

from jh_quant.factors import calculate_factor_returns, load_ts_factor_inputs

inputs = load_ts_factor_inputs(
    start_date="2020-01-01",
    end_date="2024-12-31",
)
ff3 = calculate_factor_returns("ff3", **inputs, method="simple")
print(ff3.head())

输出为一个 DataFrame，index 为 date，columns 为因子名（如 mkt、smb、hml）：

              mkt       smb       hml
date
2020-01-31  0.0123   -0.0045    0.0087
2020-02-29 -0.0056    0.0023   -0.0012
...

一次性计算所有因子模型：

all_factors = calculate_factor_returns("all", **inputs)
# 返回 Dict[FactorType, DataFrame]

for name, df in all_factors.items():
    print(f"{name}: {len(df)} 行, 因子: {list(df.columns)}")

方式二：FactorEngine（推荐进阶）

from jh_quant.factors import FactorEngine, FactorType, CalculationMethod, TimePeriod

engine = FactorEngine()

ff5 = engine.calculate_factor_returns(
    factor_type=FactorType.FF5,
    method=CalculationMethod.CLASSIC,
    n_jobs=4,
    use_polars=True,
    **inputs,
)

# 批量计算
results = engine.calculate_all_factors(
    factor_types=[FactorType.FF3, FactorType.CARHART, FactorType.DHS],
    method=CalculationMethod.SIMPLE,
    period=TimePeriod.MONTHLY,
    **inputs,
)

for ft, df in results.items():
    print(f"{ft.value}: {df.shape}")

方式三：暴露度估计

from jh_quant.factors import calculate_exposures

# 给定已计算好的因子收益率和个股收益率，计算个股暴露
exposures = calculate_exposures(
    stock_returns=my_stock_returns,   # 包含 symbol, date, return
    factor_returns=ff3,               # FactorEngine 的输出
    period='M',
)

参数速查

load_ts_factor_inputs 参数

参数	默认值	说明
`symbols`	`None`	股票范围。省略或传空列表时加载全部 A 股（请求省略 `ts_code`）；传 ts_codes 列表则限定范围，如 `['000001.SZ', '600000.SH']`
`period`	`"M"`	`"M"` 使用 TS 月频行情 `TS_MONTHLY_*`，基本面优先用 `TS_MONTHLY_BASIC`（不可用时回退 `TS_DAILY_BASIC` 本地降频）；`"D"` 使用日频行情转月末收益，基本面用 `TS_DAILY_BASIC`
`price_adjust`	`"qfq"`	优先使用前复权价格；可选 `"hfq"` 或 `"none"`
`lag_features`	`True`	将市值、BM、动量等特征滞后一收益期，避免同月 look-ahead
`include_proxy_fundamentals`	`False`	仅用于 smoke test 的代理财务字段，不建议用于正式研究

FactorType

字符串	FactorType	因子组成
`'capm'`	`CAPM`	mkt
`'ff3'`	`FF3`	mkt, smb, hml
`'ff5'`	`FF5`	mkt, smb, hml, rmw, cma
`'carhart'`	`CARHART`	mkt, smb, hml, umd
`'novy_marx'`	`NOVY_MARX`	mkt, hml_adj, umd, gp_a
`'hou_xue_zhang'`	`HOU_XUE_ZHANG`	mkt, me, ia, roe
`'dhs'`	`DHS`	mkt, pead, fin
`'ch3'`	`CH3`	mkt, smb, vmg
`'sy4'`	`SY4`	mkt, smb, mgmt, perf
`'reversal'`	`REVERSAL`	mkt, smb, rev
`'low_vol'`	`LOW_VOL`	mkt, smb, ivol
`'all'`	所有以上模型	—

TimePeriod

值	说明
`'M'` / `TimePeriod.MONTHLY`	月度因子
`'D'` / `TimePeriod.DAILY`	日度因子

CalculationMethod

值	说明
`'simple'`（默认）	简化方法，等权+中位数分组
`'classic'`	经典方法，市值加权+分位数分组