小果定投量化策略回测系统专家

一、系统概述

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

1.1 系统定位

小果定投量化策略回测系统（xg_dt_backtrader）是一套专为定期定额定投 + 涨跌做T增厚收益设计的专业级量化回测框架。它以「每隔 N 个交易日定额买入一次」为底仓积累主线，叠加「当日大跌买入 / 当日大涨卖出」的做T规则在震荡中反复降低成本，并以多标的独立资金池 + 组合级汇总的方式输出完整绩效。研究者可用它验证不同定投频率/金额/做T阈值下的收益差异，回答"怎么定投更划算"这类问题。

1.2 核心策略逻辑（每个交易日）

系统按每只标的独立账户逐日决策，资金池 = 总资金 ÷ 标的数：

① 定投信号：距上次定投满 dt_interval 个交易日 → 当天按 dt_type/dt_value 定额买入（底仓积累）
② 做T买入：当日涨跌幅 ≤ buy_zdf（如跌 3%）且现金充足 → 买入 trade_value 金额（逢跌吸筹）
③ 做T卖出：当日涨跌幅 ≥ sell_zdf（如涨 3%）且已有持仓 → 卖出 trade_value 金额（逢涨止盈）
④ 全部成交均按 100 份整手、先扣手续费；随后记录现金/持仓/累计成本/浮盈亏
⑤ 组合级汇总：把各标的在共同交易日的现金、持仓、市值相加，叠加基准曲线输出净值

> 先做T后定投；做T卖出只减持仓、做T买入与定投只增持仓；定投是「固定节奏」，做T是「涨跌触发器」，两者互不干扰。

1.3 定投与做T的协同逻辑

• 定投（长期底仓）：纪律化买入，摊平成本，解决"择时难"问题；
• 做T（波段增强）：在既有底仓上做"高抛低吸"，单次 T 金额 = trade_value，收益来自震荡价差；
• 定投买入的资金计入累计成本 investment_cost，用于计算持仓浮盈亏；做T买入同样计入成本，做T卖出只回收现金不减少成本口径（成本口径用于观察投入额）。
• 每个标的的资金池是独立上限：当现金不足以支付当期定投金额时自动跳过（记 ⚠️定投资金不足），不会挪用其它标的资金。

1.4 设计哲学

• 解耦与复用：数据加载、定投信号、做T信号、交易撮合、绩效评估各环节解耦，可独立替换。
• 透明可解释：每个交易日的买卖动作（定投买入/做T买入/做T卖出）、价格、手续费、原因均写入日志可追溯。
• 灵活可扩展：三种定投方式、可调做T阈值、标的与指数双重自定义数据源、支持子类重写做个性化规则。

二、安装与运行环境

2.1 安装包

教程 https://gitcode.com/qq_50882340/xg_dt_backtrader

2.2 依赖

• pandas
• numpy
• pyarrow（读取本地 parquet 历史数据用）
• openpyxl（导出 Excel 用）

2.3 包结构

推荐以「包」方式导入：

xg_dt_backtrader/
├── __init__.py                  # 空文件即可
└── xg_dt_backtrader.py          # 主模块（定投回测类）

2.4 导入方式

from xg_dt_backtrader.xg_dt_backtrader import xg_dt_backtrader

2.5 数据目录要求（使用内置数据源时）

系统默认从脚本同级的 data/ 目录读取本地数据：

data/
├── 历史数据/
│   ├── 513100.SH.parquet       # 标的日线数据
│   └── ...
└── 指数数据/
    ├── 000300.SH.parquet       # 指数数据（parquet 优先）
    ├── 000300.SH.xlsx          # 也支持 Excel / CSV / JSON
    └── ...

> 若不想准备本地数据，可用自定义数据注入（标的 + 指数各自独立注入，见「十、自定义数据详解」），系统自动切换到内存数据源。

2.6 数据字段要求

必须字段：

推荐字段：

三、初始化参数完整参考

> 以下为 __init__ 方法全部参数详细说明。

3.1 时间与标的 (Time & Universe)

3.2 资金与费用 (Capital & Cost)

3.3 定投参数 (DCA / Regular Investment)

dt_type 与 dt_value 匹配表：

> 例：2 只标的、总资金 10 万 → 每标资金池 5 万。dt_type='百分比', dt_value=2 表示每期每标投入 5 万 × 2% = 1000 元。无论哪种方式，实际买入都以「现金是否足够」且「凑满一手(100份)」为前提，按 100 份整数倍成交。

3.4 做T参数 (T+0 Band Trading)

做T信号判定表：

