小果综合多策略回测系统专家

教程 https://gitcode.com/qq_50882340/xg_quant_backtrader
> 一套把 10 个量化回测引擎 收进同一个 xg_quant_backtrader Python 包的综合多策略平台。
> 统一数据规范、统一注入接口、统一导出结构，引擎各自负责差异化的交易逻辑。

一、平台总览（一包十引擎）

xg_quant_backtrader 是一个目录（Python 包），内含 10 个单文件、单类回测引擎。每个文件即一个引擎，类名与模块同名。统一导入方式（本文档全部采用，从包路径导入）：

from xg_quant_backtrader.xg_dt_backtrader import xg_dt_backtrader              # 定投+做T
from xg_quant_backtrader.xg_gd_backtrader import xg_gd_backtrader              # 网格+做T
from xg_quant_backtrader.xg_hg_backtrader import xg_hg_backtrader              # 海龟
from xg_quant_backtrader.xg_mom_backtrader import xg_mom_backtrader            # 动量轮动
from xg_quant_backtrader.xg_more_mom_backtrader import xg_more_mom_backtrader  # 综合动量
from xg_quant_backtrader.xg_pz_backtrader import xg_pz_backtrader              # 资产配置+做T
from xg_quant_backtrader.xg_zcph_backtrader import xg_zcph_backtrader          # 资产配置平衡+做T
from xg_quant_backtrader.xg_mean_var_backtrader import xg_mean_var_backtrader  # 均值方差 MPT
from xg_quant_backtrader.xg_condi_factor_backtrader import xg_condi_factor_backtrader  # 条件因子
from xg_quant_backtrader.xg_rank_factor_backtrader import xg_rank_factor_backtrader    # 排序多因子

> 把整个 xg_quant_backtrader 目录放到工作目录，或将它的父目录加入 PYTHONPATH / sys.path 即可用上述写法导入。若脚本与 .py 同目录，也可退化为 from xg_dt_backtrader import xg_dt_backtrader（模块名写法）。

1.1 十引擎全景对照表

> 方法数为类内方法数（不含模块级顶层函数；xg_condi_factor_backtrader 另有 parse_factor_config/parse_config_with_bool 两个模块级函数）。

1.2 引擎族谱

xg_quant_backtrader 包
│
├─ A. 信号交易型（择时/信号触发买与卖）
│   ├─ 定期定投族:  xg_dt_backtrader        定投节奏 + 做T
│   ├─ 网格交易族:  xg_gd_backtrader        网格档位高抛低吸
│   ├─ 趋势突破族:  xg_hg_backtrader        海龟唐奇安突破 + N值
│   ├─ 动量轮动族:  xg_mom_backtrader       单动量模型轮动
│   │              xg_more_mom_backtrader   六大动量 + 多层风控
│   └─ 因子选股族:  xg_condi_factor_backtrader  条件过滤 + 排序因子
│                   xg_rank_factor_backtrader  因子加权打分 + 排名
│
├─ B. 资产配置型（配置权重 / 风险收益最优化）
│   ├─ xg_pz_backtrader       固定配置买入持有 + 做T增厚
│   ├─ xg_zcph_backtrader     固定市值再平衡 + 做T
│   └─ xg_mean_var_backtrader 马科维茨 MPT 最优权重（依赖 scipy）

1.3 两大引擎族（公共方法口径差异）

> 全部 10 引擎真公共为 36 个方法（构造/数据加载/标的7注入/管理/撮合/绩效/输出生成/基础 getter/run_backtest），见第十八章函数总表。

1.4 三大共性（所有引擎一致）

1. 同一数据规范：标的日线 data/历史数据/{代码}.parquet，指数 data/指数数据/{代码}.xxx；必需 date/close/open/volume，推荐 zdf/preClose/high/low/amount。
2. 同一导出规范：save_backtrader_data(user=...) 落盘 策略模型/{策略类型}/{user}/，统一 8 子目录（指数数据/成交数据/持股数据/账户数据/绩效指标/净值曲线/策略参数/年度收益统计）；xg_mean_var_backtrader 额外含「权重历史」子目录。
3. 同一撮合口径：整手 100 份、comm 费率、adj_type='none'。

