Files
ProStock/docs/factor_implementation_analysis.md
liaozhaorun 62a4635a71 feat: 新增因子装饰器系统和完整因子文档
- 添加因子表达式文档,收录180+个因子及数学表达式
- 添加因子实现分析报告,明确ts_*与cs_*算子分类
- 实现装饰器系统:@time_series/@cross_section/@element_wise
- 优化API和翻译器以支持新架构
2026-03-06 23:59:39 +08:00

22 KiB
Raw Blame History

因子表达式可实现性分析报告 (v2)

文档来源

  • 分析文件: docs/factor_expressions_document.md
  • 分析日期: 2026-03-06
  • 共收录因子: 180+ 个
  • 更新说明: 本版本明确区分 ts_* (时间序列) 和 cs_* (截面) 算子类型

一、当前 DSL 框架已实现功能

1.1 时间序列函数 (ts_*)

说明: 所有时间序列函数都按 ts_code 分组计算,防止跨股票数据泄露

函数名 参数 状态 说明 Polars 实现
ts_mean(x, window) x: 表达式, window: 窗口 已实现 滚动均值 rolling_mean(window).over("ts_code")
ts_sum(x, window) x: 表达式, window: 窗口 已实现 滚动求和 rolling_sum(window).over("ts_code")
ts_std(x, window) x: 表达式, window: 窗口 已实现 滚动标准差 rolling_std(window).over("ts_code")
ts_max(x, window) x: 表达式, window: 窗口 已实现 滚动最大值 rolling_max(window).over("ts_code")
ts_min(x, window) x: 表达式, window: 窗口 已实现 滚动最小值 rolling_min(window).over("ts_code")
ts_delay(x, periods) x: 表达式, periods: 滞后 已实现 滞后 N 期 shift(periods).over("ts_code")
ts_delta(x, periods) x: 表达式, periods: 差分 已实现 差分 N 期 (x - x.shift(periods)).over("ts_code")
ts_corr(x, y, window) x, y: 表达式, window: 窗口 已实现 滚动相关系数 rolling_corr(y, window).over("ts_code")
ts_cov(x, y, window) x, y: 表达式, window: 窗口 已实现 滚动协方差 rolling_cov(y, window).over("ts_code")
ts_rank(x, window) x: 表达式, window: 窗口 API 已定义 滚动排名 待实现

1.2 截面函数 (cs_*)

说明: 所有截面函数都按 trade_date 分组计算,防止跨日期数据泄露

函数名 参数 状态 说明 Polars 实现
cs_rank(x) x: 表达式 已实现 截面排名 (归一化到 [0,1]) (rank() / count()).over("trade_date")
cs_zscore(x) x: 表达式 已实现 Z-Score 标准化 ((x - mean()) / std()).over("trade_date")
cs_neutralize(x, group?) x: 表达式, group?: 分组列 已实现 行业/市值中性化 (x - mean()).over("trade_date")
cs_winsorize(x, lower, upper) x: 表达式, lower/upper: 分位数 API 已定义 缩尾处理 待实现
cs_demean(x) x: 表达式 API 已定义 去均值 待实现
cs_std(x) x: 表达式 缺失 截面标准差 待实现
cs_mean(x) x: 表达式 缺失 截面均值 待实现
cs_sum(x) x: 表达式 缺失 截面求和 待实现
cs_max(x) x: 表达式 缺失 截面最大值 待实现
cs_min(x) x: 表达式 缺失 截面最小值 待实现

1.3 数学函数(无分组,逐元素计算)

函数名 参数 状态 说明
log(x) x: 表达式 API 已定义 自然对数
log1p(x) x: 表达式 缺失 log(1+x)
exp(x) x: 表达式 API 已定义 指数函数
sqrt(x) x: 表达式 API 已定义 平方根
sign(x) x: 表达式 API 已定义 符号函数 (-1/0/1)
abs(x) x: 表达式 API 已定义 绝对值
max_(x, y) x, y: 表达式 API 已定义 逐元素最大值
min_(x, y) x, y: 表达式 API 已定义 逐元素最小值
clip(x, lower, upper) x: 表达式, lower/upper: 边界 API 已定义 数值裁剪
atan(x) x: 表达式 缺失 反正切函数

