小果排序多因子回测系统专家

一、系统概述

使用教程：https://gitcode.com/qq_50882340/xg_rank_factor_backtrader

1.1 系统定位

小果排序多因子回测系统（xg_rank_factor_backtrader）是一套专为排名轮动型多因子策略设计的专业级量化回测框架。它将复杂的多因子选股流程标准化为可配置、可扩展的流水线作业，让研究者能够高效地进行因子挖掘、策略回测和绩效分析。

1.2 设计哲学

• 解耦与复用：将数据加载、因子计算、条件筛选、排序打分、交易执行、绩效评估各环节解耦，每个模块可独立优化和复用。
• 透明与可解释：每个调仓日的排序逻辑、因子权重、得分明细均可追溯，策略决策过程完全透明。
• 灵活与扩展：支持用户自定义因子公式、自定义数据注入（标的 + 指数）、自定义交易规则，满足从简单到复杂的各类策略需求。

1.3 核心回测流程（四步）

第一步  买入条件过滤：按 buy_condi_factor 用 and / or / not 逻辑筛出初步候选池
        （is_open_buy_condi=False 时跳过，直接全市场排序）
第二步  排序因子打分：rank_factor 中每个因子得分 = 因子值 × 相关性系数 × 权重
        相关性系数：正相关 = +1，负相关 = -1；Bool 因子参与排序时按 1/0 处理
第三步  综合排序取前N：按 total_factor_rank（降序/升序/无）对总分排序，
        取前 hold_stock_limit 名形成交易股票池
第四步  先卖后买轮动：持股不在交易股票池 → 卖出；交易池中未持股 → 买入；
        受 min_hold_days、止盈(sell_type)、涨跌停过滤、单票仓位上限等约束

1.4 因子值语义约定

• Bool 类型因子（如金叉/死叉、价格在均线上等）：0 表示符合条件（True），1 表示不符合条件（False），用于买入条件 等于 0 判定。
• 数值类型因子（连续涨跌天数、价格、动量等）：正常数值比较（大于/小于/等于）。
• 买入条件比较时系统会兼容 True/False、'T'/'t'/'TRUE'、'F'/'f'/'FALSE' 等布尔形态，1 和 0 始终按数值处理。

1.5 数据文件字段要求

> 自定义指数数据列要求：使用 add_index_data_from_* 注入的指数数据只需包含 date 与 close（且 close > 0）。系统会自动识别日期列/日期索引并升序排列；若同时存在 open 列也会执行 open > 0 过滤。注入成功后，回测的指数基准将优先使用注入数据（等价于股票数据的 use_custom_data 自动切换机制）。

二、初始化参数完整参考

> 以下为 __init__ 方法全部参数的详细说明，按功能分组。

2.1 时间与标的 (Time & Universe)

2.2 资金与费用 (Capital & Cost)

2.3 交易与仓位 (Trading & Position)

2.4 因子与策略 (Factor & Strategy)

2.5 止盈与风控 (Risk Management)

2.6 trader_type 与 trader_value 匹配表

2.7 sell_type 与 sell_value 匹配表

三、自定义因子公式引擎详解

3.1 公式编写规范

• 数据对象：公式中固定使用 df 代表当前股票的全量日线 DataFrame。
• 函数库：自动导入 xg_tdx_func 中全部函数，无需额外 import。
• 返回值：支持 pd.Series（长度与 df 一致）、int/float（广播为常量列）、或可转换为 Series 的对象。
• 命名约束：自定义因子名不可与已有列名重复。
• 执行方式：每只股票独立 eval 计算，公式异常会被静默跳过（可通过 verbose 观察结果列确认是否生成成功）。

3.2 支持的常用指标函数速查

趋势类指标

超买超卖类

量能类指标

波动类指标

逻辑与形态类

3.3 典型自定义因子示例