二、安装与环境配置

2.1 包结构（本教程统一采用）

工作目录/
├── xg_quant_backtrader/            # 综合多策略包（10 个引擎文件）
│   ├── xg_dt_backtrader.py
│   ├── xg_gd_backtrader.py
│   ├── xg_hg_backtrader.py
│   ├── xg_mom_backtrader.py
│   ├── xg_more_mom_backtrader.py
│   ├── xg_pz_backtrader.py
│   ├── xg_zcph_backtrader.py
│   ├── xg_mean_var_backtrader.py
│   ├── xg_condi_factor_backtrader.py
│   ├── xg_rank_factor_backtrader.py
│   └── __init__.py                 # 可选：集中 re-export
├── data/
│   ├── 历史数据/                   # 标的日线 parquet（{代码}.parquet）
│   ├── stock_data/                 # 可选备选路径（部分引擎）
│   ├── 指数数据/                   # 指数（parquet/xlsx/csv/json）
│   └── {代码}.parquet              # 可选：直接放 data/
└── 策略模型/                       # save_backtrader_data 导出根目录（自动创建）

2.2 依赖

• Python ≥ 3.8
• pandas、numpy
• pyarrow（读 .parquet，数据为 parquet 时必需）
• xg_mean_var_backtrader 引擎额外需 scipy（optimize.minimize，SLSQP 最大化夏普）；openpyxl（写 xlsx）
• xg_condi_factor_backtrader / xg_rank_factor_backtrader 引擎的自定义因子公式依赖通达信函数库 xg_tdx_func（from xg_tdx_func.xg_tdx_func import *），需把含 xg_tdx_func.py 的目录加入路径

pip install pandas numpy pyarrow scipy openpyxl

2.3 最小可用（一行验证）

from xg_quant_backtrader.xg_mom_backtrader import xg_mom_backtrader
bt = xg_mom_backtrader()          # 全部默认参数
print(type(bt).__name__)          # xg_mom_backtrader

三、数据字段与数据目录（10 引擎通用）

> 全部 10 引擎共用同一套数据规范。差异仅在个别引擎对行数的强制要求（动量/海龟类需较长历史；因子类用日线 OHLCV 即可）。

3.1 必需字段（OHLCV）

3.2 推荐字段

> 行数要求：多数引擎 _load_single_stock 要求单标的数据 > 50 行（动量、海龟等需足够历史）；xg_condi_factor/xg_rank_factor 因子引擎对行数较宽松但需足够算指标。指数仅需 date+close。

3.3 本地标的路径（引擎自动依次尝试）

data/历史数据/{代码}.parquet
data/stock_data/{代码}.parquet   # 部分引擎支持
data/{代码}.parquet              # 部分引擎支持

3.4 指数本地路径（data/指数数据/{指数代码}）

{代码}.parquet → {代码}.xlsx → {代码}.csv → {代码}.json   # 多格式依次回退

四、统一数据注入与管理（10 引擎通用）

每个引擎都内置「标的注入」；除 xg_rank_factor_backtrader 外均内置「指数注入」。当 use_custom_data=True / use_custom_index_data=True 时使用注入数据，否则走本地目录读取。

4.1 标的数据注入（7 种，全部引擎通用）

from xg_quant_backtrader.xg_mom_backtrader import xg_mom_backtrader
bt = xg_mom_backtrader(use_custom_data=True)

bt.add_stock_data_from_dataframe('159915.SZ', df)          # DataFrame
bt.add_stock_data_from_excel('159915.SZ', 'x.xlsx')        # Excel
bt.add_stock_data_from_csv('159915.SZ', 'x.csv')           # CSV
bt.add_stock_data_from_json('159915.SZ', 'x.json')         # JSON
bt.add_stock_data_from_dict('159915.SZ', {...})            # dict
bt.add_stock_data_from_parquet('159915.SZ', 'x.parquet')   # parquet
bt.add_stock_data_from_bytes('159915.SZ', raw_bytes)       # bytes