1.4 统计函数(需要新增)

函数名 类型 参数 说明
ts_var(x, window) ts x: 表达式, window: 窗口 滚动方差
ts_skew(x, window) ts x: 表达式, window: 窗口 滚动偏度
ts_kurt(x, window) ts x: 表达式, window: 窗口 滚动峰度
ts_pct_change(x, periods) ts x: 表达式, periods: 周期 百分比变化
ts_ema(x, window) ts x: 表达式, window: 窗口 指数移动平均
ts_sma(x, window) ts x: 表达式, window: 窗口 简单移动平均 (ts_mean 别名)

1.5 TA-Lib 技术指标(用户可安装 TA-Lib

函数名 类型 参数 说明 优先级
ts_atr(high, low, close, window) ts high/low/close: 表达式, window: 窗口 真实波动幅度
ts_obv(close, vol) ts close/vol: 表达式 能量潮指标
ts_rsi(close, window) ts close: 表达式, window: 窗口 相对强弱指数
ts_natr(high, low, close, window) ts high/low/close: 表达式, window: 窗口 归一化 ATR

说明: 由于用户已确认可安装 TA-Lib建议直接使用 ta-lib Python 包,并通过 adapter 模式封装到 DSL 中。

1.6 条件函数

函数名 参数 状态 说明
if_(condition, true_val, false_val) condition: 布尔表达式 API 已定义 条件选择
where(condition, true_val, false_val) 同上 API 已定义 if_ 的别名

1.7 符号/数据字段

字段名 状态 数据来源 所属类别
close 可用 daily/pro_bar 表 价格
open 可用 daily/pro_bar 表 价格
high 可用 daily/pro_bar 表 价格
low 可用 daily/pro_bar 表 价格
vol 可用 daily/pro_bar 表 成交量
amount 可用 daily/pro_bar 表 成交额
pre_close 可用 daily/pro_bar 表 价格
change 可用 daily/pro_bar 表 价格变化
pct_chg 可用 daily/pro_bar 表 涨跌幅
turnover_rate 可用 daily/pro_bar 表 换手率
volume_ratio 可用 daily/pro_bar 表 量比

1.8 支持的运算符

算术运算符: +, -, *, /, **, //, % 比较运算符: ==, !=, <, <=, >, >= 一元运算符: -, +, abs()


二、需要新增的数据表

2.1 筹码分布数据cyq 表)

数据来源: Tushare cyq API (VIP) 数据频率: 日频 同步方式: 按股票

字段名 类型 说明 依赖因子数
cost_5pct DOUBLE 5% 成本价 ~50个
cost_15pct DOUBLE 15% 成本价 ~50个
cost_50pct DOUBLE 50% 成本价 (中位数) ~50个
cost_85pct DOUBLE 85% 成本价 ~50个
cost_95pct DOUBLE 95% 成本价 ~50个
weight_avg DOUBLE 加权平均成本 ~50个
winner_rate DOUBLE 获利盘比例 ~50个
his_high DOUBLE 历史最高价 ~10个
his_low DOUBLE 历史最低价 ~10个

依赖筹码数据的主要因子:

  • cashflow_to_ev_factor
  • chip_concentration_range
  • profit_pressure
  • underwater_resistance
  • vol_amp_loss_20
  • smallcap_concentration
  • cat_golden_resonance
  • ...等 50+ 个

2.2 资金流向数据moneyflow 表)

数据来源: Tushare moneyflow API (VIP) 数据频率: 日频 同步方式: 按股票

字段名 类型 说明 依赖因子数
buy_sm_vol DOUBLE 小单买入量 ~30个
sell_sm_vol DOUBLE 小单卖出量 ~30个
buy_lg_vol DOUBLE 大单买入量 ~30个
sell_lg_vol DOUBLE 大单卖出量 ~30个
buy_elg_vol DOUBLE 特大单买入量 ~30个
sell_elg_vol DOUBLE 特大单卖出量 ~30个
net_mf_vol DOUBLE 净流入量 ~20个