> 设置建议：把 buy_zdf 设成 sell_zdf 的相反数并配套（如 ±3%），在震荡市实现"跌了买、涨了卖"的网格做T。若只想定投不想做T，可把 sell_zdf/buy_zdf 设成极端值（如 ±99）或 0 结合 trade_value 判断。

3.5 运行与数据源 (Runtime & Data Source)

3.6 内部固定参数（构造时自动设置，一般不修改）

四、数据加载与处理详解

4.1 标的（股票/ETF）数据来源优先级

get_stock_data(stock_code) 取数顺序：

1. 自定义标的源：use_custom_data=True 且该代码已注入 → 从内存 _custom_data_cache 读取；
2. 本地 parquet：读取 data/历史数据/{code}.parquet。

两种路径均执行统一清洗：截取 [start_date, end_date] 区间 → 日期升序 → 剔除 close<=0 或 open<=0 行 → adjust_price（当前为 none 原样返回）→ 重算 zdf = close.pct_change()。

4.2 多线程加载

get_all_stock_data() 用 ThreadPoolExecutor（线程数 = max_workers）并发加载全部标的，打印每只标的的成功/失败、数据范围与价格范围，返回 {code: DataFrame}。

4.3 指数数据来源（五级回退）

get_index_data() 依次尝试以下来源，命中即返回：

> 指数数据只用于输出展示/留档（导出目录的「指数数据」），不参与策略基准对比；策略对照基准是「等权持有不动」曲线。

4.4 基准曲线（等权重持有不动）

calculate_benchmark_curve(all_data)：取全部标的的共同交易日，每只归一化为「首日=1」后逐日等权平均，得到"等权买入持有不动"净值曲线，作为策略的对照基准，用于计算超额收益。

五、定投与做T信号生成详解

5.1 定投信号（generate_dca_signals）

5.2 做T信号（generate_trade_signals）

5.3 信号触发顺序（每日循环内）

做T买入 → 做T卖出 → 定投买入；买入需要 现金 ≥ 应投金额，卖出需要 持仓 > 0，最终以「实际能成交」为准。

六、交易执行详解

6.1 买入撮合（calculate_buy_shares）

calculate_buy_shares(amount, price) -> (shares, actual_cost)

• 先扣除手续费：买入金额 = amount ÷ (1 + comm)；
• 按 100 份整数倍取整：shares = floor(买入金额 ÷ price ÷ 100) × 100；
• 不足一手（< 100 份）则买 0；
• 若含手续费的实际成本超可用金额，循环减一手直到不超；
• 返回 (买入份数, 实际成本=市值+手续费)。

6.2 卖出撮合（calculate_sell_shares）

calculate_sell_shares(shares, price, amount) -> (sell_shares, actual_amount)

• 按卖出金额直接折算股数（手续费从卖出金额中扣）：sell_shares = floor(amount ÷ price ÷ 100) × 100；
• 折算不足 100 但按金额够一手时补足 100；卖出份额超过持仓则全部卖出；
• 返回 (卖出份数, 实收金额=市值-手续费)。

6.3 日交易记录字段（trade_log）

七、完整函数清单

> 框架类 xg_dt_backtrader 共 60 个方法，以下按功能模块列出，便于二次开发和深度集成。

7.1 构造与配置

7.2 数据加载与处理

7.3 自定义标的注入（7 种接口）

7.4 自定义标的数据库管理

7.5 自定义指数注入（7 种接口）

7.6 指数数据管理

7.7 定投与做T信号生成

7.8 交易撮合计算

7.9 回测执行

7.10 绩效与数据生成

7.11 数据获取接口

7.12 结果保存

7.13 报告生成

7.14 内部工具方法（供二次开发参考）

八、输出数据结构详解

8.1 绩效指标字段（performance_metrics）

8.2 年度收益统计字段（annual_performance）

8.3 净值曲线字段（equity_curve_data）

8.4 成交统计（trade_data['statistics']）

total_trades、buy_trades、sell_trades、dca_trades（定投买入笔数）、total_buy_amount、total_sell_amount、net_invested（净投入=买-卖）、total_commission、first_trade_date、last_trade_date。

8.5 持仓统计（position_data['statistics']）

total_days、max_holdings、min_holdings、final_holdings、avg_holdings、first_date、last_date、final_return。每日明细还含 investment_cost、daily_pnl、cumulative_pnl、stock_details（逐标的现值/现金/收益）。

8.6 账户统计（account_data['statistics']）

起始/结束日期、总天数、初始资金、期末总资产/现金/持仓、累计投入、总盈亏、总收益率（百分数）、最高/最低总资产与净值、波动率、基准期末净值与总收益。

8.7 文本报告内容（generate_report()）

