如何在 JoinQuant 中使用 calc_factors 计算多因子？

因子模块jqfactor中calc_factors 用法

新建多因子策略时，模板显示导入jqfactor模块中的calc_factors
后面也用calc_factors计算因子值，请问calc_factors具体怎么使用呢？
from jqfactor imort Factor, calc_factors

计算因子值
values = calc_factors(universe,
factor_list,
context.previous_date,
context.previous_date)

在 JoinQuant（聚宽）量化平台中，jqfactor 模块提供了强大的因子分析和计算功能。calc_factors 函数主要用于在回测或研究环境中计算自定义因子或内置因子的值。

以下是 calc_factors 的详细用法说明：

函数原型

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

参数说明

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

返回值

返回一个 dict 对象：

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

完整使用示例

下面是一个在研究环境或回测中定义自定义因子并使用 calc_factors 计算的完整示例：

import numpy as np
from jqfactor import Factor, calc_factors

# 1. 定义一个自定义因子类，继承自 Factor
class MyAlpha013(Factor):
    # 设置因子名称，计算结果的 dict 将以此作为 key
    name = 'alpha013_name'
    # 设置获取数据的时间窗口长度（天）
    max_window = 1
    # 设置依赖的基础数据字段
    dependencies = ['high', 'low', 'volume', 'money']
    
    # 实现 calc 方法计算因子值
    def calc(self, data):
        high = data['high']
        low = data['low']
        # 计算成交均价 vwap
        vwap = data['money'] / data['volume']
        # 返回一个 pandas.Series，index 是股票代码，value 是因子值
        # 这里求 mean() 是为了将 1行N列 的 DataFrame 转换为 Series
        return (np.power(high * low, 0.5) - vwap).mean()

# 2. 准备参数
securities = ['600000.XSHG', '600016.XSHG']
factor_list = [MyAlpha013()]
start_date = '2017-01-01'
end_date = '2017-01-10'

# 3. 调用 calc_factors 计算因子值
values = calc_factors(
    securities=securities, 
    factors=factor_list, 
    start_date=start_date, 
    end_date=end_date,  
    use_real_price=False, 
    skip_paused=False
)

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

在回测策略中的典型用法

如果你在回测的 handle_data 或定时运行函数中调用，通常只需要计算前一个交易日的因子值：

def before_trading_start(context):
    # 获取股票池
    universe = get_index_stocks('000300.XSHG')
    # 实例化因子
    factor_list = [MyAlpha013()]
    
    # 计算前一交易日的因子值
    values = calc_factors(
        securities=universe,
        factors=factor_list,
        start_date=context.previous_date,
        end_date=context.previous_date
    )
    
    # 获取具体的因子 DataFrame
    alpha_df = values['alpha013_name']
    # 提取前一天的 Series 数据
    today_factor_values = alpha_df.loc[context.previous_date]
    
    # 后续可以根据 today_factor_values 进行排序选股等操作

通过这种方式，你可以非常方便地将复杂的因子计算逻辑封装在 `Factor` 类中，并利用 `calc_factors` 批量计算多只股票、多个因子的历史数值。