小果均值方差回测系统专家

一、系统概述

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

1.1 系统定位

小果均值方差最优资产组合权重再平衡回测系统（xg_mean_var_backtrader）是一套忠实还原马科维茨现代投资组合理论（Modern Portfolio Theory, MPT）的专业级量化资产配置回测框架。它以「过去 lookback_days 天的历史收益率」估计各资产的期望收益与协方差矩阵，通过「均值方差优化（SLSQP 最大化夏普比率）」在每只标的权重限制 [min_weight, max_weight] 内求解当期最优资产权重，随后每 interval 个交易日将实际持仓再平衡到该目标权重，把「该买多少 / 该卖多少」由量化出的组合风险收益最优解来界定。

与其它策略系统最大的不同在于：均值方差系统不做择时、不靠单标的方向判断，而是聚焦组合层面的资产配置——把资金在多个低相关资产间按「期望收益÷波动风险」最优配比，在给定风险偏好约束下最大化单位风险所获得的超额回报（夏普比率）。单一资金池整体运作（不把 cash 均分到各标的），每日记录各标的实际/目标权重，交易类型为「初始建仓」与「再平衡买入/卖出」，无做T、无止损止盈概念。

> 均值方差核心思想：不要把鸡蛋放在一个篮子里，且每个篮子的大小应由「收益÷风险」的科学配比而非拍脑袋决定。 组合的风险不仅取决于各资产自身波动，更取决于资产间的协方差（相关性）——低相关资产的搭配可在不牺牲太多收益的前提下显著降低组合波动。

1.2 核心策略逻辑（每 interval 交易日执行）

均值方差框架在每个共同交易日的运行分两阶段：组合初始化（一次性） 与 定期再平衡（每 interval 日）：

一、组合初始化（首个共同交易日）
  ① 等权重初始建仓：按 stock_list 等分资金买入各标的（不足 1 手则跳过）
  ② 目标权重置为等权，调仓计数归零

二、每日主循环（遍历每个共同交易日）
  ① 当日市值 = 各标的 持仓 × 收盘价；总资产 = 现金 + 市值
  ② 若有当日最优权重 → 更新 target_weights
  ③ 每累计 interval 个交易日且总资产>0 → 触发再平衡：
     ├─ 对每只标的：target_value = 总资产 × target_weight
     ├─ diff = target_value − 当前市值
     ├─ |diff| < 总资产×0.5% → 忽略（避免频繁小额交易）
     ├─ diff>0 → 再平衡买入（≤可用现金）
     └─ diff<0 → 按金额卖出（回收现金）
  ④ 记录每日：现金/持仓/市值/总资产/累计盈亏/各标的实际与目标权重
  ⑤ 依序补齐每日收益率/盈亏，并对照等权持有不动基准

每个 interval 个交易日对每只标的最多买卖一次；单日可多标的同时调仓；动作类型记录为「初始建仓 / 再平衡买入 / 再平衡卖出」。

1.3 均值方差优化引擎（关键概念）

均值方差系统的一切围绕「收益率矩阵」与「协方差风险」两个核心，权重由最大化夏普比率的最优化求得：

> ⚠️ 权重优化用 zdf(日涨跌幅) 作为收益率代理、zdf.cov() 作为协方差来源；求解为无放空（weights 归零后归一化）的纯多头均值方差配置。
>
> 📌 注意：lambda_risk（风险厌恶系数）在当前版本只作参数存储/打印留档，并未直接进入 SLSQP 目标函数——实际求解目标是最大化夏普比率（negative_sharpe），而非 max return − lambda×risk 形式。如需风险厌恶形式可二次开发 optimize_max_sharpe。

1.4 现代组合理论(MPT) → 本框架参数映射

1.5 设计哲学

• 解耦与复用：数据对齐（align_data）、收益矩阵（get_returns_matrix）、优化目标（negative_sharpe）、求解（optimize_max_sharpe）、逐期权重（calculate_optimal_weights_ts）与交易撮合各环节解耦，可独立替换。
• 透明与可解释：每个调仓日记录目标权重/前权重/买卖权重差，weight_history 完整留存每日权重演变，决策可追溯。
• 风险优先：以协方差与组合波动作为约束标尺，追求「单位风险下最高收益」，天然适应不同波动率资产搭配。
• 灵活与扩展：支持自定义数据注入（标的+指数各 7 种接口）、lookback/interval/weight 边界 全参数化，可继承重写 optimize_max_sharpe 引入风险厌恶/无放空变体。

二、安装与运行环境

2.1 安装包

