如何在 JoinQuant 中高效调用 get_factor_values 批量获取质量与情绪因子？

在 JoinQuant（聚宽）平台中，get_factor_values 是获取聚宽因子库中质量、情绪、成长、风险等数百个因子核心 API。本文将详细介绍该函数的使用规范，并提供批量获取质量因子与情绪因子的完整代码示例。

一、 API 语法与参数说明

get_factor_values 函数属于 jqfactor 模块，使用前需先导入。

from jqfactor import get_factor_values

# 核心调用格式
factor_data = get_factor_values(securities, factors, start_date=None, end_date=None, count=None)

参数解析：

1. securities: 股票池，支持单只股票代码字符串（如 '000001.XSHE'）或股票代码列表（如 ['000001.XSHE', '600000.XSHG']）。
2. factors: 因子代码列表，如质量因子 quick_ratio（速动比率）或情绪因子 VOL5（5日平均换手率）。
3. start_date / end_date / count:
   • 可选择 start_date + end_date 确定时间范围。
   • 也可使用 count + end_date 获取截止到 end_date 前指定交易日天数的数据。

注意事项：

• 数据区间限制：为了保证系统性能，单次请求的因子数据总量（因子数 × 股票数 × 交易日数）不得超过 200,000 个。
• 返回值格式：返回一个字典（dict），key 为因子名称，value 为对应的 pandas.DataFrame（Index 为日期，Columns 为股票代码）。

二、 常用质量因子与情绪因子代码对照

1. 常见质量因子 (Quality Factors)

• quick_ratio: 速动比率
• roe_ttm: 净资产收益率 TTM
• net_profit_margin: 销售净利率
• debt_to_asset_ratio: 资产负债率

2. 常见情绪因子 (Emotion Factors)

• VOL5: 5日平均换手率
• VOSC: 成交量震荡指标
• AR: 人气指标
• BR: 意愿指标

三、 完整代码示例：批量获取与处理数据

以下示例展示如何在 Python 中一次性提取沪深300成分股的质量与情绪因子，并提取为 DataFrame 数据：

import pandas as pd
from jqdata import get_index_stocks
from jqfactor import get_factor_values

# 1. 获取标的池（以沪深300为例）
stocks = get_index_stocks('000300.XSHG')[:10]  # 取前10只股票作为示例

# 2. 定义需要获取的因子列表（包含质量与情绪因子）
factor_list = [
    'quick_ratio',       # 质量因子：速动比率
    'roe_ttm',           # 质量因子：ROE TTM
    'VOL5',              # 情绪因子：5日平均换手率
    'VOSC'               # 情绪因子：成交量震荡
]

# 3. 批量获取最近 5 个交易日的因子数据
factor_dict = get_factor_values(
    securities=stocks,
    factors=factor_list,
    end_date='2023-12-29',
    count=5
)

# 4. 查看与使用数据
# 获取 ROE 因子数据的 DataFrame
roe_df = factor_dict['roe_ttm']
print("=== ROE TTM ===")
print(roe_df)

# 获取 5日平均换手率 因子数据的 DataFrame
vol5_df = factor_dict['VOL5']
print("\n=== 5日平均换手率 (VOL5) ===")
print(vol5_df)

# 5. 提取最新一天的所有因子值并合并为截面表
latest_date = roe_df.index[-1]
snapshot = pd.DataFrame({
    factor: factor_dict[factor].loc[latest_date]
    for factor in factor_list
})
print(f"\n=== 最新截面数据 ({latest_date}) ===")
print(snapshot)

四、 高效调用的性能优化建议

1. 控制请求规模：按需提取因子和股票，避免一次性查询全市场数千只股票的长周期数据，防止触发 200,000 数据量上限限制。
2. 截面因子计算：若仅用于每日调仓选股，设置 count=1 即可仅获取最新一天的截面因子，可大幅提升策略运行速度。
3. 缺失值处理：某些停牌股或新股的财务/情绪因子可能包含 NaN 值，建议在后续计算中配合 .fillna() 或 jqfactor.winsorize 等预处理函数进行清洗。