0
# Performance Visualization
1

2
Comprehensive plotting and charting functions for creating professional-grade performance visualizations including cumulative returns, rolling metrics, drawdown analysis, return distributions, and interactive charts for quantitative analysis.
3

4
## Capabilities
5

6
### Comprehensive Performance Snapshots
7

8
Multi-panel performance overviews combining key metrics and visualizations.
9

10
```python { .api }
11
def snapshot(returns, grayscale=False, figsize=(10, 8), title="Portfolio Summary", show=True, log_scale=False, **kwargs):
12
    """
13
    Create comprehensive performance snapshot with multiple panels.
14
    
15
    Parameters:
16
    - returns: pandas Series of returns
17
    - grayscale: bool, whether to use grayscale color scheme
18
    - figsize: tuple, figure size (width, height)
19
    - title: str, chart title
20
    - show: bool, whether to display the plot
21
    - log_scale: bool, whether to use log scale for returns
22
    - **kwargs: additional plotting parameters
23
    
24
    Returns:
25
    matplotlib Figure: Multi-panel performance chart
26
    """
27
```
28

29
### Cumulative Returns Visualization
30

31
Track portfolio performance over time with various return representations.
32

33
```python { .api }
34
def returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), log_scale=False, **kwargs):
35
    """
36
    Plot cumulative returns over time.
37
    
38
    Parameters:
39
    - returns: pandas Series of returns
40
    - benchmark: pandas Series of benchmark returns (optional)
41
    - grayscale: bool, whether to use grayscale colors
42
    - figsize: tuple, figure size
43
    - log_scale: bool, whether to use logarithmic scale
44
    - **kwargs: additional plotting parameters
45
    
46
    Returns:
47
    matplotlib Figure: Cumulative returns chart
48
    """
49

50
def log_returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), **kwargs):
51
    """
52
    Plot log-scaled cumulative returns.
53
    
54
    Parameters:
55
    - returns: pandas Series of returns
56
    - benchmark: pandas Series of benchmark returns (optional)
57
    - grayscale: bool, whether to use grayscale colors
58
    - figsize: tuple, figure size
59
    - **kwargs: additional plotting parameters
60
    
61
    Returns:
62
    matplotlib Figure: Log-scaled returns chart
63
    """
64

65
def earnings(returns, start_balance=1e5, mode="comp", grayscale=False, figsize=(10, 6), **kwargs):
66
    """
67
    Plot portfolio earnings/value over time.
68
    
69
    Parameters:
70
    - returns: pandas Series of returns
71
    - start_balance: float, starting portfolio balance
72
    - mode: str, calculation mode ('comp' for compounded)
73
    - grayscale: bool, whether to use grayscale colors
74
    - figsize: tuple, figure size
75
    - **kwargs: additional plotting parameters
76
    
77
    Returns:
78
    matplotlib Figure: Portfolio earnings chart
79
    """
80
```
81

82
### Drawdown Analysis Visualization
83

84
Visualize portfolio drawdowns and underwater periods.
85

86
```python { .api }
87
def drawdown(returns, grayscale=False, figsize=(10, 5), **kwargs):
88
    """
89
    Create underwater/drawdown plot showing portfolio drawdowns over time.
90
    
91
    Parameters:
92
    - returns: pandas Series of returns
93
    - grayscale: bool, whether to use grayscale colors
94
    - figsize: tuple, figure size
95
    - **kwargs: additional plotting parameters
96
    
97
    Returns:
98
    matplotlib Figure: Drawdown underwater chart
99
    """
100

101
def drawdowns_periods(returns, periods=5, lw=1.5, log_scale=False, figsize=(10, 6), **kwargs):
102
    """
103
    Plot the longest drawdown periods.
104
    
105
    Parameters:
106
    - returns: pandas Series of returns
107
    - periods: int, number of longest periods to highlight
108
    - lw: float, line width
109
    - log_scale: bool, whether to use log scale
110
    - figsize: tuple, figure size
111
    - **kwargs: additional plotting parameters
112
    
113
    Returns:
114
    matplotlib Figure: Longest drawdown periods chart
115
    """
116
```
117

118
### Return Distribution Analysis
119

120
Analyze and visualize return distribution characteristics.
121