依赖资金流向数据的主要因子:

  • lg_elg_net_buy_vol
  • flow_lg_elg_intensity
  • sm_net_buy_vol
  • flow_divergence_ratio
  • lg_flow_mom_corr_20_60
  • cs_rank_net_lg_flow_val
  • ...等 30+ 个

2.3 财务数据financial 表)

数据来源: Tushare income/balance_sheet/cashflow API (VIP) 数据频率: 季度 同步方式: 按股票,需 asof_backward join

字段名 类型 说明 数据来源表
bps DOUBLE 每股净资产 income
total_liab DOUBLE 总负债 balance_sheet
money_cap DOUBLE 货币资金 balance_sheet
n_cashflow_act DOUBLE 经营活动现金流净额 cashflow
undist_profit_ps DOUBLE 每股未分配利润 income
ocfps DOUBLE 每股经营现金流 income
roa DOUBLE 资产回报率 income
roe DOUBLE 净资产收益率 income
total_mv DOUBLE 总市值 daily_basic
circ_mv DOUBLE 流通市值 daily_basic

依赖财务数据的主要因子:

  • undist_profit_ps
  • cashflow_to_ev_factor
  • book_to_price_ratio
  • cs_rank_size

2.4 行业分类数据

字段名 类型 说明 数据来源
cat_l2_code VARCHAR 二级行业分类代码 stock_basic

用途: daily_industry_deviation, cs_rank_ind_adj_lg_flow 等分组计算


三、因子表达式可实现性分类

3.1 完全可实现(使用现有功能)

技术指标因子

因子名称 表达式 复杂度
turnover_rate_mean_5 ts_mean(turnover_rate, 5)
bbi_ratio_factor (ts_mean(close,3)+ts_mean(close,6)+ts_mean(close,12)+ts_mean(close,24))/4/close

ARBR 因子

因子名称 表达式 复杂度
AR ts_sum(high - open, N) / ts_sum(open - low, N) * 100
BR ts_sum(max_(0, high - ts_delay(close,1)), N) / ts_sum(max_(0, ts_delay(close,1) - low), N) * 100
AR_BR AR - BR

成交量因子

因子名称 表达式 复杂度
volume_change_rate ts_mean(vol, 2) / ts_mean(vol, 10) - 1
turnover_deviation (turnover_rate - ts_mean(turnover_rate, 3)) / ts_std(turnover_rate, 3)
vol_std_5 ts_std(ts_delta(vol), 5)

收益率因子

因子名称 表达式 复杂度
return_5 close / ts_delay(close, 5) - 1
return_20 close / ts_delay(close, 20) - 1
std_return_5 ts_std(ts_delta(close)/ts_delay(close), 5)
std_return_90 ts_std(ts_delta(close)/ts_delay(close), 90)

截面排序因子

因子名称 表达式 复杂度
cs_rank_volume_ratio cs_rank(volume_ratio)
cs_rank_turnover_rate cs_rank(turnover_rate)

3.2 需要新增 ts_* 函数

因子名称 所需函数 表达式示例 优先级
variance_20 ts_var(x, window) ts_var(pct_chg, 20)
return_skew ts_skew(x, window) ts_skew(pct_chg, 5)
return_kurtosis ts_kurt(x, window) ts_kurt(pct_chg, 5)
turnover_diff_skew_20 ts_skew(x, window) ts_skew(ts_delta(turnover_rate), 20)
act_factor1 ts_ema(x, window) atan((ts_ema(close,5)/ts_delay(ts_ema(close,5),1)-1)*100) * 57.3 / 50
act_factor2 ts_ema(x, window) atan((ts_ema(close,13)/ts_delay(ts_ema(close,13),1)-1)*100) * 57.3 / 40
act_factor3 ts_ema(x, window) atan((ts_ema(close,20)/ts_delay(ts_ema(close,20),1)-1)*100) * 57.3 / 21
act_factor4 ts_ema(x, window) atan((ts_ema(close,60)/ts_delay(ts_ema(close,60),1)-1)*100) * 57.3 / 10
atr_14 ts_atr(h,l,c,w) ts_atr(high, low, close, 14)
atr_6 ts_atr(h,l,c,w) ts_atr(high, low, close, 6)
rsi_3 ts_rsi(x, window) ts_rsi(close, 3)
obv ts_obv(c, v) ts_obv(close, vol)
maobv_6 ts_obv + ts_mean ts_mean(ts_obv(close, vol), 6)

