pyfolioanalytics 0.3.1

High-fidelity Python implementation of R PortfolioAnalytics — portfolio optimisation, risk measures, and moment estimation with cross-validated mathematical parity.

PyFolioAnalytics

PyFolioAnalytics 是 R 语言顶级组合优化库 PortfolioAnalytics 的高保真 Python 实现。本项目不仅完美复刻了 R 语言的声明式定义和优化逻辑，还整合了 Riskfolio-Lib 和 PyPortfolioOpt 中的现代量化特性，通过严苛的 $10^{-7}$ 精度交叉验证，为量化研究提供生产级的数学保障。

---

🛠 全功能概览

1. 组合规格与复杂约束 (Portfolio Specification)

复刻了 R 语言 portfolio.spec 的核心逻辑，支持高度灵活的约束组合：

• 资产分配约束: box (权重上下限), group (组约束), position_limit (最大持仓数)。
• 预算与杠杆: full_investment (权重和为1), dollar_neutral (多空对冲), leverage_exposure (毛杠杆限制，支持 130/30)。
• 风控偏离限制:
  • factor_exposure: 限制风格/宏观因子的 Beta 暴露。
  • tracking_error: 强大的多范数跟踪误差。支持 $L_2$ (经典波动偏离), $L_1$ (主动偏离度), 以及极致严格的 $L_\infty$ (单一个股绝对最大偏离) 风控。
  • active_share: 强制组合与基准的主动管理差异。
  • diversification (HHI): 通过权重平方和限制实现多样化。
• 交易控制: turnover (换手率限制), transaction_cost (基于百分比的交易成本)。

2. 统计矩估计 (Statistical Moments)

提供多样化的均值、协方差及高阶矩估计技术，用于降低估计误差：

• 动态波动率: CCC-GARCH (单变量 GARCH + 常相关) 矩估计。
• 主观观点整合: Meucci Entropy Pooling (支持解析梯度) 与 Black-Litterman（支持 Meucci 和 He-Litterman 双公式）。
  • Idzorek 置信方法: 通过 idzorek_omega() 或 Omega="idzorek" 直接以百分比置信度（0~100%）代替手工指定的方差矩阵，大幅降低 BL 参数化难度。
• 稳健估计: MinCovDet (鲁棒协方差), Ledoit-Wolf / OAS (收缩估计), Semi-Covariance。
• 随机矩阵理论 (RMT): 特征值去噪（Fixed, Spectral, Shrink 方法）。
• 高阶矩: 样本及统计因子模型（SFM）生成的 共偏度 (M3) 和 共峰度 (M4) 矩阵；支持因子模型收缩。
• 类型安全估计器 API: MomentConfig dataclass 替代 **kwargs 散打，配合 register_cov_estimator / register_mu_estimator 装饰器支持用户自定义估计器插件注册。

3. 风险度量与归因 (Risk Analysis)

涵盖从经典波动率到前沿稳健度量的全方位分析：

• 经典与修正风险: Gaussian/Modified (Cornish-Fisher) VaR 和 ES (CVaR)。
• 下行风险: SemiDeviation / SemiVariance（基于 LPM p=2 的标准化接口，与 Riskfolio-Lib 对齐）、MAD、semi_MAD。
• 回撤风险: CDaR (条件回撤), EDaR (熵回撤), MaxDrawdown，以及惩罚持续深度的 Ulcer Index (溃疡指数)。
• 现代稳健度量: EVaR (熵 VaR), RLVaR/RLDaR (基于稳健线性规划的 VaR/DaR)。
• 排序加权 (OWA): 支持 GMD、L-Moments 权重、CRM 权重等 OWA 风险度量。
• 风险归因: 资产级与因子级的 MCR (边际), CCR (成分), PCR (百分比) 贡献分解。

4. 优化算法与引擎 (Optimization)

集成多种求解器，适配线性、二次及非凸优化：

• 凸优化集成 (CVXPY):
  • MVO, SOCP, MILP 极速求解。
  • 比率全局优化 (Ratio Optimization): 内置 Charnes-Cooper 变换，使得各种风险比率（如 Sharpe Ratio, STARR, Martin Ratio）能转化为凸规划被直接秒解出全局最优点。
• 风险平价: ERC (等风险贡献) 的非线性精确求解。
• 有效前沿: CLA (关键线算法) 实现带约束的精确前沿描绘。
• 机器学习优化:
  • HRP (分层风险平价), HERC (分层等风险贡献), NCO (嵌套聚类优化)。
  • 支持 DBHT (有向气泡层次树) 聚类算法。
• 非凸与启发式搜索: 支持 rp_sample (网格随机采样), rp_grid, 以及基于 Simplex 变换的随机生成，用于复杂非凸空间的完全覆盖搜索。

5. 架构与实务功能

• 对冲基金级回测引擎:
  • 支持滚动窗口（Rolling）和扩张窗口（Expanding）的自动化调仓测试。
  • 支持精细化费用建模，可在考虑 PTC 的同时，基于精确的绝对资产规模 (AUM) 轨迹逐日计提管理费 (Management Fee) 并支持带有高水位线 (High Water Mark) 的表现费 (Performance Fee) 计算。
• 层次化结构: 支持 Regime Switching (状态切换) 组合和多层级嵌套组合。
• 离散化分配: 支持将百分比权重转换为实际股票股数。

---

🔬 数学保真度与交叉验证

本项目每一项核心算法均通过了与 R 语言 PortfolioAnalytics 原生库的对比验证：

• 验证数据集: 包含 edhec 策略数据及 2020-2026 年真实股票数据。
• 自动化断言: 在 tests/ 下有超过 400 个测试用例，确保 Python 与 R 的计算结果在 1e-7 精度下一致。
• 透明逻辑: 所有基准生成的 R 脚本均保留在 scripts/ 目录，供用户复现。

📚 官方文档

欢迎查阅模块化的详细开发与使用文档（包含核心数学原理说明及丰富的代码示例）：

0. 构建与验证量化投资组合的标准流程 - 强烈建议初学者阅读，涵盖从参数估计到滚动回测的完整量化流水线！
1. 快速入门指南 (Quickstart) - 5 分钟上手构建你的第一个均值-方差最优投资组合。
2. 组合规格定义 (Portfolio Specification) - 详解如何使用 portfolio.py 声明复杂的业务约束（如多空、杠杆、换手率、风险预算等）。
3. 参数与矩估计 (Parameter Estimation) - 探讨 moments.py 与 rmt.py 中的高阶统计矩估计技术（去噪、收缩、Black-Litterman 等）。
4. 风险度量与测度 (Risk Measures) - 深入 risk.py，了解 VaR、CVaR、CDaR、OWA 等前沿稳健风险度量的数学定义与应用。
5. 核心优化引擎 (Optimization Engine) - 解析 optimize.py 与 solvers.py 如何将你的声明转化为 CVXPY 凸优化或启发式问题并极速求解。
6. 机器学习与图论配置 (Machine Learning) - 指导如何使用 ml.py 和 dbht.py 构建基于网络拓扑和层次聚类的现代投资组合（如 HRP, HERC）。
7. 回测与可视化 (Backtesting & Plots) - 使用 backtest.py 引擎进行带费率的滚动回测，并使用 plots.py 生成专业的交互式风险归因图表。

---

量化研究的精准桥梁。