PyFolioAnalytics 是 R 语言顶级组合优化库 PortfolioAnalytics 的高保真 Python 实现。本项目不仅完美复刻了 R 语言的声明式定义和优化逻辑，还整合了 Riskfolio-Lib 和 PyPortfolioOpt 中的现代量化特性，通过严苛的
复刻了 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(基于百分比的交易成本)。
提供多样化的均值、协方差及高阶矩估计技术，用于降低估计误差：
- 动态波动率:
CCC-GARCH(单变量 GARCH + 常相关) 矩估计。 - 主观观点整合:
Meucci Entropy Pooling(支持解析梯度) 与Black-Litterman（支持 Meucci 和 He-Litterman 双公式）。- Idzorek 置信方法: 通过
idzorek_omega()或Omega="idzorek"直接以百分比置信度（0~100%）代替手工指定的方差矩阵，大幅降低 BL 参数化难度。
- Idzorek 置信方法: 通过
- 稳健估计:
MinCovDet(鲁棒协方差),Ledoit-Wolf/OAS(收缩估计),Semi-Covariance。 - 随机矩阵理论 (RMT): 特征值去噪（Fixed, Spectral, Shrink 方法）。
- 高阶矩: 样本及统计因子模型（SFM）生成的 共偏度 (M3) 和 共峰度 (M4) 矩阵；支持因子模型收缩。
- 类型安全估计器 API:
MomentConfigdataclass 替代**kwargs散打，配合register_cov_estimator/register_mu_estimator装饰器支持用户自定义估计器插件注册。
涵盖从经典波动率到前沿稳健度量的全方位分析：
- 经典与修正风险: 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 (百分比) 贡献分解。
集成多种求解器，适配线性、二次及非凸优化：
- 凸优化集成 (CVXPY):
- MVO, SOCP, MILP 极速求解。
- 比率全局优化 (Ratio Optimization): 内置 Charnes-Cooper 变换，使得各种风险比率（如 Sharpe Ratio, STARR, Martin Ratio）能转化为凸规划被直接秒解出全局最优点。
- 风险平价:
ERC(等风险贡献) 的非线性精确求解。 - 有效前沿: CLA (关键线算法) 实现带约束的精确前沿描绘。
- 机器学习优化:
HRP(分层风险平价),HERC(分层等风险贡献),NCO(嵌套聚类优化)。- 支持 DBHT (有向气泡层次树) 聚类算法。
- 非凸与启发式搜索: 支持
rp_sample(网格随机采样),rp_grid, 以及基于 Simplex 变换的随机生成，用于复杂非凸空间的完全覆盖搜索。
- 对冲基金级回测引擎:
- 支持滚动窗口（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/目录，供用户复现。
欢迎查阅模块化的详细开发与使用文档（包含核心数学原理说明及丰富的代码示例）：
- 构建与验证量化投资组合的标准流程 - 强烈建议初学者阅读，涵盖从参数估计到滚动回测的完整量化流水线！
- 快速入门指南 (Quickstart) - 5 分钟上手构建你的第一个均值-方差最优投资组合。
- 组合规格定义 (Portfolio Specification) - 详解如何使用
portfolio.py声明复杂的业务约束（如多空、杠杆、换手率、风险预算等）。 - 参数与矩估计 (Parameter Estimation) - 探讨
moments.py与rmt.py中的高阶统计矩估计技术（去噪、收缩、Black-Litterman 等）。 - 风险度量与测度 (Risk Measures) - 深入
risk.py，了解 VaR、CVaR、CDaR、OWA 等前沿稳健风险度量的数学定义与应用。 - 核心优化引擎 (Optimization Engine) - 解析
optimize.py与solvers.py如何将你的声明转化为 CVXPY 凸优化或启发式问题并极速求解。 - 机器学习与图论配置 (Machine Learning) - 指导如何使用
ml.py和dbht.py构建基于网络拓扑和层次聚类的现代投资组合（如 HRP, HERC）。 - 回测与可视化 (Backtesting & Plots) - 使用
backtest.py引擎进行带费率的滚动回测，并使用plots.py生成专业的交互式风险归因图表。
量化研究的精准桥梁。