小果均值方差回测系统以单个类文件 xg_mean_var_backtrader.py 形式提供，无独立安装步骤。将脚本置于工作目录后，在同一目录（或旁路）下放置数据文件即可使用。

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

2.2 依赖

• Python ≥ 3.8
• 第三方库：pandas、numpy、scipy（均值方差优化与统计必需）
• 本地数据源可选依赖：pyarrow（读取 .parquet 历史数据）
• 无需安装 xg_tdx_func（本框架不涉及通达信公式引擎）

> ⚠️ 本系统强依赖 scipy（from scipy.optimize import minimize、from scipy import stats），与其它小果回测系统不同，务必安装 scipy。

安装依赖：

pip install pandas numpy scipy pyarrow

2.3 包结构

工作目录/
├── xg_mean_var_backtrader.py   # 主类文件（class xg_mean_var_backtrader）
├── data/
│   ├── 历史数据/              # 本地标的日线 parquet（代码.parquet）
│   └── (可选) 指数历史文件     # 指数数据（未注入自定义指数时）
└── 策略模型/
    └── 均值方差最优资产组合策略/<user>/  # save_backtrader_data 导出目录（自动创建）

2.4 导入方式

from xg_mean_var_backtrader.xg_mean_var_backtrader import xg_mean_var_backtrader

bt = xg_mean_var_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'],
    cash=1000000,
)

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

当未注入自定义数据（use_custom_data=False）时，系统按固定路径查找单只标的日线 parquet：

data/历史数据/{stock_code}.parquet

找到即用；找不到该标的则加载失败并在结果中跳过。

2.6 数据字段要求

标的（股票/ETF）日线数据需包含以下字段：

> 均值方差优化核心只用到 date + close + zdf；align_data 需各标的存在共同交易日期（交集非空），否则回测终止。数据行数至少需 > lookback_days + 30（calculate_optimal_weights_ts 要求历史≥30 行才跑优化，否则一直退回等权）效果最佳。

指数数据仅需 date + close（close>0），用于输出留档。

三、初始化参数完整参考

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

3.1 基础参数 (Base)

3.2 均值方差优化参数 (Mean-Variance)

3.3 数据源开关 (Data Source)

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

3.5 关键口径：整体资金池与再平衡死区

四、数据加载与处理详解

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

get_stock_data(stock_code) 依次尝试：

1. 自定义数据源（use_custom_data=True 且代码在 _custom_data_cache）——add_stock_data_from_* 注入后优先；
2. 本地 parquet（data/历史数据/{代码}.parquet，固定单路径）；
3. 均无 → 返回空 DataFrame，标的被跳过。

加载后统一：日期过滤到 [start_date, end_date]、按日期升序、剔除 close≤0 或 open≤0 行、补算 zdf = close.pct_change().fillna(0)。

4.2 多线程加载与对齐

get_all_stock_data() 用 ThreadPoolExecutor(max_workers) 并发加载全部标的；_load_single_stock 仅要求非空 DataFrame。

align_data(all_data) 取全部标的共同交易日交集，产出对齐宽表：date + {code}_close + {code}_zdf。交集为空则回测终止。这是组合可比的基石——某只标的数据缺失日期过多会显著缩小回测区间。

4.3 指数数据来源

get_index_data() 优先返回注入的自定义指数数据（use_custom_index_data=True 且已注入），否则从本地文件读取 index_stock 对应指数并缓存。指数仅用于输出留档，策略对照基准实际是 calculate_benchmark_curve 生成的等权持有不动曲线。

五、均值方差优化详解

5.1 对齐与收益率矩阵（align_data / get_returns_matrix）

在 vectorized_backtest 中：先 align_data(all_data) 对齐共同日期；get_returns_matrix 从对齐表中取最近 lookback_days 天的 {code}_zdf 列（剔除缺列与 dropna），得到收益率矩阵（列=标的，行=交易日），供优化求解。

5.2 最优权重求解（optimize_max_sharpe）

对收益率矩阵：

• mean_returns = 各列均值 × 252（年化期望收益）；
• cov_matrix = 协方差 × 252（年化协方差）；
• 目标 negative_sharpe(weights)：组合收益=(w·μ)，组合波动=√(wᵀΣw)，sharpe=(组合收益−rf)/组合波动，返回 −sharpe 供最小化（rf 固定 0.02）；
• 约束：Σweights = 1（eq），每个权重 ∈ [min_weight, max_weight]（bounds）；
• 初值等权 1/n，scipy.optimize.minimize(method='SLSQP', maxiter=1000)；
• 成功 → 结果权重 clip≥0 后归一化返回；失败 → 返回 None。