4.2 指数数据注入（7 种，rank_factor 除外）

方法名同标的，仅前缀改为 add_index_data_from_。具体为（标准引擎族 8 个 + 条件因子 condi 引擎均内置，rank_factor 引擎无指数注入）：

4.3 管理接口

五、交易撮合规则（10 引擎通用）

> 所有引擎遵循 A 股/场内 ETF 的整手撮合口径：

> ⚠️ 例外：xg_dt_backtrader 为多标的独立资金池（每标的分到 cash/len(stock_list)，互不挪用）；其余为单一整体资金池。

六、统一回测输出与导出

所有引擎运行 run_backtest() 后可用同一组 getter 取数，用 generate_report()/save_backtrader_data() 落盘。

6.1 标准引擎族 getter（8 个标准引擎均有，均含 vectorized_backtest）

6.2 因子引擎族 getter（condi/rank 的取数接口，主循环在 run_backtest 内联）

6.3 落盘接口

6.4 基准口径

多数引擎基准 = 等权/按配置权重「买入持有不动」 的净值曲线（calculate_benchmark_curve，标准引擎族），用于评估策略相对“躺平”的增益；指数 index_stock 另作大盘择时或绩效参考。

七、引擎①：定投 xg_dt_backtrader（DCA + 做T）

7.1 定位

定期定额 + 逢跌/逢涨做T。适合长线定投者：以固定节奏买入长期底仓，同时在波动中做T摊薄成本。

7.2 核心逻辑（每日）

• 定投信号 generate_dca_signals：每到 dt_interval 交易日触发，按 dt_type(金额/数量/百分比) × dt_value 买入。
• 做T generate_trade_signals：涨 ≥ sell_zdf(+3%) 止盈卖出约 trade_value；跌 ≤ buy_zdf(-3%) 补回。
• 独立资金池：每标的分得 cash/len(stock_list)。

7.3 关键参数

start_date/end_date/stock_list/index_stock/cash/comm、dt_interval(定投周期)、dt_type/dt_value(定投口径)、sell_zdf/buy_zdf/trade_value(做T)、max_workers、use_custom_data/use_custom_index_data。

7.4 快速上手

from xg_quant_backtrader.xg_dt_backtrader import xg_dt_backtrader
bt = xg_dt_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['513100.SH', '513500.SH'], cash=100000,
    dt_interval=20, dt_type='金额', dt_value=1000,
    sell_zdf=0.03, buy_zdf=-0.03, trade_value=1000,
)
bt.run_backtest()
print(bt.generate_report())
bt.save_backtrader_data(user='定投示例')

八、引擎②：网格 xg_gd_backtrader（网格 + 做T）

8.1 定位

期初打底仓 + 网格高抛低吸 + 日内做T。适合震荡市：按档位涨时卖一档、跌时买一档，赚波动钱。

8.2 核心逻辑（每日）

• 初始建仓：首日按 init_position_ratio_list 比例建底仓。
• 网格档位 calculate_grid_prices/calculate_grid_step：现价涨到某卖出档→卖一档；跌到某买入档→买一档。
• 中枢重置：触及边界后重置网格中枢。
• 做T：日内涨 ≥ sell_zdf 止盈卖、跌 ≤ buy_zdf 止损买。

8.3 关键参数（网格为 per-stock 列表，与 stock_list 一一对应）

gd_interval(每日检查间隔，默认 1)、gd_bc_type_list(步长类型: 百分比/差值/ATR)、gd_buy_bc_list(买入阈值列表)、gd_sell_bc_list(卖出阈值列表)、gd_atr_ratio_list/gd_atr_period_list(ATR 步长的倍数/周期)、gd_type_list/gd_value_list(单档金额口径，用 calculate_order_amount)、init_position_ratio_list(初始底仓比例)、sell_zdf/buy_zdf/trade_value(做T)。