3.3 需要新增 cs_* 函数

因子名称 所需函数 表达式示例 优先级
daily_positive_benchmark cs_mean(x) cs_mean(pct_chg[pct_chg > 0])
daily_industry_positive_benchmark cs_mean(x) by group cs_mean(pct_chg) by cat_l2_code
industry_avg_flow cs_mean(x) by group cs_mean(net_lg_flow_vol) by trade_date, cat_l2_code

注意: 这些因子需要 分组聚合 能力,可能需要扩展 DSL 语法支持 by 子句,或通过 cs_neutralize 的 group 参数实现。

3.4 需要新增数据表

依赖筹码数据cyq 表)的因子

因子名称 表达式 复杂度
chip_concentration_range (cost_95pct - cost_5pct) / (close + epsilon)
chip_skewness (weight_avg - cost_50pct) / (cost_50pct + epsilon)
profit_pressure winner_rate * 0.5 * ((close/cost_85pct-1) + (close/cost_95pct-1))
underwater_resistance (1-winner_rate) * max_(0, cost_15pct-close) / (close+epsilon)
smallcap_concentration (1 / log(circ_mv)) * (cost_85pct - cost_15pct)

依赖资金流向数据moneyflow 表)的因子

因子名称 表达式 复杂度
lg_elg_net_buy_vol (buy_lg_vol + buy_elg_vol - sell_lg_vol - sell_elg_vol)
flow_lg_elg_intensity lg_elg_net_buy_vol / (vol + epsilon)
cs_rank_net_lg_flow_val cs_rank(lg_elg_net_buy_vol * close)

依赖财务数据的因子

因子名称 表达式 复杂度 特殊需求
book_to_price_ratio bps / close 需 asof_backward join
cashflow_to_ev_factor n_cashflow_act / (total_mv*10000 + total_liab - money_cap) 需多表 join

3.5 需要复杂条件逻辑

因子名称 逻辑 实现方式
daily_deviation 按条件选择不同基准 if_(pct_chg > 0, pct_chg - pos_benchmark, if_(pct_chg < 0, pct_chg - neg_benchmark, 0))
cat_volume_breakout 布尔分类 if_(vol > ts_max(vol, 5), 1, 0)
cat_turnover_spike 阈值分类 if_(turnover_rate > ts_mean(turnover_rate,3) + 2*ts_std(turnover_rate,3), 1, 0)
cat_golden_resonance 多条件组合 (close > weight_avg) & (volume_ratio > 1.5) & (winner_rate > 0.7)

四、实施计划(按优先级排序)

Phase 1: 核心 ts_* 函数Week 1-2

目标: 实现最常用的 30+ 个因子

# 1. 新增数学函数(逐元素,无分组)
def atan(x): ...
def log1p(x): ...

# 2. 新增统计函数ts_*,按 ts_code 分组)
def ts_var(x, window): ...      # 滚动方差
def ts_skew(x, window): ...     # 滚动偏度
def ts_kurt(x, window): ...     # 滚动峰度
def ts_pct_change(x, periods): ...  # 百分比变化

# 3. 新增 EMAts_*,使用 Polars ewm_mean
def ts_ema(x, window):
    # 使用 Polars: pl.col(x).ewm_mean(span=window).over("ts_code")
    pass

# 4. 实现 ATR基于现有函数组合
def ts_atr(high, low, close, window):
    tr1 = high - low
    tr2 = abs(high - ts_delay(close, 1))
    tr3 = abs(low - ts_delay(close, 1))
    tr = max_(tr1, max_(tr2, tr3))
    return ts_mean(tr, window)

