Coverage for src / jquantstats / _reports / _portfolio.py: 100%

1"""HTML report generation for portfolio analytics. 

2 

3This module defines the Report facade which produces a self-contained HTML 

4document containing all relevant performance numbers and interactive Plotly 

5visualisations for a Portfolio. 

6 

7Examples: 

8 >>> import dataclasses 

9 >>> from jquantstats._reports import Report 

10 >>> dataclasses.is_dataclass(Report) 

11 True 

12""" 

13 

14from __future__ import annotations 

15 

16import dataclasses 

17import math 

18from pathlib import Path 

19from typing import TYPE_CHECKING, TypeGuard 

20 

21import plotly.graph_objects as go 

22import plotly.io as pio 

23import polars as pl 

24from jinja2 import Environment, FileSystemLoader, select_autoescape 

25 

26if TYPE_CHECKING: 

27 from ._protocol import PortfolioLike 

28 

29# templates/ lives one level above this subpackage (at src/jquantstats/templates/) 

30_TEMPLATES_DIR = Path(__file__).parent.parent / "templates" 

31_env = Environment( 

32 loader=FileSystemLoader(_TEMPLATES_DIR), 

33 autoescape=select_autoescape(["html"]), 

34) 

35 

36 

37# ── Formatting helpers ──────────────────────────────────────────────────────── 

38 

39 

40def _is_finite(v: object) -> TypeGuard[int | float]: 

41 """Return True when *v* is a real, finite number.""" 

42 if not isinstance(v, (int, float)): 

43 return False 

44 return math.isfinite(float(v)) 

45 

46 

47def _fmt(value: object, fmt: str = ".4f", suffix: str = "") -> str: 

48 """Format *value* for display in an HTML table cell. 

49 

50 Returns ``"N/A"`` for ``None``, ``NaN``, or non-finite values. 

51 """ 

52 if not _is_finite(value): 

53 return "N/A" 

54 return f"{float(value):{fmt}}{suffix}" 

55 

56 

57# ── Stats table ─────────────────────────────────────────────────────────────── 

58 

59_METRIC_FORMATS: dict[str, tuple[str, str]] = { 

60 "avg_return": (".6f", ""), 

61 "avg_win": (".6f", ""), 

62 "avg_loss": (".6f", ""), 

63 "best": (".6f", ""), 

64 "worst": (".6f", ""), 

65 "sharpe": (".2f", ""), 

66 "calmar": (".2f", ""), 

67 "recovery_factor": (".2f", ""), 

68 "max_drawdown": (".2%", ""), 

69 "avg_drawdown": (".2%", ""), 

70 "max_drawdown_duration": (".0f", " days"), 

71 "win_rate": (".1%", ""), 

72 "monthly_win_rate": (".1%", ""), 

73 "profit_factor": (".2f", ""), 

74 "payoff_ratio": (".2f", ""), 

75 "volatility": (".2%", ""), 

76 "skew": (".2f", ""), 

77 "kurtosis": (".2f", ""), 

78 "value_at_risk": (".6f", ""), 

79 "conditional_value_at_risk": (".6f", ""), 

80} 

81 

82_METRIC_LABELS: dict[str, str] = { 

83 "avg_return": "Avg Return", 

84 "avg_win": "Avg Win", 

85 "avg_loss": "Avg Loss", 

86 "best": "Best Period", 

87 "worst": "Worst Period", 

88 "sharpe": "Sharpe Ratio", 

89 "calmar": "Calmar Ratio", 

90 "recovery_factor": "Recovery Factor", 

91 "max_drawdown": "Max Drawdown", 

92 "avg_drawdown": "Avg Drawdown", 

93 "max_drawdown_duration": "Max DD Duration", 

94 "win_rate": "Win Rate", 

95 "monthly_win_rate": "Monthly Win Rate", 

96 "profit_factor": "Profit Factor", 

97 "payoff_ratio": "Payoff Ratio", 

98 "volatility": "Volatility (ann.)", 

99 "skew": "Skewness", 

100 "kurtosis": "Kurtosis", 

101 "value_at_risk": "VaR (95 %)", 

102 "conditional_value_at_risk": "CVaR (95 %)", 

103} 

104 

105# Metrics where the *highest* value across assets is highlighted. 

106_HIGHER_IS_BETTER: frozenset[str] = frozenset( 

107 {"sharpe", "calmar", "recovery_factor", "win_rate", "monthly_win_rate", "profit_factor", "payoff_ratio"} 

108) 

109 