> ⚠️ 反直觉符号约定（务必核对源码，勿凭直觉填）：
> - gd_buy_bc_list 填正值（默认 [0.03, 0.02]），内部 sell_step = gd_buy_bc，决定卖出档 → 涨 gd_buy_bc 即高抛卖出；
> - gd_sell_bc_list 填负值（默认 [-0.02, -0.015]），内部 buy_step = abs(gd_sell_bc)，决定买入档 → 跌 gd_sell_bc 即低吸买入；
> - 即「正的是卖档、负的是买档」，字段名里带 buy/sell 与直觉相反。

8.4 快速上手

from xg_quant_backtrader.xg_gd_backtrader import xg_gd_backtrader
bt = xg_gd_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['513100.SH', '513500.SH'], cash=100000,
    gd_interval=1,
    gd_bc_type_list=['百分比', '百分比'],
    gd_buy_bc_list=[0.02, 0.015],   # 正值 → 卖出档：涨2%/1.5% 卖
    gd_sell_bc_list=[-0.03, -0.02], # 负值 → 买入档：跌3%/2% 买
    gd_type_list=['金额', '金额'], gd_value_list=[1000, 1000],
    init_position_ratio_list=[0.1, 0.1],
)
bt.run_backtest(); print(bt.generate_report())

九、引擎③：海龟 xg_hg_backtrader（唐奇安 + N值）

9.1 定位

经典海龟交易法则：唐奇安通道突破入场 + ATR/N 值定仓 + 2N 止损 + 金字塔加仓 + 做T。

9.2 核心逻辑

• calculate_turtle_signals：突破 entry_period 日高点 → 买入；跌破 exit_period 日低点 → 清仓（shift(1) 避免未来函数）。
• N 值 = 真实波幅 ATR 的 EWM；unit_size = (每标资金 × risk_per_trade)/(N × risk_per_unit)。
• 价格每向有利方向移动 add_unit_threshold(默认 0.5N) 金字塔加仓，至多 max_units 仓；2N 止损。
• 内部固定 use_long_system=False（仅做多）、adj_type='none'、enable_dt=True。

9.3 关键参数

entry_period(突破周期 20)、exit_period(离场周期 10)、n_period(N=ATR周期 20)、risk_per_trade(总资金风险 1%)、risk_per_unit(单单位风险 2%)、max_units(最大加仓 4)、add_unit_threshold(加仓间隔 0.5N)、做T sell_zdf/buy_zdf/trade_value。

9.4 快速上手

from xg_quant_backtrader.xg_hg_backtrader import xg_hg_backtrader
bt = xg_hg_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['513100.SH', '513500.SH'], cash=100000,
    entry_period=20, exit_period=10, n_period=20,
    risk_per_trade=0.01, risk_per_unit=0.02,
    max_units=4, add_unit_threshold=0.5,
)
bt.run_backtest(); print(bt.generate_report())

十、引擎④：动量 xg_mom_backtrader（动量轮动）

10.1 定位

单动量模型（带 R² 加权的线性回归斜率）打分 + 排名持有前 buy_rank + 止盈。适合趋势轮动。

10.2 核心逻辑

• calculate_momentum_score：log(close) 带权线性回归斜率 × R² 年化 → 每标动量分。
• 分数区间过滤（min_mom~max_mom）→ 排名前 buy_rank 为目标 → 先卖后买轮动。
• 止盈：当日 zdf ≥ sell_zdf → 按 sell_amount 卖出部分（calculate_sell_shares_by_amount）。
• mom_type(金额/数量/百分比)×mom_value 决定买入预算。

10.3 关键参数

mom_type/mom_value(资金分配)、mom_daily(回归窗口 25)、min_mom/max_mom(分数区间)、buy_rank(持有前 N)、sell_zdf/sell_amount(止盈)。

10.4 快速上手