完成后可实现的因子:

  • variance_20
  • return_skew, return_kurtosis
  • turnover_diff_skew_20
  • act_factor1-4
  • atr_14, atr_6
  • vol_adj_roc_20

Phase 2: TA-Lib 集成Week 3

目标: 支持 RSI、OBV 等复杂技术指标

# 安装 TA-Lib
# pip install TA-Lib

# 封装为 ts_* 函数
def ts_rsi(close, window):
    # 使用 talib.RSI并添加 .over("ts_code")
    pass

def ts_obv(close, vol):
    # 使用 talib.OBV并添加 .over("ts_code")
    pass

完成后可实现的因子:

  • rsi_3
  • obv
  • maobv_6

Phase 3: 筹码分布数据同步Week 4

目标: 实现 cyq 表同步,支持 50+ 个筹码相关因子

class CyqSync(StockBasedSync):
    table_name = "cyq"
    TABLE_SCHEMA = {
        "ts_code": "VARCHAR(16) NOT NULL",
        "trade_date": "DATE NOT NULL",
        "cost_5pct": "DOUBLE",
        "cost_15pct": "DOUBLE",
        "cost_50pct": "DOUBLE",
        "cost_85pct": "DOUBLE",
        "cost_95pct": "DOUBLE",
        "weight_avg": "DOUBLE",
        "winner_rate": "DOUBLE",
        "his_high": "DOUBLE",
        "his_low": "DOUBLE",
    }
    PRIMARY_KEY = ("ts_code", "trade_date")

完成后可实现的因子:

  • chip_concentration_range
  • profit_pressure
  • underwater_resistance
  • smallcap_concentration
  • ...等 50+ 个

Phase 4: 资金流向数据同步Week 5

目标: 实现 moneyflow 表同步,支持 30+ 个资金相关因子

class MoneyFlowSync(StockBasedSync):
    table_name = "moneyflow"
    TABLE_SCHEMA = {
        "ts_code": "VARCHAR(16) NOT NULL",
        "trade_date": "DATE NOT NULL",
        "buy_sm_vol": "DOUBLE",
        "sell_sm_vol": "DOUBLE",
        "buy_lg_vol": "DOUBLE",
        "sell_lg_vol": "DOUBLE",
        "buy_elg_vol": "DOUBLE",
        "sell_elg_vol": "DOUBLE",
        "net_mf_vol": "DOUBLE",
    }

完成后可实现的因子:

  • lg_elg_net_buy_vol
  • flow_lg_elg_intensity
  • cs_rank_net_lg_flow_val
  • ...等 30+ 个

Phase 5: 分组聚合功能Week 6

目标: 实现 cs_mean by group 等分组计算

# 方式1: 扩展 cs_neutralize 的 group 参数
def cs_neutralize(x, group=None):
    if group:
        return (x - x.mean().over(["trade_date", group]))
    return (x - x.mean().over("trade_date"))

# 方式2: 新增 cs_mean_by 函数
def cs_mean_by(x, by):
    return x.mean().over(["trade_date"] + by)

完成后可实现的因子:

  • daily_deviation
  • daily_industry_deviation
  • cs_rank_ind_adj_lg_flow

Phase 6: 财务数据集成Week 7

目标: 实现财务数据同步和 asof_backward join

# 使用 DataSpec 的 asof_backward 模式
spec = DataSpec(
    table="financial_income",
    columns=["bps", "roe", "roa"],
    join_type="asof_backward",
    left_on="trade_date",
    right_on="f_ann_date",
)

完成后可实现的因子:

  • book_to_price_ratio
  • cashflow_to_ev_factor
  • cs_rank_size (需要 circ_mv)

五、可实现性统计

按实现难度分类

类别 数量 状态 时间预估
立即可实现 ~40个 使用现有功能 0 周
需新增 ts_* 函数 ~30个 Phase 1-2 2-3 周
需新增 cs_* 函数 ~10个 Phase 5 1 周
需筹码数据 (cyq) ~50个 Phase 3 1 周
需资金数据 (moneyflow) ~30个 Phase 4 1 周
需财务数据 (financial) ~20个 Phase 6 1 周
总计 180+个 6-7 周

按数据源分类

