一、QuantStats 简介
QuantStats 是一个 Python 库，专门用于量化投资分析和投资组合性能分析。
它提供了一套完整的工具来计算各种金融指标、生成专业报告和可视化图表。
QuantStats 是量化分析师和投资者的强大工具，
能够快速生成专业级别的投资绩效分析报告，大幅提升工作效率。


主要特点：
全面的指标计算 - 支持夏普比率、最大回撤、Alpha/Beta、索提诺比率等
可视化功能 - 自动生成收益曲线、回撤图、月度收益热图等
简便易用 - 简洁的 API 设计，几行代码即可生成专业报告
与主流库兼容 - 与 pandas、numpy、backtrader 等无缝集成

二、安装

pip install quantstats


三、基本使用示例

示例 1：基础性能分析

import quantstats as qs
import yfinance as yf
import pandas as pd

# 下载数据
spy = yf.download('SPY', start='2020-01-01', end='2023-12-31')
portfolio = yf.download('AAPL', start='2020-01-01', end='2023-12-31')

# 提取收益率（使用调整后收盘价）
spy_returns = spy['Adj Close'].pct_change().dropna()
portfolio_returns = portfolio['Adj Close'].pct_change().dropna()

# 生成完整报告
qs.reports.full(portfolio_returns, benchmark=spy_returns)

# 或生成 HTML 报告
qs.reports.html(portfolio_returns, benchmark=spy_returns, 
                output='quantstats_report.html', title='AAPL Performance')


示例 2：计算各项指标

# 单独计算各项指标
import quantstats as qs

# 计算夏普比率（年化）
sharpe = qs.stats.sharpe(portfolio_returns)
print(f"夏普比率: {sharpe:.3f}")

# 计算最大回撤
max_dd = qs.stats.max_drawdown(portfolio_returns)
print(f"最大回撤: {max_dd:.2%}")

# 计算索提诺比率
sortino = qs.stats.sortino(portfolio_returns)
print(f"索提诺比率: {sortino:.3f}")

# 计算 Alpha 和 Beta
alpha = qs.stats.alpha(portfolio_returns, spy_returns)
beta = qs.stats.beta(portfolio_returns, spy_returns)
print(f"Alpha: {alpha:.3f}, Beta: {beta:.3f}")

# 获取所有统计数据
stats = qs.reports.metrics(portfolio_returns, benchmark=spy_returns, 
                          mode='full')
print(stats)


示例 3：可视化

import matplotlib.pyplot as plt

# 设置样式
qs.extend_pandas()

# 1. 收益曲线
portfolio_returns.plot_monthly_returns(kind='bar', figsize=(15, 5))
plt.title('月度收益率')
plt.show()

# 2. 回撤图
qs.plots.drawdown(portfolio_returns, figsize=(15, 5))

# 3. 滚动夏普比率
qs.plots.rolling_sharpe(portfolio_returns, rolling_window=252, 
                        figsize=(15, 5))

# 4. 收益分布直方图
qs.plots.histogram(portfolio_returns, figsize=(15, 5))

# 5. 月度收益热力图
qs.plots.returns_heatmap(portfolio_returns, annot_size=10, 
                         figsize=(15, 8))


示例 4：投资组合分析

# 多资产组合分析
import numpy as np

# 模拟三个资产
tickers = ['AAPL', 'MSFT', 'GOOGL']
returns_data = {}

for ticker in tickers:
    data = yf.download(ticker, start='2020-01-01', 
                      end='2023-12-31')
    returns_data[ticker] = data['Adj Close'].pct_change().dropna()

# 创建等权重的投资组合
portfolio_df = pd.DataFrame(returns_data)
weights = np.array([0.4, 0.3, 0.3])  # 权重

# 计算加权收益
portfolio_returns = (portfolio_df * weights).sum(axis=1)

# 分析组合性能
benchmark = spy_returns.reindex(portfolio_returns.index)

report = qs.reports.metrics(
    portfolio_returns,
    benchmark=benchmark,
    rf=0.02,  # 无风险利率 2%
    display=False,
    mode='full'
)

print("投资组合表现指标:")
print(report)



示例 5：自定义报告

# 自定义要计算的指标
my_metrics = {
    '累计收益': qs.stats.comp(portfolio_returns),
    '年化收益': qs.stats.cagr(portfolio_returns),
    '年化波动率': qs.stats.volatility(portfolio_returns),
    '夏普比率': qs.stats.sharpe(portfolio_returns),
    '最大回撤': qs.stats.max_drawdown(portfolio_returns),
    'Calmar比率': qs.stats.calmar(portfolio_returns),
    'Omega比率': qs.stats.omega(portfolio_returns),
    'Sortino比率': qs.stats.sortino(portfolio_returns),
    'Skew': qs.stats.skew(portfolio_returns),
    'Kurtosis': qs.stats.kurtosis(portfolio_returns),
    '尾部比率': qs.stats.tail_ratio(portfolio_returns),
    '日胜率': qs.stats.win_rate(portfolio_returns),
    'Best Day': qs.stats.best(portfolio_returns),
    'Worst Day': qs.stats.worst(portfolio_returns)
}

# 转换为 DataFrame
metrics_df = pd.DataFrame.from_dict(my_metrics, orient='index', 
                                   columns=['Value'])
print(metrics_df)



示例 6：与 Backtrader 集成

import backtrader as bt

class MyStrategy(bt.Strategy):
    # ... 策略定义 ...
    pass

# 回测后获取结果
cerebro = bt.Cerebro()
# ... 添加数据、策略等 ...
results = cerebro.run()

# 提取收益序列
portfolio_value = cerebro.broker.getvalue()  # 简化的示例
# 实际使用时需要正确提取收益序列

# 使用 QuantStats 分析
# qs.reports.basic(returns_series)



四、主要功能模块
1. 核心模块
quantstats.stats - 性能指标计算
quantstats.plots - 可视化图表
quantstats.reports - 完整报告生成
quantstats.utils - 工具函数

2. 常用指标
收益指标：累计收益、年化收益、日胜率
风险指标：波动率、最大回撤、VaR、CVaR
风险调整收益：夏普比率、索提诺比率、Calmar比率
归因分析：Alpha、Beta、信息比率
分布特征：偏度、峰度、尾部比率

3. 报告类型
full() - 完整性能报告
html() - HTML格式报告
tearsheet() - 综合仪表板
metrics() - 指标表格

五、注意事项
数据要求：输入应为收益率序列（日频），而非价格序列
基准对齐：确保投资组合和基准数据的时间索引对齐
无风险利率：默认使用0%，可根据需要调整
频率假设：默认假设252个交易日/年

六、高级功能


# 自定义无风险利率和交易天数
qs.reports.full(
    portfolio_returns,
    benchmark=spy_returns,
    rf=0.03,  # 3% 无风险利率
    periods_per_year=365  # 加密货币等全年交易
)

# 提取详细数据
daily_stats = qs.stats.daily_stats(portfolio_returns)
monthly_stats = qs.stats.monthly_returns(portfolio_returns)

# 压力测试
stress = qs.stats.to_drawdown_series(portfolio_returns)