110_CATEGORIES: list[tuple[str, list[str]]] = [ 

111 ("Returns", ["avg_return", "avg_win", "avg_loss", "best", "worst"]), 

112 ("Risk-Adjusted Performance", ["sharpe", "calmar", "recovery_factor"]), 

113 ("Drawdown", ["max_drawdown", "avg_drawdown", "max_drawdown_duration"]), 

114 ("Win / Loss", ["win_rate", "monthly_win_rate", "profit_factor", "payoff_ratio"]), 

115 ("Distribution & Risk", ["volatility", "skew", "kurtosis", "value_at_risk", "conditional_value_at_risk"]), 

116] 

117 

118 

119def _stats_table_html(summary: pl.DataFrame) -> str: 

120 """Render a stats summary DataFrame as a styled HTML table. 

121 

122 Args: 

123 summary: Output of :py:meth:`Stats.summary` — one row per metric, 

124 one column per asset plus a ``metric`` column. 

125 

126 Returns: 

127 An HTML ``<table>`` string ready to embed in a page. 

128 """ 

129 assets = [c for c in summary.columns if c != "metric"] 

130 

131 # Build a fast lookup: metric_name → {asset: value} 

132 metric_data: dict[str, dict[str, object]] = {} 

133 for row in summary.iter_rows(named=True): 

134 name = str(row["metric"]) 

135 metric_data[name] = {a: row.get(a) for a in assets} 

136 

137 header_cells = "".join(f'<th class="asset-header">{a}</th>' for a in assets) 

138 rows_html_parts: list[str] = [] 

139 

140 for category_label, metrics in _CATEGORIES: 

141 rows_html_parts.append( 

142 f'<tr class="table-section-header">' 

143 f'<td colspan="{len(assets) + 1}"><strong>{category_label}</strong></td>' 

144 f"</tr>\n" 

145 ) 

146 for metric in metrics: 

147 if metric not in metric_data: 

148 continue 

149 fmt, suffix = _METRIC_FORMATS.get(metric, (".4f", "")) 

150 label = _METRIC_LABELS.get(metric, metric.replace("_", " ").title()) 

151 values = metric_data[metric] 

152 

153 # Find the best asset to highlight (only for higher-is-better metrics) 

154 best_asset: str | None = None 

155 if metric in _HIGHER_IS_BETTER: 

156 finite_pairs = [(a, float(v)) for a, v in values.items() if _is_finite(v)] 

157 if finite_pairs: 

158 best_asset = max(finite_pairs, key=lambda x: x[1])[0] 

159 

160 cells = "".join( 

161 f'<td class="metric-value{" best-value" if a == best_asset else ""}">' 

162 f"{_fmt(values.get(a), fmt, suffix)}</td>" 

163 for a in assets 

164 ) 

165 rows_html_parts.append(f'<tr><td class="metric-name">{label}</td>{cells}</tr>\n') 

166 

167 rows_html = "".join(rows_html_parts) 

168 return ( 

169 '<table class="stats-table">' 

170 "<thead><tr>" 

171 f'<th class="metric-header">Metric</th>{header_cells}' 

172 "</tr></thead>" 

173 f"<tbody>{rows_html}</tbody>" 

174 "</table>" 

175 ) 

176 

177 

178# ── Report dataclass ────────────────────────────────────────────────────────── 

179 

180 

181def _figure_div(fig: go.Figure, include_plotlyjs: bool | str) -> str: 

182 """Return an HTML div string for *fig*. 

183 

184 Args: 

185 fig: Plotly figure to serialise. 

186 include_plotlyjs: Passed directly to :func:`plotly.io.to_html`. 

187 Pass ``"cdn"`` for the first figure so the CDN script tag is 

188 injected; pass ``False`` for all subsequent figures. 

189 

190 Returns: 

191 HTML string (not a full page). 

192 """ 

193 return pio.to_html( 

194 fig, 

195 full_html=False, 

196 include_plotlyjs=include_plotlyjs, 

197 ) 

198 

199 

200@dataclasses.dataclass(frozen=True) 

201class Report: 

202 """Facade for generating HTML reports from a Portfolio. 

203 

204 Provides a :py:meth:`to_html` method that assembles a self-contained, 

205 dark-themed HTML document with a performance-statistics table and 

206 multiple interactive Plotly charts. 

207 

208 Usage:: 

209 

210 report = portfolio.report 

211 html_str = report.to_html() 

212 report.save("output/report.html") 

213 """ 

214 

215 portfolio: PortfolioLike 

216 

217 def to_html(self, title: str = "JQuantStats Portfolio Report") -> str: 

218 """Render a full HTML report as a string. 

219 

220 The document is self-contained: Plotly.js is loaded once from the 

221 CDN and all charts are embedded as ``<div>`` elements. No external 

222 CSS framework is required. 

223 

224 Args: 

225 title: HTML ``<title>`` text and visible page heading. 

226 

227 Returns: 

228 A complete HTML document as a :class:`str`. 

229 """ 

230 pf = self.portfolio 

231 

232 # ── Metadata ────────────────────────────────────────────────────────── 