122
```python { .api }
123
def distribution(returns, grayscale=False, figsize=(10, 6), **kwargs):
124
    """
125
    Plot return distribution with histogram and normal curve overlay.
126
    
127
    Parameters:
128
    - returns: pandas Series of returns
129
    - grayscale: bool, whether to use grayscale colors
130
    - figsize: tuple, figure size
131
    - **kwargs: additional plotting parameters
132
    
133
    Returns:
134
    matplotlib Figure: Return distribution chart
135
    """
136

137
def histogram(returns, benchmark=None, resample="ME", grayscale=False, figsize=(10, 6), **kwargs):
138
    """
139
    Create histogram of resampled returns.
140
    
141
    Parameters:
142
    - returns: pandas Series of returns
143
    - benchmark: pandas Series of benchmark returns (optional)
144
    - resample: str, resampling frequency ('ME' for month-end, 'QE' for quarter-end)
145
    - grayscale: bool, whether to use grayscale colors
146
    - figsize: tuple, figure size
147
    - **kwargs: additional plotting parameters
148
    
149
    Returns:
150
    matplotlib Figure: Returns histogram
151
    """
152

153
def daily_returns(returns, benchmark, grayscale=False, figsize=(10, 4), **kwargs):
154
    """
155
    Plot daily returns time series.
156
    
157
    Parameters:
158
    - returns: pandas Series of portfolio returns
159
    - benchmark: pandas Series of benchmark returns
160
    - grayscale: bool, whether to use grayscale colors
161
    - figsize: tuple, figure size
162
    - **kwargs: additional plotting parameters
163
    
164
    Returns:
165
    matplotlib Figure: Daily returns chart
166
    """
167
```
168

169
### Rolling Metrics Visualization
170

171
Visualize time-varying performance metrics over rolling windows.
172

173
```python { .api }
174
def rolling_sharpe(returns, benchmark=None, rf=0.0, periods=252, window=126, grayscale=False, figsize=(10, 6), **kwargs):
175
    """
176
    Plot rolling Sharpe ratio over time.
177
    
178
    Parameters:
179
    - returns: pandas Series of returns
180
    - benchmark: pandas Series of benchmark returns (optional)
181
    - rf: float, risk-free rate
182
    - periods: int, number of periods per year
183
    - window: int, rolling window size
184
    - grayscale: bool, whether to use grayscale colors
185
    - figsize: tuple, figure size
186
    - **kwargs: additional plotting parameters
187
    
188
    Returns:
189
    matplotlib Figure: Rolling Sharpe ratio chart
190
    """
191

192
def rolling_sortino(returns, benchmark=None, rf=0.0, periods=252, window=126, grayscale=False, figsize=(10, 6), **kwargs):
193
    """
194
    Plot rolling Sortino ratio over time.
195
    
196
    Parameters:
197
    - returns: pandas Series of returns
198
    - benchmark: pandas Series of benchmark returns (optional)
199
    - rf: float, risk-free rate
200
    - periods: int, number of periods per year
201
    - window: int, rolling window size
202
    - grayscale: bool, whether to use grayscale colors
203
    - figsize: tuple, figure size
204
    - **kwargs: additional plotting parameters
205
    
206
    Returns:
207
    matplotlib Figure: Rolling Sortino ratio chart
208
    """
209

210
def rolling_volatility(returns, benchmark=None, period=126, grayscale=False, figsize=(10, 6), **kwargs):
211
    """
212
    Plot rolling volatility over time.
213
    
214
    Parameters:
215
    - returns: pandas Series of returns
216
    - benchmark: pandas Series of benchmark returns (optional)
217
    - period: int, rolling window size
218
    - grayscale: bool, whether to use grayscale colors
219
    - figsize: tuple, figure size
220
    - **kwargs: additional plotting parameters
221
    
222
    Returns:
223
    matplotlib Figure: Rolling volatility chart
224
    """
225

226
def rolling_beta(returns, benchmark, window1=126, window2=252, grayscale=False, figsize=(10, 6), **kwargs):
227
    """
228
    Plot rolling beta coefficients over time.
229
    
230
    Parameters:
231
    - returns: pandas Series of portfolio returns
232
    - benchmark: pandas Series of benchmark returns
233
    - window1: int, first rolling window size
234
    - window2: int, second rolling window size
235
    - grayscale: bool, whether to use grayscale colors
236
    - figsize: tuple, figure size
237
    - **kwargs: additional plotting parameters
238
    
239
    Returns:
240
    matplotlib Figure: Rolling beta chart
241
    """
242
```
243

