0
# Report Generation
1

2
Professional tearsheet and report generation capabilities including comprehensive HTML reports, performance metrics tables, and customizable analysis layouts with benchmarking support for institutional-grade portfolio reporting.
3

4
## Capabilities
5

6
### HTML Report Generation
7

8
Create comprehensive HTML tearsheets with embedded charts and detailed analytics.
9

10
```python { .api }
11
def html(returns, benchmark=None, rf=0.0, grayscale=False, title="Strategy Tearsheet", output=None, download_filename="quantstats-tearsheet.html", figfmt="svg", template_path=None, match_dates=True, **kwargs):
12
    """
13
    Generate comprehensive HTML tearsheet report.
14
    
15
    Parameters:
16
    - returns: pandas Series of portfolio returns
17
    - benchmark: pandas Series of benchmark returns (optional)
18
    - rf: float, risk-free rate (default 0.0)
19
    - grayscale: bool, whether to use grayscale color scheme
20
    - title: str, report title
21
    - output: str, output file path (optional)
22
    - download_filename: str, default filename for download
23
    - figfmt: str, figure format ('svg', 'png', 'jpg')
24
    - template_path: str, path to custom HTML template
25
    - match_dates: bool, whether to match portfolio and benchmark dates
26
    - **kwargs: additional parameters
27
    
28
    Returns:
29
    str: HTML content string
30
    """
31

32
def full(returns, benchmark=None, rf=0.0, grayscale=False, figsize=(10, 8), display=True, compounded=True, **kwargs):
33
    """
34
    Generate full performance report with plots and metrics.
35
    
36
    Parameters:
37
    - returns: pandas Series of portfolio returns
38
    - benchmark: pandas Series of benchmark returns (optional)
39
    - rf: float, risk-free rate
40
    - grayscale: bool, whether to use grayscale colors
41
    - figsize: tuple, figure size for plots
42
    - display: bool, whether to display the report
43
    - compounded: bool, whether returns are compounded
44
    - **kwargs: additional parameters
45
    
46
    Returns:
47
    dict: Dictionary containing plots and metrics
48
    """
49

50
def basic(returns, benchmark=None, display=True, compounded=True, **kwargs):
51
    """
52
    Generate basic performance metrics report without plots.
53
    
54
    Parameters:
55
    - returns: pandas Series of portfolio returns
56
    - benchmark: pandas Series of benchmark returns (optional)
57
    - display: bool, whether to display the report
58
    - compounded: bool, whether returns are compounded
59
    - **kwargs: additional parameters
60
    
61
    Returns:
62
    pandas DataFrame: Basic performance metrics
63
    """
64
```
65

66
### Metrics Tables
67

68
Generate structured performance metrics tables and summaries.
69

70
```python { .api }
71
def metrics(returns, benchmark=None, rf=0.0, display=True, mode="basic", compounded=True, **kwargs):
72
    """
73
    Generate comprehensive performance metrics table.
74
    
75
    Parameters:
76
    - returns: pandas Series of portfolio returns
77
    - benchmark: pandas Series of benchmark returns (optional)
78
    - rf: float, risk-free rate
79
    - display: bool, whether to display the metrics
80
    - mode: str, metrics mode ('basic', 'full')
81
    - compounded: bool, whether returns are compounded
82
    - **kwargs: additional parameters
83
    
84
    Returns:
85
    pandas DataFrame: Performance metrics table with portfolio and benchmark columns
86
    """
87
```
88

89
### Plot Collections
90

91
Generate complete sets of performance visualizations.
92

93
```python { .api }
94
def plots(returns, benchmark=None, grayscale=False, figsize=(10, 8), **kwargs):
95
    """
96
    Generate comprehensive collection of performance plots.
97
    
98
    Parameters:
99
    - returns: pandas Series of portfolio returns
100
    - benchmark: pandas Series of benchmark returns (optional)  
101
    - grayscale: bool, whether to use grayscale colors
102
    - figsize: tuple, default figure size
103
    - **kwargs: additional plotting parameters
104
    
105
    Returns:
106
    dict: Dictionary of matplotlib Figure objects for each plot type
107
    """
108
```
109

110
## Usage Examples
111

112
### Basic HTML Report
113

114
```python
115
import quantstats as qs
116
import pandas as pd
117

118
# Load portfolio returns
119
returns = pd.read_csv('portfolio_returns.csv', index_col=0, parse_dates=True).squeeze()
120

121
# Generate basic HTML tearsheet
122
qs.reports.html(returns, output='portfolio_tearsheet.html')
123

124
# Generate with benchmark comparison
125
benchmark = qs.utils.download_returns('SPY')
126
qs.reports.html(returns, benchmark=benchmark, 
127
                title="Portfolio vs S&P 500",
128
                output='portfolio_vs_spy.html')
129
```
130