233 has_date = "date" in pf.prices.columns 

234 if has_date: 

235 dates = pf.prices["date"] 

236 start_date = str(dates.min()) 

237 end_date = str(dates.max()) 

238 n_periods = pf.prices.height 

239 period_info = f"{start_date} → {end_date} &nbsp;|&nbsp; {n_periods:,} periods" 

240 else: 

241 start_date = "" 

242 end_date = "" 

243 period_info = f"{pf.prices.height:,} periods" 

244 

245 assets_list = ", ".join(pf.assets) 

246 

247 # ── Figures ─────────────────────────────────────────────────────────── 

248 # The first chart includes Plotly.js from CDN; subsequent ones reuse it. 

249 _first = True 

250 

251 def _div(fig: go.Figure) -> str: 

252 """Serialise *fig* to an HTML div, embedding Plotly.js only on the first call.""" 

253 nonlocal _first 

254 include = "cdn" if _first else False 

255 _first = False 

256 return _figure_div(fig, include) 

257 

258 def _try_div(build_fig: object) -> str: 

259 """Call *build_fig()* and return the chart div; on error return a notice.""" 

260 try: 

261 fig = build_fig() # type: ignore[operator] 

262 return _div(fig) 

263 except Exception as exc: 

264 return f'<p class="chart-unavailable">Chart unavailable: {exc}</p>' 

265 

266 snapshot_div = _try_div(pf.plots.snapshot) 

267 rolling_sharpe_div = _try_div(pf.plots.rolling_sharpe_plot) 

268 rolling_vol_div = _try_div(pf.plots.rolling_volatility_plot) 

269 annual_sharpe_div = _try_div(pf.plots.annual_sharpe_plot) 

270 monthly_heatmap_div = _try_div(pf.plots.monthly_returns_heatmap) 

271 corr_div = _try_div(pf.plots.correlation_heatmap) 

272 lead_lag_div = _try_div(pf.plots.lead_lag_ir_plot) 

273 trading_cost_div = _try_div(pf.plots.trading_cost_impact_plot) 

274 

275 # ── Stats table ─────────────────────────────────────────────────────── 

276 stats_table = _stats_table_html(pf.stats.summary()) 

277 

278 # ── Turnover table ──────────────────────────────────────────────────── 

279 try: 

280 turnover_df = pf.turnover_summary() 

281 turnover_rows = "".join( 

282 f'<tr><td class="metric-name">{row["metric"].replace("_", " ").title()}</td>' 

283 f'<td class="metric-value">{row["value"]:.4f}</td></tr>' 

284 for row in turnover_df.iter_rows(named=True) 

285 ) 

286 turnover_html = ( 

287 '<table class="stats-table">' 

288 "<thead><tr>" 

289 '<th class="metric-header">Metric</th>' 

290 '<th class="asset-header">Value</th>' 

291 "</tr></thead>" 

292 f"<tbody>{turnover_rows}</tbody>" 

293 "</table>" 

294 ) 

295 except Exception as exc: 

296 turnover_html = f'<p class="chart-unavailable">Turnover data unavailable: {exc}</p>' 

297 

298 # ── Assemble HTML ───────────────────────────────────────────────────── 

299 footer_date = end_date if has_date else "" 

300 template = _env.get_template("portfolio_report.html") 

301 return template.render( 

302 title=title, 

303 period_info=period_info, 

304 assets_list=assets_list, 

305 aum=f"{pf.aum:,.0f}", 

306 footer_date=footer_date, 

307 snapshot_div=snapshot_div, 

308 rolling_sharpe_div=rolling_sharpe_div, 

309 rolling_vol_div=rolling_vol_div, 

310 annual_sharpe_div=annual_sharpe_div, 

311 monthly_heatmap_div=monthly_heatmap_div, 

312 corr_div=corr_div, 

313 lead_lag_div=lead_lag_div, 

314 trading_cost_div=trading_cost_div, 

315 stats_table=stats_table, 

316 turnover_html=turnover_html, 

317 container_max_width="1400px", 

318 ) 

319 

320 def save(self, path: str | Path, title: str = "JQuantStats Portfolio Report") -> Path: 

321 """Save the HTML report to a file. 

322 

323 A ``.html`` suffix is appended automatically when *path* has no 

324 file extension. 

325 

326 Args: 

327 path: Destination file path. 

328 title: HTML ``<title>`` text and visible page heading. 

329 

330 Returns: 

331 The resolved :class:`pathlib.Path` of the written file. 

332 """ 

333 p = Path(path) 

334 if not p.suffix: 

335 p = p.with_suffix(".html") 

336 p.parent.mkdir(parents=True, exist_ok=True) 

337 p.write_text(self.to_html(title=title), encoding="utf-8") 

338 return p