244
### Calendar-Based Visualizations
245

246
Time-period performance analysis with calendar views.
247

248
```python { .api }
249
def monthly_heatmap(returns, benchmark=None, grayscale=False, figsize=(10, 5), cbar=True, **kwargs):
250
    """
251
    Create monthly returns heatmap showing performance by month and year.
252
    
253
    Parameters:
254
    - returns: pandas Series of returns
255
    - benchmark: pandas Series of benchmark returns (optional)
256
    - grayscale: bool, whether to use grayscale colors
257
    - figsize: tuple, figure size
258
    - cbar: bool, whether to show color bar
259
    - **kwargs: additional plotting parameters
260
    
261
    Returns:
262
    matplotlib Figure: Monthly returns heatmap
263
    """
264

265
def monthly_returns(returns, grayscale=False, figsize=(10, 5), **kwargs):
266
    """
267
    Create monthly returns heatmap (wrapper for monthly_heatmap).
268
    
269
    Parameters:
270
    - returns: pandas Series of returns
271
    - grayscale: bool, whether to use grayscale colors
272
    - figsize: tuple, figure size
273
    - **kwargs: additional plotting parameters
274
    
275
    Returns:
276
    matplotlib Figure: Monthly returns heatmap
277
    """
278

279
def yearly_returns(returns, benchmark=None, grayscale=False, figsize=(10, 6), **kwargs):
280
    """
281
    Plot end-of-year returns as bar chart.
282
    
283
    Parameters:
284
    - returns: pandas Series of returns
285
    - benchmark: pandas Series of benchmark returns (optional)
286
    - grayscale: bool, whether to use grayscale colors
287
    - figsize: tuple, figure size
288
    - **kwargs: additional plotting parameters
289
    
290
    Returns:
291
    matplotlib Figure: Annual returns bar chart
292
    """
293
```
294

295
### Interactive and Export Features
296

297
Enhance visualizations with interactivity and export capabilities.
298

299
```python { .api }
300
def to_plotly(fig):
301
    """
302
    Convert matplotlib figure to Plotly for interactivity (if Plotly available).
303
    
304
    Parameters:
305
    - fig: matplotlib Figure object
306
    
307
    Returns:
308
    plotly Figure: Interactive Plotly figure (if available)
309
    """
310
```
311

312
## Usage Examples
313

314
### Basic Performance Visualization
315

316
```python
317
import quantstats as qs
318
import pandas as pd
319
import numpy as np
320

321
# Create sample data
322
dates = pd.date_range('2020-01-01', '2023-12-31', freq='D')
323
returns = pd.Series(np.random.normal(0.001, 0.02, len(dates)), index=dates)
324

325
# Create comprehensive performance snapshot
326
qs.plots.snapshot(returns, title="Portfolio Performance Analysis")
327

328
# Plot cumulative returns
329
qs.plots.returns(returns, figsize=(12, 8))
330

331
# Visualize drawdowns
332
qs.plots.drawdown(returns)
333
```
334

335
### Benchmarking Visualization
336

337
```python
338
# Load benchmark data
339
spy_returns = qs.utils.download_returns('SPY')
340

341
# Compare against benchmark
342
qs.plots.returns(returns, benchmark=spy_returns, title="Portfolio vs SPY")
343
qs.plots.rolling_sharpe(returns, benchmark=spy_returns)
344
qs.plots.monthly_heatmap(returns, benchmark=spy_returns)
345
```
346

347
### Distribution Analysis
348

349
```python
350
# Analyze return distributions
351
qs.plots.distribution(returns)
352
qs.plots.histogram(returns, resample='ME')  # Monthly returns histogram
353
qs.plots.yearly_returns(returns)  # Annual performance bars
354
```
355

356
## Constants
357

358
```python { .api }
359
_FLATUI_COLORS: list
360
    """Default color palette for plots"""
361

362
_GRAYSCALE_COLORS: list
363
    """Grayscale color palette for professional presentations"""
364

365
_HAS_PLOTLY: bool
366
    """Boolean indicating whether Plotly is available for interactive plots"""
367
```