策略参数（标的/指数/复权/定投/做T/手续费/数据源）→ 各标的盈亏明细 → 汇总持仓 → 收益指标（总/年化/盈亏/波动/手续费）→ 基准对比（含超额）→ 风险指标（回撤/夏普/索提诺/卡尔玛）→ 交易统计（总次数/做T次数/胜率）→ 年度收益统计表。

8.8 导出目录结构

策略模型/定投策略/{user}/
├── 指数数据/      指数数据.xlsx + .json
├── 成交数据/      成交数据.xlsx + .json
├── 持股数据/      持股数据.xlsx + .json
├── 账户数据/      账户数据.xlsx + .json
├── 绩效指标/      绩效指标.xlsx + .json
├── 净值曲线/      净值曲线.xlsx + .json
├── 策略参数/      策略参数.xlsx + .json
└── 年度收益统计/  年度收益统计.xlsx + .json

九、完整实战示例

9.1 示例1：经典定期定额定投（金额模式 + 默认做T）

from xg_dt_backtrader.xg_dt_backtrader import xg_dt_backtrader

bt = xg_dt_backtrader(
    start_date='20250701',
    end_date='20261201',
    stock_list=['513100.SH', '513500.SH'],   # 纳指ETF / 标普500ETF
    index_stock='000300.SH',
    cash=100000,
    comm=0.0001,
    dt_interval=20,        # 每 20 个交易日定投一次
    dt_type='金额',         # 金额定投
    dt_value=1000,         # 每标每期定投 1000 元
    sell_zdf=0.03,         # 涨 3% 做T卖出
    buy_zdf=-0.03,         # 跌 3% 做T买入
    trade_value=1000,      # 每次做T 1000 元
    max_workers=8,
)

bt.run_backtest()
print(bt.generate_report())
bt.save_backtrader_data(user='经典定投')

9.2 示例2：百分比定投 + 关闭做T

bt = xg_dt_backtrader(
    start_date='20240101',
    end_date='20261201',
    stock_list=['159915.SZ', '510300.SH', '518880.SH'],
    cash=300000,
    comm=0.0001,
    dt_interval=30,        # 月度级别定投
    dt_type='百分比',       # 按资金池比例定投
    dt_value=2,            # 每期投入该标资金池的 2%
    sell_zdf=0.99,         # 极大值 → 关闭做T卖出
    buy_zdf=-0.99,         # 极大值 → 关闭做T买入
    trade_value=1000,
    max_workers=4,
)

bt.run_backtest()
print(bt.generate_report())
print("做T交易次数:", bt.get_performance_metrics().get('t_trades', 0))   # 应为 0

9.3 示例3：数量定投 + 注入自定义标的数据

bt = xg_dt_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['513100.SH', '513500.SH'],
    cash=200000,
    dt_interval=10,
    dt_type='数量',          # 按固定份额定投
    dt_value=100,           # 每期定投 100 份
    sell_zdf=0.05,
    buy_zdf=-0.05,
    trade_value=2000,
    use_custom_data=True,   # 显式声明使用自定义数据
)

# 不同格式注入
bt.add_stock_data_from_csv('513100.SH', 'data/513100.csv')
bt.add_stock_data_from_dataframe('513500.SH', df_513500)  # 内存 DataFrame

print("已注入:", bt.get_custom_data_keys())
bt.run_backtest()
print(bt.generate_report())
bt.save_to_json('result/dca_backtest.json')

9.4 示例4：注入自定义指数数据（自定义对比指数）

import pandas as pd

# 构造或读取指数 DataFrame（含 date/close 即可）
index_df = pd.read_csv('data/index_000300.csv')

bt = xg_dt_backtrader(
    start_date='20250701',
    end_date='20261201',
    stock_list=['513100.SH', '513500.SH'],
    index_stock='CUSTOM_INDEX',   # 占位代码（不影响，指数以注入为准）
    cash=100000,
    use_custom_index_data=True,   # 关键：启用自定义指数
)

bt.add_index_data_from_dataframe(index_df)      # 或 add_index_data_from_csv('xxx.csv')
print("指数已注入:", bt.has_index_data())
print(bt.get_index_data_info())   # {'has_data': True, 'rows': N, 'start_date':..., 'source': 'dataframe'}

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

# 恢复本地指数
# bt.clear_index_data()

9.5 示例5：提取结果做二次分析 + 画净值/回撤曲线

bt.run_backtest()

metrics = bt.get_performance_metrics()
curve = bt.get_equity_curve_data()
trades = bt.get_trade_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['total_invested']:,.2f}")
print(f"做T交易次数: {metrics['t_trades']}")
print(f"总手续费: ¥{metrics['total_commission']:,.2f}")