131
### Metrics Analysis
132

133
```python
134
# Generate comprehensive metrics table
135
metrics_df = qs.reports.metrics(returns, benchmark=benchmark, rf=0.02)
136
print(metrics_df)
137

138
# Basic metrics without benchmark
139
basic_metrics = qs.reports.basic(returns)
140
print(basic_metrics)
141
```
142

143
### Custom Report Generation
144

145
```python
146
# Generate full report with custom parameters
147
full_report = qs.reports.full(
148
    returns, 
149
    benchmark=benchmark,
150
    rf=0.025,
151
    grayscale=True,
152
    figsize=(12, 8),
153
    title="Institutional Portfolio Analysis"
154
)
155

156
# Access individual components
157
plots_dict = full_report['plots']
158
metrics_table = full_report['metrics']
159
```
160

161
### Professional Tearsheet with Custom Styling
162

163
```python
164
# Generate professional grayscale tearsheet
165
qs.reports.html(
166
    returns,
167
    benchmark=benchmark,
168
    rf=0.02,
169
    grayscale=True,
170
    title="Quantitative Strategy Performance",
171
    output='strategy_tearsheet.html',
172
    figfmt='svg',  # High-quality vector graphics
173
    download_filename='strategy_analysis.html'
174
)
175
```
176

177
## Report Components
178

179
The HTML reports include the following sections:
180

181
### Performance Summary
182
- Key performance metrics table
183
- Risk-adjusted returns analysis
184
- Drawdown statistics
185
- Win/loss analysis
186

187
### Visualizations
188
- Cumulative returns chart
189
- Rolling Sharpe ratio
190
- Drawdown underwater plot
191
- Monthly returns heatmap
192
- Return distribution histogram
193
- Rolling volatility
194

195
### Risk Analysis
196
- Value at Risk metrics
197
- Tail risk measures
198
- Correlation analysis (when benchmark provided)
199
- Beta analysis (when benchmark provided)
200

201
### Detailed Metrics
202
- Return statistics
203
- Risk metrics
204
- Ratios and factors
205
- Calendar analysis
206

207
## Internal Functions
208

209
```python { .api }
210
def _get_trading_periods(periods_per_year=252):
211
    """
212
    Calculate trading periods for different time windows.
213
    
214
    Parameters:
215
    - periods_per_year: int, number of trading periods per year
216
    
217
    Returns:
218
    dict: Dictionary with trading period information
219
    """
220

221
def _match_dates(returns, benchmark):
222
    """
223
    Match dates between portfolio returns and benchmark.
224
    
225
    Parameters:
226
    - returns: pandas Series of portfolio returns
227
    - benchmark: pandas Series of benchmark returns
228
    
229
    Returns:
230
    tuple: Matched returns and benchmark series
231
    """
232

233
def _calc_dd(df, display=True, as_pct=False):
234
    """
235
    Calculate detailed drawdown analysis.
236
    
237
    Parameters:
238
    - df: pandas DataFrame or Series
239
    - display: bool, whether to display results
240
    - as_pct: bool, whether to format as percentages
241
    
242
    Returns:
243
    pandas DataFrame: Drawdown analysis details
244
    """
245

246
def _html_table(obj, showindex="default"):
247
    """
248
    Convert pandas object to HTML table format.
249
    
250
    Parameters:
251
    - obj: pandas DataFrame or Series
252
    - showindex: str, whether to show index ('default', True, False)
253
    
254
    Returns:
255
    str: HTML table string
256
    """
257

258
def _download_html(html, filename="quantstats-tearsheet.html"):
259
    """
260
    Prepare HTML content for download.
261
    
262
    Parameters:
263
    - html: str, HTML content
264
    - filename: str, download filename
265
    
266
    Returns:
267
    str: Prepared HTML with download headers
268
    """
269

270
def _open_html(html):
271
    """
272
    Open HTML content in default browser.
273
    
274
    Parameters:
275
    - html: str, HTML content
276
    
277
    Returns:
278
    None
279
    """
280

281
def _embed_figure(figfiles, figfmt):
282
    """
283
    Embed figure files into HTML report.
284
    
285
    Parameters:
286
    - figfiles: list, list of figure file paths
287
    - figfmt: str, figure format
288
    
289
    Returns:
290
    str: Embedded HTML figure content
291
    """
292
```