JoinQuant 平台自定义因子开发指南

在 JoinQuant（聚宽）平台上，进行多因子选股或因子研究时，编写自定义因子是极重要的一环。聚宽提供的 jqfactor 模块允许开发者通过继承 Factor 类快速构建自定义因子，并使用 calc_factors 函数进行高效的批量计算与历史回溯。

一、自定义因子的核心步骤

编写并使用自定义因子主要分为三个步骤：

1. 继承 Factor 类定义因子：设定因子名称、时间窗口（max_window）、依赖数据（dependencies），并重写 calc 方法。
2. 调用 calc_factors 计算因子值：传入标的列表、因子对象实例以及时间范围，获取计算结果。
3. 单因子分析（可选）：使用 analyze_factor 评估因子的 IC 值、换手率及分位数收益。

二、继承 Factor 类编写自定义因子

1. Factor 类的核心属性

• name：因子的唯一标识名称（字符串）。
• max_window：计算该因子所需的最大历史数据天数（整数）。
• dependencies：因子计算所依赖的基础数据列表，支持基础价量（open, close, high, low, volume, money）、财务数据（如 total_operating_revenue）、聚宽因子库因子或行业/概念因子。

2. 代码示例：定义 MA5 均线因子与毛利率因子

import numpy as np
from jqfactor import Factor

# 示例1：基于价量的 MA5 均线因子
class MA5(Factor):
    name = 'ma5_factor'
    max_window = 5
    dependencies = ['close']
    
    def calc(self, data):
        # data['close'] 为 DataFrame，行索引为天数，列索引为股票代码
        return data['close'][-5:].mean()

# 示例2：基于财务数据的单季度毛利率因子
class GrossProfitability(Factor):
    name = 'gross_profitability'
    max_window = 1
    dependencies = ['total_operating_revenue', 'total_operating_cost', 'total_assets']
    
    def calc(self, data):
        revenue = data['total_operating_revenue']
        cost = data['total_operating_cost']
        assets = data['total_assets']
        
        # 计算毛利率，并转为 pandas.Series 格式返回
        gp = (revenue - cost) / assets
        return gp.mean()

注意：calc 方法接收一个 data 字典参数，字典的 key 为 dependencies 中定义的名称，value 为 pandas.DataFrame。calc 的返回值必须是一个 pandas.Series（Index 为股票代码，Value 为因子值）。如果计算结果是一行 N 列的 DataFrame，需调用 .mean() 或 .iloc[0] 转换为 Series。

三、使用 calc_factors 批量计算因子值

通过 calc_factors 函数，可以在研究环境或回测中批量计算多个股票在一段时间内的自定义因子值。

函数语法

from jqfactor import calc_factors

factors_dict = calc_factors(
    securities=['000001.XSHE', '600000.XSHG'],
    factors=[MA5(), GrossProfitability()],
    start_date='2023-01-01',
    end_date='2023-02-01',
    use_real_price=False,  # 是否使用真实价格（默认False使用后复权）
    skip_paused=False       # 是否跳过停牌标的
)

示例代码与输出处理

from jqdata import get_index_stocks
from jqfactor import calc_factors

# 1. 获取沪深300成分股
securities = get_index_stocks('000300.XSHG')[:5]

# 2. 批量计算因子
factor_results = calc_factors(
    securities=securities,
    factors=[MA5(), GrossProfitability()],
    start_date='2023-01-01',
    end_date='2023-01-10'
)

# 3. 查看计算结果（返回值为 dict，key 为因子 name，value 为 DataFrame）
ma5_df = factor_results['ma5_factor']
print(ma5_df.head())

四、单因子分析评估（Analyze Factor）

获得自定义因子后，可使用 analyze_factor 进行因子的有效性评估：

from jqfactor import analyze_factor

# 对自定义 MA5 因子进行单因子性能分析
far = analyze_factor(
    factor=MA5,
    start_date='2022-01-01',
    end_date='2022-12-31',
    universe='000300.XSHG',
    quantiles=5,
    periods=(1, 5, 10)
)

# 查看月度 IC 值
print(far.ic_monthly)

五、注意事项与最佳实践

1. 防止未来函数：在回测中使用 calc_factors 时，请确保 end_date 不大于策略当前的逻辑时间 context.current_dt。
2. 单行 DataFrame 转换：当 max_window = 1 时，data[field] 返回的是 1 行 N 列的 DataFrame，必须转为 Series（如调用 .mean()）才能正确返回。
3. 内存与数据量控制：一次性计算过多股票或过长历史区间的因子值可能导致内存超限，建议分批次或按需获取。