from xg_quant_backtrader.xg_mom_backtrader import xg_mom_backtrader
bt = xg_mom_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    mom_type='百分比', mom_value=0.5, mom_daily=25,
    buy_rank=1, min_mom=0, max_mom=5, sell_zdf=0.03, sell_amount=1000,
)
bt.run_backtest(); print(bt.generate_report())

十一、引擎⑤：综合动量 xg_more_mom_backtrader（六大动量 + 多层风控）

11.1 定位

集成 六大动量模型 + 排名轮动 + 大盘择时/动量区间/开平仓条件/盘中止盈 的多级过滤动量框架，动量引擎中最完整的一档。

11.2 核心逻辑

• 六大动量模型 calculate_momentum_score_1~6（线性回归加权 / 现价÷N日前价 / 现价÷N均线 / 现价÷N日前M均线 / 短长均线交叉 / 滞后均线交叉），calculate_momentum 按 mom_models 分发。
• 排名取第 max_rank~min_rank 名 → 先卖后买轮动。
• 五层可独立开关风控：大盘择时 check_index_condition、动量区间过滤(enable_mom_filter)、开仓条件 check_buy_condition、平仓条件 check_sell_condition、盘中止盈。
• 交易类型全集：大盘择时清仓/轮动卖出/轮动买入/条件平仓/止盈卖出（无“初始建仓”，进排名即买）。

11.3 关键参数

enable_index_timing/index_mean_line/index_not_trader/index_condition_type/index_offset(择时)、mom_models(动量1~6)/mom_daily/period/short_ma/long_ma、mom_type/mom_value、enable_mom_filter/max_value/mini_value、max_rank/min_rank、enable_buy_condition/enable_sell_condition(+buy_condition_type/buy_period/buy_period_ratio/buy_offset/sell_condition_type/sell_period/sell_period_ratio/sell_offset)、sell_zdf/sell_amount、interval。

> ⚠️ 无 save_to_json；JSON 落盘用 get_all_data() / get_backtrader_data() 手动 dump。

11.4 快速上手

from xg_quant_backtrader.xg_more_mom_backtrader import xg_more_mom_backtrader
bt = xg_more_mom_backtrader(
    start_date='20250101', end_date='20261231',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    mom_models='动量1', mom_type='百分比', mom_value=0.5,
    max_rank=1, min_rank=1, interval=1,
)
bt.run_backtest(); print(bt.generate_report())

十二、引擎⑥：资产配置 xg_pz_backtrader（固定配置 + 做T）

12.1 定位

按你给的固定配置（百分比/金额/数量 × weight_list）期初一次性建仓买入持有，再用做T增厚。不做轮动、不清仓。

12.2 核心逻辑

• 初始建仓：首日按 dt_type × weight_list 配置买入。
• 每日做T：涨 ≥ sell_zdf 止盈卖、跌 ≤ buy_zdf 止损买，各约 trade_value 金额；其余持有不动。
• 交易类型全集：初始建仓/止盈卖出/止损买入。

12.3 关键参数

dt_type(百分比/金额/数量)、weight_list(每标配置权重，与 stock_list 对应)、sell_zdf/buy_zdf/trade_value(做T)。

12.4 快速上手

from xg_quant_backtrader.xg_pz_backtrader import xg_pz_backtrader
bt = xg_pz_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    dt_type='百分比', weight_list=[0.4, 0.4, 0.2],
    sell_zdf=0.03, buy_zdf=-0.03, trade_value=1000,
)
bt.run_backtest(); print(bt.generate_report())

十三、引擎⑦：资产配置平衡 xg_zcph_backtrader（固定市值再平衡 + 做T）

13.1 定位

固定市值目标配置 + 定期再平衡 + 做T。当组合某标的市值偏离目标比例超阈值时拉回，维持纪律性配置。

13.2 核心逻辑

• 目标值随净值变化：目标市值 = 总净值 × 目标权重，随净值滚动更新。
• 再平衡：每 interval 交易日检查——实际占比偏离目标权重超 deviation_list 阈值 → 买卖拉回。
• 做T：每日涨跌做T增厚（可独立关闭）。