import matplotlib.pyplot as plt
dates = curve['dates']
plt.figure(figsize=(12, 6))
plt.plot(dates, curve['net_value'], label='策略净值', linewidth=2)
if curve.get('benchmark_net_value'):
    plt.plot(dates, curve['benchmark_net_value'], label='基准(持有不动)', linestyle='--')
plt.legend(); plt.xlabel('日期'); plt.ylabel('净值')
plt.title('定投+做T 策略净值曲线'); 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')
plt.xlabel('日期'); plt.ylabel('回撤(%)'); plt.title('策略回撤曲线'); plt.tight_layout(); plt.show()

9.6 示例6：按标的查看回测明细 + 年度绩效

bt.run_backtest()

# 各标的独立结果
for stock, res in bt.get_stock_results().items():
    print(f"{stock}: 最终资产¥{res['final_value']:,.2f}, "
          f"最终持仓{res['final_holdings']:.0f}份, 累计投入¥{res['total_invested']:,.2f}")

# 年度绩效
annual_df = bt.get_annual_performance_df()
print(annual_df[['year', 'total_return', 'annual_return', 'max_drawdown', 'sharpe_ratio', 't_trades']])

十、自定义数据详解

10.1 标的注入后系统自动做的事

add_stock_data_from_*（标的）最终都调用 add_stock_data_from_dataframe → _normalize_dataframe：

• 日期列：识别含 date/日期 的列或 DatetimeIndex，统一转 datetime 并升序；
• 缺列补齐：close/high/low/open/volume 任一缺失 → 先按列名模糊匹配，否则补空列（NaN）；
• 代码列：自动补 证券代码；
• 涨跌幅：缺 zdf 时用 close.pct_change() 自动计算；
• 复权因子：含 preClose 时自动用 close/preClose 累计生成 adj_factor。

10.2 指数注入说明

• 指数注入走同一套 _normalize_dataframe（以 INDEX 为占位代码），只要求含 date 与 close（close>0）；
• 注入成功后 use_custom_index_data 自动置 True，get_index_data() 优先返回注入数据；
• get_index_data_info() 额外返回 source（dataframe/csv/excel/json/...）标识来源。

10.3 注入成功判定与验证

> 建议：构造时把 use_custom_data=True / use_custom_index_data=True 传入，可避免中途依赖本地文件。

十一、常见问题与 FAQ

十二、高级技巧与二次开发

12.1 参数调优建议

12.2 定投节奏设计

• 日定投：dt_interval=1（每个交易日买入）；
• 周定投：dt_interval≈5；双周定投：≈10；月定投：≈20~22；
• 定投间隔与做T阈值独立，可组合出「周定投 + 日做T」等混合形态。

12.3 自定义定投/做T规则

继承 xg_dt_backtrader 后重写信号方法，即可换成任意定投/加仓逻辑：

from xg_dt_backtrader.xg_dt_backtrader import xg_dt_backtrader

class MyDCA(xg_dt_backtrader):
    def generate_dca_signals(self, df, per_stock_cash):
        df = super().generate_dca_signals(df, per_stock_cash)
        # 例：只在"净值低于 120 日线"时定投（越跌越买）
        df['ma120'] = df['close'].rolling(120).mean()
        df.loc[df['close'] > df['ma120'], 'is_dca_day'] = False
        df.loc[df['close'] > df['ma120'], 'dca_amount'] = 0
        return df

    def generate_trade_signals(self, df):
        df = super().generate_trade_signals(df)
        # 例：增加"持仓浮盈达 5% 才做T卖出"的风控
        # ... 自定义列 is_sell_t 即可
        return df

bt = MyDCA(start_date='20240101', end_date='20261201', dt_interval=10, dt_value=1000)
bt.run_backtest()
print(bt.generate_report())

12.4 自定义交易/成本规则

重写 calculate_buy_shares() / calculate_sell_shares() 可自定义整手规则、印花税、最低佣金等；重写 vectorized_backtest() 可在不改变数据层的前提下整体替换交易引擎。

十三、技术说明与提示

• performance_metrics 中的比率多为小数（如 total_return=0.25 表示 25%）；报告打印时已 ×100；position_data/account_data 里的 total_return 是百分数口径，直接从 dict 取值时注意区分。
• 年化按 365.25 天折算；夏普/索提诺/波动率按 250 个交易日年化；无风险利率固定 0.02。
• total_invested 只统计 定投买入 金额，做T买入计入成本但不计入该字段；t_trades 为做T总笔数（买+卖）。
• 回测以每只标的数据的自身交易日序列生成定投日；组合净值按标的间共同交易日汇总。
• 指数数据仅用于输出留档，策略对照基准为「等权持有不动」曲线。
• 源码当前固定 adj_type='none'，若需前复权/后复权可在 adjust_price 中扩展。

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