user_factor_cacal = {
    # 动量因子：20日涨跌幅
    "动量_20日": "df['close'] / REF(df['close'], 20) - 1",

    # 波动因子：20日标准差
    "波动率_20日": "STD(df['close'], 20)",

    # 均线乖离率
    "乖离率_5日": "(df['close'] - MA(df['close'], 5)) / MA(df['close'], 5)",

    # 均线多头排列评分 (0-100)
    "均线多头评分": (
        "IF(MA(df['close'],3) > MA(df['close'],5), 25, 0) + "
        "IF(MA(df['close'],5) > MA(df['close'],10), 25, 0) + "
        "IF(MA(df['close'],10) > MA(df['close'],20), 25, 0) + "
        "IF(MA(df['close'],20) > MA(df['close'],30), 25, 0)"
    ),

    # MACD金叉信号 (0=符合)
    "MACD金叉": "IF(CROSS(MACD(df['close'],12,26,9)[0], MACD(df['close'],12,26,9)[1]), 0, 1)",

    # RSI超卖信号 (0=符合)
    "RSI超卖": "IF(RSI(df['close'],14) < 30, 0, 1)",

    # 成交量放大
    "成交量放大": "IF(df['volume'] > MA(df['volume'],5) * 1.5, 1, 0)",
}

四、策略配置详解与最佳实践

4.1 买入条件配置 (buy_condi_factor)

配置格式

buy_condi_factor = {
    "因子名A": {"选择类型": "and|or|not", "选择方向": "等于|大于|小于", "值": 目标值},
}

逻辑组合规则

• and：所有 and 条件必须同时满足。
• or：同组 or 条件至少满足其一。
• not：条件必须不满足。

最佳实践

• 对于布尔型因子，推荐使用 0 表示符合条件（True），1 表示不符合（False）。
• 避免使用过多条件导致候选池过小，建议控制在 3-5 个核心条件。
• 可以使用 or 组合相似的替代条件，增加候选池的鲁棒性。

4.2 排序因子配置 (rank_factor)

配置格式

rank_factor = {
    "因子名A": {"相关性": "正相关|负相关", "权重": 权重值},
}

得分计算公式

单因子得分 = 因子值 × 相关性系数 × 权重
综合得分   = Σ(所有排序因子的单因子得分)
其中：相关性系数：正相关 = +1，负相关 = -1

最佳实践

• 权重值反映因子的相对重要性，建议使用 1-10 之间的整数。
• 布尔型因子的权重建议设为 1-2，避免过度影响得分。
• 避免使用高度相关的因子组合，以防多重共线性。
• 建议同时包含趋势类（动量）、均值回复类（波动率）、质量类（ROE）等不同类型的因子。

4.3 交易参数调优建议

五、完整函数清单（含内部方法）

> 框架类 xg_rank_factor_backtrader 共 62 个核心方法 + 10 个指数数据接口（合计 72 个），以下按功能模块列出，便于二次开发和深度集成。

5.1 初始化和配置管理

5.2 数据加载与注入

5.3 自定义数据注入接口（7种）

5.4 自定义数据管理

5.5 指数数据注入接口（7种）

> 将自定义指数数据注入内存，注入成功后 has_index_data() 为 True，回测的指数基准优先使用注入数据（等价于股票数据 use_custom_data 机制，自动切换）。数据只需 date、close 两列。

5.6 指数数据管理

5.7 因子计算与条件判定

5.8 交易执行与计算

5.9 回测执行

5.10 数据生成与转换

5.11 绩效评估与报告

六、输出数据结构详解

> 框架共提供 8 类对外输出数据，均由回测结束后生成（首次调用 get_* 或 run_backtest 时自动触发缓存）。

6.1 绩效指标字段 (performance_metrics)

6.2 年度收益统计字段 (annual_performance)

> 按自然年分组统计，get_annual_performance() / get_backtrader_data() 返回。键为年份字符串，值为如下字段：

6.3 净值曲线字段 (equity_curve_data)

6.4 成交记录字段 (trade_data / trade_log)

> get_trade_data() 返回 {'trades': [...], 'statistics': {...}}。其中 trades 元素（即 trade_log 明细）字段如下：

statistics 子结构：

6.5 持仓数据字段 (position_data)

> get_position_data() 返回 {'positions': [...], 'statistics': {'total_days': N}}，每日一行。

6.6 账户数据字段 (account_data)

