JoinQuant 聚宽平台如何使用 calc_factors 计算自定义因子？

在 JoinQuant (聚宽) 量化平台中，from jqfactor import calc_factors 导入的 calc_factors 函数主要用于在回测以及研究环境中，计算单因子分析中自定义的因子值。

通过该函数，你可以将自己编写的因子逻辑（继承自 Factor 类的对象）应用到指定的股票池和时间段上，从而获取每天的因子值，为后续的单因子分析（如 IC 分析、收益分析等）提供数据基础。

1. 函数原型与参数说明

calc_factors(securities, factors, start_date, end_date, use_real_price=False, skip_paused=False)

参数详解：

• securities: 股票代码列表（如 ['600000.XSHG', '000001.XSHE']）。
• factors: 因子对象列表。需要传入实例化的自定义因子对象（如 [ALPHA013(), GROSSPROFITABILITY()]）。
• start_date: 计算因子的开始日期（字符串或 datetime 对象）。
• end_date: 计算因子的结束日期。在回测中使用时，应保证截止日期小于 context.current_dt 以避免未来函数。
• use_real_price: 是否使用真实价格。默认为 False，表示使用后复权价格计算。
• skip_paused: 是否跳过停牌日。默认为 False。注意：当依赖的因子为价量信息且 skip_paused = True 时，返回的 DataFrame 索引由 datetime 变为 int（值越大表示离当前日期越近）。

返回值：
返回一个 dict 对象：

• Key: 各个因子的名称（即自定义因子类中的 name 属性）。
• Value: 一个 pandas.DataFrame。DataFrame 的 index 是日期，column 是股票代码，里面的值即为计算出的因子值。

2. 具体用法示例

要使用 calc_factors，通常需要先定义一个继承自 Factor 的自定义因子类，实现 calc 方法。以下是一个完整的示例，演示如何定义一个简单的价量因子并计算其值：

import numpy as np
from jqfactor import Factor, calc_factors

# 1. 定义自定义因子
class ALPHA013(Factor):
    # 设置因子名称，计算结果的 dict 将以此作为 key
    name = 'alpha013_name'
    # 设置获取数据的时间窗口长度（天）
    max_window = 1
    # 设置依赖的基础数据字段
    dependencies = ['high', 'low', 'volume', 'money']
    
    # 实现计算逻辑
    def calc(self, data):
        high = data['high']
        low = data['low']
        # 计算成交均价 vwap
        vwap = data['money'] / data['volume']
        # 返回因子值：最高价与最低价乘积的平方根 减去 均价
        # 使用 .mean() 是为了将 1行N列 的 DataFrame 转换为 Series
        return (np.power(high * low, 0.5) - vwap).mean()

# 2. 准备计算参数
# 定义股票池
securities = ['600000.XSHG', '600016.XSHG']

# 3. 调用 calc_factors 计算因子值
factors_result = calc_factors(
    securities=securities, 
    factors=[ALPHA013()], # 传入实例化的因子对象列表
    start_date='2017-01-01', 
    end_date='2017-02-01',  
    use_real_price=False, 
    skip_paused=False
)

# 4. 查看计算结果
print(factors_result['alpha013_name'].head())

输出结果示例：

             600000.XSHG  600016.XSHG
2017-01-03    -0.176511    -0.070154
2017-01-04    -0.068026     0.006268
2017-01-05    -0.092072     0.022604
2017-01-06    -0.021411     0.259906
2017-01-09     0.054015    -0.118956

总结

calc_factors 是聚宽因子研究体系中的核心函数之一。通过它，你可以将复杂的选股逻辑封装为 Factor 类，并批量计算出历史因子值，进而无缝对接到 analyze_factor 等单因子分析工具中，评估因子的有效性（如 IC、IR、分位数收益等）。