5.3 逐日权重时间序列（calculate_optimal_weights_ts）

遍历对齐表，对每个调仓参考日用「当日之前全部历史」求解该日最优权重；数据不足 30 行或求解失败 → 该日权重退回等权。产出一张 weight_df（列 = date + 各标的），即每日最优目标权重历史，存为 self.weight_history。

5.4 权重边界与再平衡执行口径

六、交易执行详解

6.1 买入撮合（calculate_buy_shares）

buy_amount = amount / (1 + comm)      # 先扣手续费
shares = 向下取整(buy_amount / price)  # 再按 share_multiple(100) 对齐
若 shares < min_shares(100) → 0
实际成本 = shares×price × (1+comm)，循环确保 ≤ amount

6.2 卖出撮合（calculate_sell_shares_by_value）

按金额卖出：sell_shares 由 sell_value÷price 按 100 对齐，上界为持仓；actual_amount = 卖出额 − 手续费。用于再平衡卖出，不提供全仓卖出参数（卖出额由目标权重差值决定）。

6.3 成交记录字段（trade_log）

每笔成交记录：date / stock / type / price / shares / amount / commission / reason。

type 取值：初始建仓 / 再平衡买入 / 再平衡卖出；reason 示例：初始建仓，目标权重33.3%、目标权重40.0%，前权重25.0%，买入权重15.0%、目标权重20.0%，前权重35.0%，卖出权重15.0%。

> 📌 与信号类策略不同，本系统无手续费字段 zdf/做T 概念；每笔统一含 commission 字段。

七、完整函数清单

> 以下为 xg_mean_var_backtrader 类的全部方法，按功能分组。共 63 个方法（含私有方法），无模块级顶层函数。

7.1 构造与配置

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

7.3 自定义标的数据库管理

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

7.5 指数数据管理

7.6 数据加载与处理

7.7 均值方差优化（核心）

7.8 交易撮合计算

7.9 回测执行

7.10 绩效与数据生成

7.11 数据获取接口（懒触发，自动 run_backtest）

7.12 结果保存与报告

八、输出数据结构详解

8.1 绩效指标字段（performance_metrics）

8.2 年度收益统计字段（annual_performance，按年份键）

8.3 净值曲线字段（equity_curve_data）

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

total_trades / buy_trades / sell_trades / total_buy_amount / total_sell_amount / 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；每条 positions 含 stock_details（各标的 price/holdings/cash/market_value/weight/target_weight）。

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

start_date / end_date / total_days / initial_cash / final_total_value / final_cash / final_holdings / total_pnl / total_return / max_total_value / min_total_value / max_net_value / min_net_value / volatility，含 benchmark_final_value / benchmark_total_return。

8.7 权重历史（get_weight_history）

DataFrame：列 = date + {各标的代码}；每行给出该共同交易日的最优目标权重（和为 1）。是均值方差系统独有的核心诊断输出。

8.8 各标的独立结果（get_stock_results）

每标的含：cash / holdings / total_value（每日数组）、trades（该标成交）、以及 final_holdings / final_cash / final_value。

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

打印策略配置、绩效指标、各标的表现、年度收益表格（含夏普/索提诺/卡尔玛/胜率/基准/超额）。

8.10 导出目录结构

策略模型/均值方差最优资产组合策略/<user>/
├── 指数数据/  指数数据.xlsx + 指数数据.json
├── 成交数据/  成交数据.xlsx + 成交数据.json
├── 持股数据/  持股数据.xlsx + 持股数据.json
├── 账户数据/  账户数据.xlsx + 账户数据.json
├── 绩效指标/  绩效指标.xlsx + 绩效指标.json
├── 年度收益统计/  年度收益统计.xlsx + 年度收益统计.json
├── 净值曲线/  净值曲线.json
├── 策略参数/  策略参数.xlsx + 策略参数.json
└── 权重历史/  权重历史.xlsx + 权重历史.json   ← 本系统独有

九、完整实战示例

9.1 示例1：经典均值方差再平衡回测（本地数据）

from xg_mean_var_backtrader.xg_mean_var_backtrader import xg_mean_var_backtrader

bt = xg_mean_var_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'],
    index_stock='000300.SH',
    cash=1000000,
    comm=0.0001,
    # 均值方差优化参数
    lookback_days=60,     # 用过去60日估计收益/协方差
    max_weight=0.6,       # 单标权重上限60%
    min_weight=0.05,      # 单标权重下限5%
    lambda_risk=2.0,      # 风险厌恶(留档)
    interval=5,           # 每5个交易日调仓
    max_workers=4,
)