13.3 关键参数

dt_type/weight_list(目标配置)、deviation_list(每标偏离阈值)、interval(再平衡周期)、sell_zdf/buy_zdf/trade_value(做T)。

13.4 快速上手

from xg_quant_backtrader.xg_zcph_backtrader import xg_zcph_backtrader
bt = xg_zcph_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    dt_type='百分比', weight_list=[0.35, 0.35, 0.3],
    deviation_list=[0.1, 0.1, 0.05], interval=20,
    sell_zdf=0.03, buy_zdf=-0.03, trade_value=1000,
)
bt.run_backtest(); print(bt.generate_report())

十四、引擎⑧：均值方差 xg_mean_var_backtrader（马科维茨 MPT）

14.1 定位

资产配置型（非信号交易型）：用马科维茨均值方差优化，SLSQP 最大化夏普比率求解最优权重，定期再平衡。依赖 scipy，是全包唯一需 scipy 的引擎。

14.2 核心逻辑

• align_data(共同交易日交集) → get_returns_matrix(近 lookback_days 收益率) → calculate_optimal_weights_ts(逐期权重) → optimize_max_sharpe(SLSQP 最大夏普，rf=0.02，权重∈[min_weight,max_weight] 且和为 1)；negative_sharpe 为目标函数。
• 初始建仓等权，之后每 interval 交易日按最优权重再平衡；|目标-当前|<总资产×0.5% 忽略。
• 独有 get_weight_history() 权重历史；导出目录含「权重历史」子目录。
• 兜底：累计收益样本 < 30 天 → 退化为等权。

> ⚠️ lambda_risk 当前仅留档打印、未进入目标函数（目标 = −夏普）。

14.3 关键参数

lookback_days(回看窗口 60)、max_weight/min_weight(权重上下限)、interval(再平衡周期)、cash/comm、use_custom_data 等。依赖：pip install scipy。

14.4 快速上手

from xg_quant_backtrader.xg_mean_var_backtrader import xg_mean_var_backtrader
bt = xg_mean_var_backtrader(
    start_date='20240101', end_date='20261231',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    lookback_days=60, max_weight=0.6, min_weight=0.05,
    interval=5,  # 每5个交易日再平衡
)
bt.run_backtest()
print(bt.generate_report())
print(bt.get_weight_history())   # 独有权重历史

十五、引擎⑨：条件因子 xg_condi_factor_backtrader（买入/卖出条件 + 排序因子）

15.1 定位

条件因子轮动：用「买入条件筛出候选 + 排序因子排出强弱 + 卖出条件离场 + 涨幅止盈」经典条件选股流水线。buy_condi_factor 用 and/or/not + 比较符组合；条件结果经 _is_bool_like 宽松识别（1/0、True/False、"大于0" 等均支持）。

15.2 核心逻辑

• 自定义因子 user_factor_cacal(通达信风格，MA/IF 等) → 合并进因子表。
• filter_by_buy_conditions 按 buy_condi_factor and 过滤候选 → apply_rank_factors 按 rank_factor 排序取前 hold_stock_limit → filter_by_sell_conditions 按 sell_condi_factor or 平仓 → 止盈 sell_type/sell_zdf/sell_value。
• 条件判定核心 check_factor_condition/_check_factor_condition_single；模块级函数 parse_factor_config/parse_config_with_bool、类内 replace_bool_values。
• 主循环在 run_backtest 内联（无 vectorized_backtest）。

15.3 关键参数

is_open_user_factor/user_factor_list/user_factor_cacal(自定义因子)、buy_condi_factor/rank_factor/sell_condi_factor(条件字典)、trader_type/trader_value、hold_stock_limit、sell_type(none/金额/数量/百分比)/sell_zdf/sell_value。

15.4 快速上手