> get_account_data() 返回 {'account_history': [...], 'statistics': {}}，每日一行。

6.7 导出目录结构

> save_backtrader_data(user='xxx') 将回测结果分类保存为 Excel + JSON 双格式；save_to_json() 保存单文件全量 JSON；get_backtrader_data() 内存中返回同构数据。指数数据目录保存的是回测实际使用的指数数据（注入的自定义指数数据或本地指数）。

策略模型/排序多因子策略/<user>/
├── 指数数据/
│   ├── 指数数据.xlsx
│   └── 指数数据.json
├── 成交数据/
│   ├── 成交数据.xlsx
│   └── 成交数据.json
├── 持股数据/
│   ├── 持股数据.xlsx
│   └── 持股数据.json
├── 账户数据/
│   ├── 账户数据.xlsx
│   └── 账户数据.json
├── 绩效指标/
│   ├── 绩效指标.xlsx
│   └── 绩效指标.json
├── 净值曲线/
│   ├── 净值曲线.xlsx
│   └── 净值曲线.json
├── 策略参数/
│   ├── 策略参数.xlsx
│   └── 策略参数.json
└── 年度收益统计/
    ├── 年度收益统计.xlsx
    └── 年度收益统计.json

七、完整实战示例合集

7.1 示例1：均线多头 + 动量排序轮动策略

from xg_rank_factor_backtrader.xg_rank_factor_backtrader import xg_rank_factor_backtrader

bt = xg_rank_factor_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH', '510300.SH', '512880.SH', '159949.SZ'],
    index_stock='000300.SH',
    cash=500000,
    comm=0.0003,
    trader_type='百分比',
    trader_value=0.8,
    hold_stock_limit=4,
    max_single_position_ratio=0.3,
    interval=5,
    min_hold_days=3,

    is_open_user_factor=True,
    user_factor_list=['close', 'open', 'high', 'low', 'volume', 'zdf', 'amount'],
    user_factor_cacal={
        "收盘价大于5日均线": "IF(df['close'] > MA(df['close'], 5), 0, 1)",
        "5日均线在10日均线上": "IF(MA(df['close'],5) > MA(df['close'],10), 0, 1)",
        "20日动量": "df['close'] / REF(df['close'], 20) - 1",
        "60日动量": "df['close'] / REF(df['close'], 60) - 1",
        "均线多头评分": (
            "IF(MA(df['close'],3) > MA(df['close'],5), 20, 0) + "
            "IF(MA(df['close'],5) > MA(df['close'],10), 20, 0) + "
            "IF(MA(df['close'],10) > MA(df['close'],20), 20, 0) + "
            "IF(MA(df['close'],20) > MA(df['close'],30), 20, 0) + "
            "IF(MA(df['close'],30) > MA(df['close'],60), 20, 0)"
        ),
        "RSI_14": "RSI(df['close'], 14)",
        "波动率_20日": "STD(df['close'], 20)",
    },

    is_open_buy_condi=True,
    buy_condi_factor={
        "收盘价大于5日均线": {"选择类型": "and", "选择方向": "等于", "值": 0},
        "5日均线在10日均线上": {"选择类型": "and", "选择方向": "等于", "值": 0},
        "20日动量": {"选择类型": "and", "选择方向": "大于", "值": 0.01},
    },

    rank_factor={
        "均线多头评分": {"相关性": "正相关", "权重": 2},
        "20日动量": {"相关性": "正相关", "权重": 3},
        "60日动量": {"相关性": "正相关", "权重": 2},
        "RSI_14": {"相关性": "正相关", "权重": 1},
        "波动率_20日": {"相关性": "负相关", "权重": 1},
    },
    total_factor_rank='降序',

    sell_type='百分比',
    sell_zdf=0.15,
    sell_value=0.3,  # 涨15%后卖出30%仓位
    enable_limit_up_down_filter=True,
    max_workers=8,
)

metrics = bt.run_backtest()
print(bt.generate_report())
bt.save_backtrader_data(user="均线动量策略")

7.2 示例2：纯因子排名轮动（关闭买入过滤）