result = bt.run_backtest()
print(bt.generate_report())
bt.save_backtrader_data(user="均值方差再平衡")

9.2 示例2：季度再平衡 + 高分散约束

bt = xg_mean_var_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '510300.SH', '518880.SH', '511010.SH', '159937.SZ'],
    cash=500000,
    lookback_days=120,    # 长回看窗口
    interval=63,          # 约每季度(63交易日)调仓
    max_weight=0.3,       # 高分散：上限30%
    min_weight=0.1,       # 每只至少10%
)
bt.run_backtest()
print(bt.get_weight_history().tail())   # 查看最近权重分配
print(bt.generate_report())

9.3 示例3：自定义标的数据注入 + 均值方差回测

import pandas as pd

bt = xg_mean_var_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ', '513100.SH', '518880.SH'],
    cash=1000000,
    max_workers=4,
)

# 注入自定义数据（DataFrame 需含 date/open/high/low/close/volume）
# bt.add_stock_data_from_csv('159915.SZ', 'data/159915.csv')
# bt.add_stock_data_from_excel('513100.SH', 'data/513100.xlsx')
# bt.add_stock_data_from_dataframe('159915.SZ', pd.read_parquet('data/159915.parquet'))

bt.run_backtest()
bt.save_to_json('result/mean_var.json')

9.4 示例4：注入自定义指数数据

bt = xg_mean_var_backtrader(
    start_date='20230101',
    end_date='20261201',
    stock_list=['159915.SZ'],
    cash=500000,
)

# 构造或读取指数 DataFrame（含 date/close 即可）
import pandas as pd
index_df = pd.read_parquet('data/my_index.parquet')   # 需 date/close 列
bt.use_custom_index_data = True
bt.add_index_data_from_dataframe(index_df)
print("是否有指数:", bt.has_index_data(), bt.get_index_data_info())

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

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

bt.run_backtest()

metrics = bt.get_performance_metrics()
curve = bt.get_equity_curve_data()
trades = bt.get_trade_data()
weights = bt.get_weight_history()

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"交易笔数: {trades['statistics']['total_trades']}")

import matplotlib.pyplot as plt
dates = curve['dates']
fig, axes = plt.subplots(2, 1, figsize=(12, 8), sharex=True)
axes[0].plot(dates, curve['net_value'], label='策略净值', linewidth=2)
if curve.get('benchmark_net_value'):
    axes[0].plot(dates, curve['benchmark_net_value'], label='基准(等权持有)', linestyle='--')
axes[0].legend(); axes[0].set_title('组合净值 vs 基准')
# 权重面积图
if weights is not None and not weights.empty:
    wd = weights.set_index('date')
    wd.plot.area(ax=axes[1], alpha=0.6)
    axes[1].set_title('最优权重历史(均值方差优化)')
plt.xticks(rotation=45); plt.tight_layout(); plt.show()

9.6 示例6：按标的查看再平衡结果与权重分配

bt.run_backtest()

# 各标的独立结果
for stock, res in bt.get_stock_results().items():
    print(f"=== {stock} ===")
    print(f"  期末资产: {res['final_value']:.2f}, 持仓: {res['final_holdings']}份")

# 最新一期最优权重
weights = bt.get_weight_history()
if weights is not None and not weights.empty:
    last_row = weights.iloc[-1]
    print("\n最近一次最优权重分配:")
    for stock in bt.stock_list:
        print(f"  {stock}: {last_row[stock]*100:.1f}%")

# 年度绩效
print("\n", bt.get_annual_performance())

十、自定义数据详解

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

add_stock_data_from_* 会调用 _normalize_dataframe：识别日期列/索引→排序→补齐 close/high/low/open/volume→补 zdf→（有 preClose 时）补 return/adj_factor。注入成功后 use_custom_data 应设为 True（多数方法自动切换）。

10.2 指数注入说明

add_index_data_from_* 只需 date+close（自动剔除 close≤0、识别日期列）；注入后 use_custom_index_data=True 时优先作为指数基准。

10.3 注入成功判定与验证

print("标的自定义键:", bt.get_custom_data_keys())   # 含代码即成功
print("has_custom_data:", bt.has_custom_data('159915.SZ'))
print("指数:", bt.has_index_data(), bt.get_index_data_info())

十一、常见问题与 FAQ

Q1: 提示「没有共同的交易日期」或回测终止？

align_data 需要全部标的共同交易日交集非空。检查各标的数据日期范围是否重叠足够；缺某标的长期停牌/无数据会显著压缩回测区间。

Q2: 为什么交易次数很少或某只总不交易？