from xg_quant_backtrader.xg_condi_factor_backtrader import xg_condi_factor_backtrader
bt = xg_condi_factor_backtrader(
    start_date='20250101', end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    user_factor_cacal={
        "收盘价大于5日均线": "IF(df['close']>MA(df['close'],5),True,False)",
    },
    buy_condi_factor={"价格在5均线上": {"选择类型": "and", "选择方向": "等于", "值": True}},
    rank_factor={"连续上涨天数": "降序"},
    sell_type='百分比', sell_zdf=0.03, sell_value=0.5,
)
bt.run_backtest(); print(bt.generate_report())

十六、引擎⑩：排序多因子 xg_rank_factor_backtrader（因子加权 + 排名）

16.1 定位

排序多因子轮动：自定义因子加权打分 → 排序取前 N → 止盈轮动。与条件因子族同源，更侧重「综合加权排名」（rank_factor 用「相关性+权重」）。

16.2 核心逻辑

• 自定义因子 user_factor_cacal 合并进因子表；Bool 值按 _convert_to_bool/_convert_factor_value_for_rank 转换（1/0、正负）。
• filter_by_buy_conditions 按 buy_condi_factor and 过滤（可选）→ calculate_rank_score 按 rank_factor(正/负相关 × 权重) 加权打分 → 综合排序 → get_trading_stocks 取前 hold_stock_limit。
• 卖出：calculate_sell_shares_by_amount/_by_percent/_by_count/_all + check_take_profit 止盈。
• 主循环在 run_backtest 内联（无 vectorized_backtest）。

16.3 关键参数

is_open_user_factor/user_factor_cacal、is_open_buy_condi/buy_condi_factor、rank_factor(相关性+权重)、total_factor_rank(无/降序/升序)、hold_stock_limit、trader_type/trader_value、sell_type(none/金额/数量/百分比)/sell_zdf/sell_value。

> ⚠️ xg_rank_factor_backtrader 无指数注入（只做标的因子轮动）。

16.4 快速上手

from xg_quant_backtrader.xg_rank_factor_backtrader import xg_rank_factor_backtrader
bt = xg_rank_factor_backtrader(
    start_date='20250101', end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'], cash=100000,
    user_factor_cacal={"20日动量": "df['close']/REF(df['close'],20)-1"},
    buy_condi_factor={"20日动量": {"选择类型": "and", "选择方向": "大于", "值": 0}},
    rank_factor={"20日动量": {"相关性": "正相关", "权重": 1}},
    hold_stock_limit=2, sell_type='金额', sell_zdf=0.03, sell_value=1000,
)
bt.run_backtest(); print(bt.generate_report())

十七、模型选型速查

十八、函数清单总表（精确分组）

> 分组口径：全部 10 引擎真公共 36 + 标准引擎族 8 个公共 55 + 因子引擎族 2 个公共 54，引擎各自“组公共 + 独有 = 类内方法总数”。

18.1 全部 10 引擎真公共方法（36 个）

18.2 标准引擎族（8 个：dt/gd/hg/mom/more_mom/pz/zcph/mv）在两两公共 55 中、且非全平台公共的部分

> 即标准引擎普遍具备、但因子引擎(condi/rank)没有的富集接口，共 19 个：vectorized_backtest、calculate_benchmark_curve、calculate_sell_shares、get_all_data、get_backtest_summary、get_daily_positions、get_portfolio_history、get_stock_results、get_trade_log、get_annual_performance_df、adjust_price、save_to_json(more_mom 例外)、指数注入 add_index_data_from_*(7)、clear_index_data、has_index_data、get_index_data_info。

> 其中 save_to_json、get_all_data、get_backtest_summary、get_daily_positions、get_portfolio_history、get_stock_results、get_trade_log、get_annual_performance_df 在 more_mom 均存在；唯独 more_mom 无 save_to_json。

18.3 因子引擎族（2 个：condi_factor / rank_factor）在两两公共 54 中、且非全平台公共的部分

> 因子族独有框架（非全平台 36）：_validate_factor_config _validate_params _print_config _print_results _parse_date _normalize_factor_name _is_bool_string _is_bool_like _convert_to_bool _check_factor_condition_single check_factor_condition _calculate_buy_hold_net_value _calculate_index_net_value filter_by_buy_conditions calculate_commission adjust_price save_to_json _record_daily_position。

