0
# QuantStats
1

2
Portfolio analytics for quants - a comprehensive Python library providing statistical analysis, risk assessment, performance visualization, and reporting capabilities for quantitative finance. QuantStats enables portfolio managers and quantitative analysts to perform in-depth performance analysis through statistical metrics, risk ratios, drawdown analysis, and professional-grade tearsheet generation.
3

4
## Package Information
5

6
- **Package Name**: quantstats
7
- **Language**: Python
8
- **Installation**: `pip install quantstats`
9

10
## Core Imports
11

12
```python
13
import quantstats as qs
14
```
15

16
Access specific modules:
17

18
```python
19
import quantstats.stats as stats
20
import quantstats.plots as plots
21
import quantstats.reports as reports
22
import quantstats.utils as utils
23
```
24

25
## Basic Usage
26

27
```python
28
import quantstats as qs
29
import pandas as pd
30
import numpy as np
31

32
# Create sample returns data
33
dates = pd.date_range('2020-01-01', '2023-12-31', freq='D')
34
returns = pd.Series(np.random.normal(0.001, 0.02, len(dates)), index=dates)
35

36
# Basic performance metrics
37
sharpe_ratio = qs.stats.sharpe(returns)
38
max_dd = qs.stats.max_drawdown(returns)
39
cagr = qs.stats.cagr(returns)
40

41
print(f"Sharpe Ratio: {sharpe_ratio:.2f}")
42
print(f"Max Drawdown: {max_dd:.2%}")
43
print(f"CAGR: {cagr:.2%}")
44

45
# Generate comprehensive HTML report
46
qs.reports.html(returns, output='portfolio_report.html')
47

48
# Create performance plots
49
qs.plots.snapshot(returns, title="Portfolio Performance")
50

51
# Extend pandas for method chaining
52
qs.extend_pandas()
53
portfolio_metrics = returns.sharpe(), returns.sortino(), returns.calmar()
54
```
55

56
## Architecture
57

58
QuantStats is organized into four main modules that work together to provide comprehensive portfolio analysis:
59

60
- **stats**: Core statistical functions for performance metrics, risk ratios, and benchmarking
61
- **plots**: Visualization functions for creating charts, graphs, and performance plots
62
- **reports**: Report generation for HTML tearsheets, metrics tables, and comprehensive analysis
63
- **utils**: Data preparation utilities for converting prices to returns, validation, and data manipulation
64

65
The library also provides `extend_pandas()` functionality that adds all statistical and plotting methods directly to pandas DataFrames and Series, enabling method chaining and integrated workflows.
66

67
## Capabilities
68

69
### Statistical Analysis
70

71
Core statistical functions for portfolio performance analysis including return calculations, risk metrics, performance ratios, and benchmarking against market indices.
72

73
```python { .api }
74
def sharpe(returns, rf=0.0, periods=252, annualize=True, smart=False): ...
75
def sortino(returns, rf=0, periods=252, annualize=True, smart=False): ...
76
def max_drawdown(prices): ...
77
def volatility(returns, periods=252, annualize=True, prepare_returns=True): ...
78
def cagr(returns, rf=0.0, compounded=True, periods=252): ...
79
def calmar(returns, prepare_returns=True, periods=252): ...
80
```
81

82
[Statistical Analysis](./statistical-analysis.md)
83

84
### Risk Assessment
85

86
Advanced risk metrics including Value at Risk (VaR), drawdown analysis, tail risk measures, and stress testing indicators for comprehensive portfolio risk evaluation.
87

88
```python { .api }
89
def value_at_risk(returns, sigma=1, confidence=0.95, prepare_returns=True): ...
90
def conditional_value_at_risk(returns, sigma=1, confidence=0.95, prepare_returns=True): ...
91
def ulcer_index(returns): ...
92
def to_drawdown_series(returns): ...
93
def tail_ratio(returns, cutoff=0.95, prepare_returns=True): ...
94
```
95

96
[Risk Assessment](./risk-assessment.md)
97

98
### Performance Visualization
99

100
Plotting and charting functions for creating comprehensive performance visualizations including cumulative returns, rolling metrics, drawdown underwater plots, and monthly heatmaps.
101

102
```python { .api }
103
def snapshot(returns, grayscale=False, figsize=(10, 8), title="Portfolio Summary", ...): ...
104
def returns(returns, benchmark=None, ...): ...
105
def drawdown(returns, ...): ...
106
def rolling_sharpe(returns, benchmark=None, rf=0.0, period=126, ...): ...
107
def monthly_heatmap(returns, benchmark=None, ...): ...
108
```
109

110
[Performance Visualization](./performance-visualization.md)
111

112
### Report Generation
113

114
Professional tearsheet and report generation including HTML reports, metrics tables, and comprehensive performance analysis with customizable layouts and benchmarking.
115

116
```python { .api }
117
def html(returns, benchmark=None, rf=0.0, ...): ...
118
def metrics(returns, benchmark=None, rf=0.0, ...): ...
119
def full(returns, benchmark=None, rf=0.0, ...): ...
120
def basic(returns, benchmark=None, ...): ...
121
```
122

123
[Report Generation](./report-generation.md)
124

125
### Data Utilities
126

127
Data preparation and utility functions for converting between prices and returns, data validation, benchmarking preparation, and pandas integration.
128

129
```python { .api }
130
def to_returns(prices, rf=0.0): ...
131
def to_prices(returns, base=1e5): ...
132
def validate_input(data, allow_empty=False): ...
133
def aggregate_returns(returns, period=None, compounded=True): ...
134
def download_returns(ticker, period="max", proxy=None): ...
135
```
136

137
[Data Utilities](./data-utilities.md)
138

139
### Pandas Integration
140

141
Extended pandas functionality that adds all QuantStats statistical and plotting methods directly to DataFrames and Series for seamless integration with existing workflows.
142

143
```python { .api }
144
def extend_pandas(): ...
145
```
146

147
When `extend_pandas()` is called, all statistical methods become available on pandas objects:
148

149
```python
150
# After calling qs.extend_pandas()
151
returns.sharpe()  # Same as qs.stats.sharpe(returns)
152
returns.plot_snapshot()  # Same as qs.plots.snapshot(returns)
153
returns.max_drawdown()  # Same as qs.stats.max_drawdown(returns)
154
```
155

156
[Pandas Integration](./pandas-integration.md)
157

158
## Types
159

160
```python { .api }
161
class QuantStatsError(Exception):
162
    """Base exception class for QuantStats"""
163

164
class DataValidationError(QuantStatsError):
165
    """Raised when input data validation fails"""
166

167
class CalculationError(QuantStatsError):
168
    """Raised when a calculation fails"""
169

170
class PlottingError(QuantStatsError):
171
    """Raised when plotting operations fail"""
172

173
class BenchmarkError(QuantStatsError):
174
    """Raised when benchmark-related operations fail"""
175
```