bt = xg_rank_factor_backtrader(
    start_date='20240101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH', '510300.SH', '512880.SH'],
    cash=200000,
    hold_stock_limit=3,
    interval=3,
    min_hold_days=2,

    is_open_buy_condi=False,  # 关键：关闭买入条件筛选
    is_open_user_factor=True,
    user_factor_cacal={
        "20日涨跌幅": "df['close'] / REF(df['close'], 20) - 1",
        "5日涨跌幅": "df['close'] / REF(df['close'], 5) - 1",
        "20日标准差": "STD(df['close'], 20)",
        "换手率": "df['volume'] / MA(df['volume'], 20)",  # 需数据含volume
    },
    rank_factor={
        "20日涨跌幅": {"相关性": "正相关", "权重": 2},
        "5日涨跌幅": {"相关性": "正相关", "权重": 1},
        "20日标准差": {"相关性": "负相关", "权重": 1},
    },
    total_factor_rank='降序',
    trader_type='金额',
    trader_value=50000,
    sell_type='none',
)

bt.run_backtest()
print(bt.generate_report())

7.3 示例3：自定义数据注入 + 多因子回测

import pandas as pd

# 准备数据（假设已有CSV文件）
bt = xg_rank_factor_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH', '510300.SH'],
    cash=300000,
    hold_stock_limit=2,
    is_open_buy_condi=False,

    is_open_user_factor=True,
    user_factor_cacal={
        "RSI_14": "RSI(df['close'], 14)",
        "MACD金叉": "IF(CROSS(MACD(df['close'],12,26,9)[0], MACD(df['close'],12,26,9)[1]), 0, 1)",
    },
    rank_factor={
        "RSI_14": {"相关性": "正相关", "权重": 1},
        "MACD金叉": {"相关性": "正相关", "权重": 2},
    },
    total_factor_rank='降序',
    sell_type='金额',
    sell_zdf=0.05,
    sell_value=2000,
)

# 注入自定义数据
bt.add_stock_data_from_csv('159915.SZ', 'data/159915.csv')
bt.add_stock_data_from_excel('513100.SH', 'data/513100.xlsx', sheet_name='Sheet1')
bt.add_stock_data_from_json('518880.SH', 'data/518880.json')
bt.add_stock_data_from_dataframe('510300.SH', pd.read_parquet('data/510300.parquet'))

bt.run_backtest()
print(bt.generate_report())
bt.save_to_json('result/multi_factor_backtest.json')

7.4 示例4：提取回测结果进行二次分析

# 运行回测
bt.run_backtest()

# 获取各项数据
metrics = bt.get_performance_metrics()
curve = bt.get_equity_curve_data()
trades = bt.get_trade_data()
positions = bt.get_position_data()

# 打印关键指标
print(f"总收益率: {metrics['total_return']*100:.2f}%")
print(f"年化收益率: {metrics['annual_return']*100:.2f}%")
print(f"最大回撤: {metrics['max_drawdown']*100:.2f}%")
print(f"夏普比率: {metrics['sharpe_ratio']:.3f}")
print(f"胜率: {metrics['win_rate']*100:.2f}%")
print(f"交易笔数: {metrics['total_trades']}")

# 使用matplotlib绘制净值曲线
import matplotlib.pyplot as plt

dates = curve['dates']
plt.figure(figsize=(12, 6))
plt.plot(dates, curve['net_value'], label='策略净值', linewidth=2)
plt.plot(dates, curve['benchmark_net_value'], label='基准(持有不动)', linewidth=1.5, linestyle='--')
if curve.get('index_net_value'):
    plt.plot(dates, curve['index_net_value'], label='指数', linewidth=1.5, linestyle=':')
plt.legend()
plt.xlabel('日期')
plt.ylabel('净值')
plt.title('策略净值 vs 基准 vs 指数')
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()

# 绘制回撤曲线
plt.figure(figsize=(12, 4))
plt.fill_between(dates, 0, curve['drawdown'], color='red', alpha=0.3)
plt.plot(dates, curve['drawdown'], color='red', linewidth=1)
plt.xlabel('日期')
plt.ylabel('回撤 (%)')
plt.title('策略回撤曲线')
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()