> ⚠️ rank_factor 无指数注入（其公共 54 中不含 add_index_data_from_*，由 condi 独有补齐差异见 18.4）。

18.4 各引擎独有方法（“组公共”之外的部分）

xg_dt_backtrader：generate_dca_signals generate_trade_signals calculate_benchmark_curve adjust_price（主循环 vectorized_backtest 在标准组公共内）

xg_gd_backtrader：calculate_atr calculate_grid_prices calculate_grid_step calculate_order_amount _validate_list_params calculate_sell_shares_all _normalize_index_dataframe

xg_hg_backtrader：calculate_turtle_signals _normalize_index_dataframe

xg_mom_backtrader：calculate_momentum_score calculate_sell_shares_all calculate_sell_shares_by_amount _normalize_index_dataframe

xg_more_mom_backtrader：六大动量打分 calculate_momentum_score_1 calculate_momentum_score_2 calculate_momentum_score_3 calculate_momentum_score_4 calculate_momentum_score_5 calculate_momentum_score_6（即 1~6）calculate_momentum calculate_buy_amount_per_stock check_index_condition check_buy_condition check_sell_condition calculate_sell_shares_all calculate_sell_shares_by_amount adjust_price

xg_pz_backtrader：calculate_sell_shares_all _normalize_index_dataframe adjust_price

xg_zcph_backtrader：calculate_sell_shares_all calculate_sell_shares_by_amount _normalize_index_dataframe adjust_price

xg_mean_var_backtrader：align_data get_returns_matrix negative_sharpe optimize_max_sharpe calculate_optimal_weights_ts get_weight_history calculate_sell_shares_by_value _normalize_index_dataframe adjust_price

xg_condi_factor_backtrader：replace_bool_values add_index_data_from_*(7) clear_index_data has_index_data get_index_data_info _normalize_index_dataframe _process_stock_data apply_rank_factors filter_by_sell_conditions calculate_sell_shares calculate_commission；顶层函数 parse_factor_config parse_config_with_bool

xg_rank_factor_backtrader：_convert_factor_value_for_rank calculate_rank_score get_trading_stocks calculate_sell_shares_by_amount calculate_sell_shares_by_percent calculate_sell_shares_by_count calculate_sell_shares_all check_take_profit calculate_commission save_to_json adjust_price

十九、注意事项与 FAQ

Q1：为什么 xg_dt_backtrader 用独立资金池，其它是单一池？
定投是按标的独立记账的“多账户”逻辑；网格/动量/配置类引擎整体组合运作。注意 cash 语义不同。

Q2：网格的 buy/sell 档位怎么填？
gd_buy_bc_list 填正（涨到该档即高抛卖出）、gd_sell_bc_list 填负（跌到该档即低吸买入），两者符号勿填反；卖档看 gd_buy_bc（正），买档看 gd_sell_bc（负取绝对值）。

Q3：均值方差要不要 scipy？
要。仅此一个引擎依赖 scipy（optimize.minimize）。其余 9 个仅 pandas/numpy。

Q4：more_mom 为什么没有 save_to_json？
该引擎未实现；需要 JSON 用 get_all_data()/get_backtrader_data() 手动 dump。

Q5：condi 和 rank 的 getter 为什么比标准引擎少？
它们是“因子引擎族”，主循环在 run_backtest 内联，取数接口走 get_backtrader_data()/generate_report() 而非富 getter 集。

Q6：数据最少要多少行？
建议 > 50 行；动量/海龟/因子引擎对历史长度敏感，越长越准。

Q7：如何只读本地目录数据而非注入？
把 use_custom_data/use_custom_index_data 保持 False（默认），并把 {代码}.parquet 放 data/历史数据/ 即可。

> 使用教程（16 章 + 逐引擎详解 + 附录总表）：references/小果综合多策略回测系统助手.md。