Metadata-Version: 2.3
Name: pyfolioanalytics
Version: 0.3.0
Summary: Add your description here
Author: curry tang
Author-email: curry tang <twn39@163.com>
Requires-Dist: clarabel>=0.11.1
Requires-Dist: cvxopt>=1.3.3
Requires-Dist: cvxpy>=1.8.2
Requires-Dist: highspy>=1.14.0
Requires-Dist: kaleido>=1.2.0
Requires-Dist: networkx>=3.6.1
Requires-Dist: numpy>=2.4.4
Requires-Dist: pandas>=3.0.2
Requires-Dist: plotly>=6.7.0
Requires-Dist: pyscipopt>=6.1.0
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.17.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# PyFolioAnalytics

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/pyfolioanalytics.svg)](https://pypi.org/project/pyfolioanalytics/)

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

---
*量化研究的精准桥梁。*