7.5 示例5：注入自定义指数数据做基准比较

bt = xg_rank_factor_backtrader(
    start_date='20240101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'],
    index_stock='000300.SH',   # 注入自定义指数数据后，以注入数据为准
    cash=100000,
    hold_stock_limit=2,
)

# 注入自定义指数数据（date + close 两列即可，均支持）
bt.add_index_data_from_csv('data/index_000300.csv')      # CSV（自动尝试编码）
# bt.add_index_data_from_dataframe(df_index)             # 或 DataFrame
# bt.add_index_data_from_excel('data/index.xlsx')        # 或 Excel
# bt.add_index_data_from_json('data/index.json')         # 或 JSON
# bt.add_index_data_from_dict({'date': [...], 'close': [...]})  # 或 字典
# bt.add_index_data_from_parquet('data/index.parquet')   # 或 Parquet

# 校验注入结果
print(bt.has_index_data())          # True
print(bt.get_index_data_info())     # {'has_data': True, 'rows': N, 'start_date':..., 'end_date':..., 'columns': [...]}

bt.run_backtest()
print(bt.generate_report())

# 如需恢复使用本地指数文件
# bt.clear_index_data()

八、高级技巧与性能优化

8.1 因子组合优化建议

• 因子多样性：组合使用趋势因子（动量）、均值回复因子（波动率）、质量因子（ROE/毛利率）、情绪因子（换手率）等不同类型。
• 因子正交化：避免使用高度相关的因子（如5日涨跌幅和10日涨跌幅），可考虑做中性化处理。
• 权重调优：使用网格搜索或贝叶斯优化寻找最优权重组合。

8.2 交易成本控制

• 降低换手：增大 interval 和 min_hold_days 可显著降低交易频率。
• 滑点敏感度：对流动性较差的标的，适当调高 slippage 参数。
• 佣金优化：min_commission 可模拟券商最低收费，避免小额交易被高佣金侵蚀。

8.3 数据加载优化

• 列裁剪：user_factor_list 只配置必要的列，减少IO开销。
• 并行加载：max_workers 可根据CPU核心数设置（建议不超过8）。
• 数据缓存：get_stock_data 和 get_index_data 内置缓存，避免重复读取；指数注入数据命中缓存时不再读取本地文件。

8.4 策略鲁棒性提升

• 涨跌停过滤：开启 enable_limit_up_down_filter 避免无法交易的样本。
• 最小持有天数：防止策略过度响应短期噪声。
• 仓位上限：max_single_position_ratio 防止单只标的过度集中。

九、常见问题与解决方案 (FAQ)

十、扩展开发指南

10.1 自定义新的技术指标

在 xg_tdx_func 库中添加新函数，然后在 user_factor_cacal 中直接调用。

10.2 自定义交易逻辑

继承 xg_rank_factor_backtrader 类，重写以下核心方法：

• get_trading_stocks()：修改交易股票池的选取逻辑
• check_take_profit()：自定义止盈/止损规则
• calculate_buy_shares()：自定义仓位分配算法

10.3 自定义绩效指标

在 calculate_performance_metrics() 中添加新的指标计算逻辑。

1. 指数数据读取接口
新增了以下方法用于加载自定义指数数据：

方法  说明
add_index_data_from_dataframe(df)   从DataFrame加载指数数据
add_index_data_from_csv(file_path)  从CSV文件加载指数数据
add_index_data_from_excel(file_path, sheet_name)    从Excel文件加载指数数据
add_index_data_from_json(file_path) 从JSON文件加载指数数据
add_index_data_from_dict(data)  从字典加载指数数据
add_index_data_from_parquet(file_path)  从Parquet文件加载指数数据
add_index_data_from_bytes(bytes, file_type) 从字节数据加载指数数据
2. 指数数据管理方法
方法  说明
clear_index_data()  清空自定义指数数据
has_index_data()    检查是否有自定义指数数据
get_index_data_info()   获取指数数据信息

小果排序多因子回测系统，让多因子策略开发更高效、更透明。如需源码、更多因子库或技术支持，欢迎联系小果（微信：xg_quant）。