数据源 依赖因子数 实现难度 优先级
daily/pro_bar (已有) ~40
纯技术指标 (ts_*) ~30
筹码分布 (cyq) ~50
资金流向 (moneyflow) ~30
财务数据 (financial) ~20
分组计算 (cs_* by group) ~10

六、立即可实现的因子示例

from src.factors.api import close, open, high, low, vol, pct_chg, turnover_rate
from src.factors.api import ts_mean, ts_std, ts_max, ts_min, ts_delay, ts_delta, ts_corr, ts_sum
from src.factors.api import cs_rank, cs_zscore, cs_neutralize
from src.factors.api import log, sqrt, abs, sign, max_, min_, clip, if_

# 1. BBI 比率
bbi = (ts_mean(close, 3) + ts_mean(close, 6) + ts_mean(close, 12) + ts_mean(close, 24)) / 4
bbi_ratio_factor = bbi / close

# 2. AR 因子 (N=26)
ar = ts_sum(high - open, 26) / ts_sum(open - low, 26) * 100

# 3. BR 因子 (N=26)
prev_close = ts_delay(close, 1)
br = ts_sum(max_(0, high - prev_close), 26) / ts_sum(max_(0, prev_close - low), 26) * 100
ar_br = ar - br

# 4. 成交量变化率
volume_change_rate = ts_mean(vol, 2) / ts_mean(vol, 10) - 1

# 5. 换手率偏离度
turnover_deviation = (turnover_rate - ts_mean(turnover_rate, 3)) / ts_std(turnover_rate, 3)

# 6. 5日收益率
return_5 = close / ts_delay(close, 5) - 1

# 7. 20日收益率
return_20 = close / ts_delay(close, 20) - 1

# 8. Alpha 003
alpha_003 = if_(high != low, (close - open) / (high - low), 0)

# 9. Alpha 007 (等 Phase 1 后)
# alpha_007 = cs_rank(ts_corr(close, vol, 5))

# 10. 截面排名
rank_close = cs_rank(close)
rank_volume = cs_rank(vol)

# 11. Z-Score 标准化
zscore_close = cs_zscore(close)

# 12. 截面中性化 (Phase 5 后支持分组)
# neutralized = cs_neutralize(close, group="industry")

七、结论与建议

关键发现

  1. ts_ vs cs_ 区分清晰**:

    • ts_* 函数按 ts_code 分组,用于时间序列计算
    • cs_* 函数按 trade_date 分组,用于截面计算
    • 数学函数log, exp, atan 等)为逐元素计算,无分组
  2. 当前框架已实现:

    • 9个核心 ts_* 函数mean, std, max, min, sum, delay, delta, corr, cov
    • 3个 cs_* 函数rank, zscore, neutralize
    • 完整的运算符重载系统
  3. 主要缺口:

    • 统计函数: ts_var, ts_skew, ts_kurt, ts_pct_change
    • 技术指标: ts_ema, ts_atr, ts_rsi, ts_obv
    • 数学函数: atan, log1p
    • 分组聚合: cs_mean, cs_sum by group
    • 数据表: cyq, moneyflow, financial

推荐实施路径

阶段 目标 时间 完成后可计算因子数
Phase 1 ts_var, ts_skew, ts_kurt, ts_ema, atan 1-2周 +30个
Phase 2 TA-Lib 集成 (RSI, OBV) 1周 +5个
Phase 3 筹码数据同步 (cyq) 1周 +50个
Phase 4 资金流向同步 (moneyflow) 1周 +30个
Phase 5 分组聚合功能 1周 +10个
Phase 6 财务数据集成 1周 +20个
总计 6-7周 180+个

建议优先实现的因子(高 ROI

  1. BBI 比率: 纯技术指标,无需新数据
  2. AR/BR: 经典情绪指标,无需新数据
  3. 换手率偏离度: 流动性因子,无需新数据
  4. 筹码集中度: 需 cyq 数据,但实现简单
  5. 大单净流入: 需 moneyflow 数据,实现简单

通过以上步骤,预计在 6-7 周 内可实现文档中 90% 以上的因子表达式