再平衡仅在 interval 个交易日且 |diff|≥总资产×0.5% 时触发；若当前权重已贴近目标权重（尤其等权优化结果），差异小于死区则不交易，属正常。可调小 interval 或死区逻辑（代码内 0.005）。

Q3: 权重始终是等权，没有优化效果？

可能原因：数据总行数 ≤ lookback_days+30（calculate_optimal_weights_ts 内 len<30 恒退回等权）；或 SLSQP 求解失败。增大历史数据 / 检查数据质量。

Q4: 如何理解 lambda_risk 参数？

当前版本 lambda_risk 仅存储与打印，目标函数是最大化夏普比率（negative_sharpe），未用 return − lambda×risk 形式。想启用风险厌恶形式可继承重写 optimize_max_sharpe。

Q5: 自定义数据注入后仍走本地目录？

确认注入返回 True，用 get_custom_data_keys() 验证，并把 use_custom_data=True（或确认注入方法自动切换）。

Q6: 收益率为 0 或异常？

检查价格列是否全为正、cash 初始值、stock_list 是否都有数据、成交撮合是否因手续费过高导致 actual_cost>amount 而 0 份、以及是否因 zdf 缺失导致收益矩阵全 NaN。

Q7: 单标的权重会超 max_weight 吗？

优化层有 bounds 约束，SLSQP 结果理论上不超 max_weight。但因价格跳动与整数手撮合，实际持仓权重会略偏离目标，需靠下个再平衡周期拉回。

Q8: 某标的首日无价格 / 建仓失败？

initial_weights 等权下若首日该标无有效价格则跳过建仓；若全部标的都无法建仓，回测结果将只剩现金。确认首日各标的有行情。

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

12.1 参数调优建议

12.2 均值方差策略设计经验

• 资产低相关是前提：均值方差的核心收益来自低相关资产搭配，尽量混入股/债/商品/黄金等不同风险资产。
• 收益/协方差估计：zdf 均值×252 与协方差×252 是朴素年化估计，实盘可用更长窗口或收缩估计（可在 get_returns_matrix 扩展）。
• 再平衡纪律：死区与 interval 缺一不可，避免过度交易吞噬收益。

12.3 自定义优化目标（风险厌恶/效用最大化）

继承 xg_mean_var_backtrader，重写 optimize_max_sharpe 引入 lambda_risk：

from scipy.optimize import minimize
import numpy as np

class MyMeanVar(xg_mean_var_backtrader):
    def negative_utility(self, w, mu, cov, lam):
        ret = np.dot(w, mu)
        vol = np.sqrt(np.dot(w.T, np.dot(cov, w)))
        return -(ret - 0.5 * lam * vol ** 2)   # 均值-方差效用(负)
    def optimize_max_sharpe(self, returns_df):
        n = len(returns_df.columns)
        mu = returns_df.mean() * 252
        cov = returns_df.cov() * 252
        cons = [{'type': 'eq', 'fun': lambda x: np.sum(x) - 1}]
        bnds = tuple((self.min_weight, self.max_weight) for _ in range(n))
        res = minimize(self.negative_utility, np.array([1/n]*n),
                       args=(mu, cov, self.lambda_risk),
                       method='SLSQP', bounds=bnds, constraints=cons)
        w = res.x if res.success else np.array([1/n]*n)
        return np.maximum(w, 0) / np.maximum(np.sum(np.maximum(w, 0)), 1e-12), mu, cov

12.4 自定义交易/成本规则

重写 calculate_buy_shares（改买入逻辑）、calculate_sell_shares_by_value（改卖出逻辑）、或 calculate_performance_metrics（加自定义绩效指标）。

十三、技术说明与提示

• 单一整体资金池：cash 不均分到各标的，全仓按权重分配，累计收益率按总初始资金 cash 折算。
• 依赖 scipy：均值方差优化需 scipy（minimize/stats），安装时务必带上。
• 无模块级函数：全部逻辑在类内，63 个方法覆盖对齐/优化/撮合/绩效全流程。
• 权重约束口径：min_weight/max_weight 作用于优化目标权重；实际因整数手撮合略有偏离。
• 指数数据仅用于输出留档，策略对照基准为「等权持有不动」曲线（calculate_benchmark_curve）。
• 交易类型仅 初始建仓 / 再平衡买入 / 再平衡卖出，无做T/止损/信号概念。
• 源码当前固定 adj_type='none'，若需复权需二次开发 _normalize_dataframe。

小果均值方差回测系统，让现代组合理论落地更高效、更透明。如需源码、更多因子库或技术支持，欢迎联系小果（微信：xg_quant）。