quantwave_backtest/
tearsheet.rs

1//! HTML tear sheet generator for [`BacktestReport`] (quantwave-0gi1).
2//!
3//! Produces a single self-contained HTML file with summary metrics, equity curve,
4//! drawdown chart, and trade statistics — no external JS/CSS dependencies.
5
6use crate::{BacktestReport, PerformanceMetrics};
7use polars::prelude::*;
8
9/// Options for HTML tear sheet rendering.
10#[derive(Debug, Clone)]
11pub struct TearsheetOptions {
12    pub title: String,
13    pub width: u32,
14    pub height: u32,
15}
16
17impl Default for TearsheetOptions {
18    fn default() -> Self {
19        Self {
20            title: "QuantWave Backtest Report".to_string(),
21            width: 720,
22            height: 220,
23        }
24    }
25}
26
27/// Render a self-contained HTML tear sheet from a completed backtest report.
28pub fn render_tearsheet_html(report: &BacktestReport, options: &TearsheetOptions) -> String {
29    let equity = extract_f64_column(&report.result.equity_curve, "equity");
30    let drawdown = compute_drawdown_pct(&equity);
31    let metrics = &report.metrics;
32
33    let equity_svg = line_chart_svg(&equity, options.width, options.height, "#2563eb", "Equity");
34    let dd_svg = line_chart_svg(&drawdown, options.width, options.height, "#dc2626", "Drawdown %");
35
36    let metrics_table = metrics_table_html(metrics);
37    let trade_table = trade_stats_html(&report.result.trades);
38    let stats_extra = stats_kv_html(&report.result.stats);
39
40    format!(
41        r##"<!DOCTYPE html>
42<html lang="en">
43<head>
44<meta charset="utf-8"/>
45<meta name="viewport" content="width=device-width, initial-scale=1"/>
46<title>{title}</title>
47<style>
48  body {{ font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif; margin: 24px; color: #111; background: #fafafa; }}
49  h1 {{ font-size: 1.5rem; margin-bottom: 0.25rem; }}
50  .subtitle {{ color: #555; margin-bottom: 1.5rem; font-size: 0.9rem; }}
51  .grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; }}
52  .card {{ background: #fff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; }}
53  .card h2 {{ font-size: 1rem; margin: 0 0 12px; color: #374151; }}
54  table {{ width: 100%; border-collapse: collapse; font-size: 0.875rem; }}
55  th, td {{ text-align: left; padding: 6px 8px; border-bottom: 1px solid #f3f4f6; }}
56  th {{ color: #6b7280; font-weight: 600; }}
57  svg {{ max-width: 100%; height: auto; }}
58  .footer {{ margin-top: 24px; font-size: 0.75rem; color: #9ca3af; }}
59</style>
60</head>
61<body>
62  <h1>{title}</h1>
63  <p class="subtitle">Generated by QuantWave backtest engine</p>
64  <div class="grid">
65    <div class="card"><h2>Performance Metrics</h2>{metrics_table}</div>
66    <div class="card"><h2>Run Stats</h2>{stats_extra}</div>
67  </div>
68  <div class="grid" style="margin-top:16px">
69    <div class="card"><h2>Equity Curve</h2>{equity_svg}</div>
70    <div class="card"><h2>Drawdown</h2>{dd_svg}</div>
71  </div>
72  <div class="card" style="margin-top:16px"><h2>Trade Summary</h2>{trade_table}</div>
73  <p class="footer">QuantWave · batch/streaming parity backtest · not investment advice</p>
74</body>
75</html>"##,
76        title = html_escape(&options.title),
77        metrics_table = metrics_table,
78        stats_extra = stats_extra,
79        equity_svg = equity_svg,
80        dd_svg = dd_svg,
81        trade_table = trade_table,
82    )
83}
84
85fn extract_f64_column(df: &DataFrame, name: &str) -> Vec<f64> {
86    df.column(name)
87        .ok()
88        .and_then(|c| c.f64().ok())
89        .map(|ca| ca.into_iter().map(|v| v.unwrap_or(f64::NAN)).collect())
90        .unwrap_or_default()
91}
92
93fn compute_drawdown_pct(equity: &[f64]) -> Vec<f64> {
94    let mut peak = f64::NEG_INFINITY;
95    equity
96        .iter()
97        .map(|&e| {
98            if e.is_nan() {
99                return f64::NAN;
100            }
101            if e > peak {
102                peak = e;
103            }
104            if peak <= 0.0 {
105                0.0
106            } else {
107                (peak - e) / peak * 100.0
108            }
109        })
110        .collect()
111}
112
113fn line_chart_svg(values: &[f64], width: u32, height: u32, color: &str, label: &str) -> String {
114    let valid: Vec<f64> = values.iter().copied().filter(|v| v.is_finite()).collect();
115    if valid.is_empty() {
116        return format!("<p>No {label} data</p>");
117    }
118    let min_v = valid.iter().copied().fold(f64::INFINITY, f64::min);
119    let max_v = valid.iter().copied().fold(f64::NEG_INFINITY, f64::max);
120    let range = (max_v - min_v).max(1e-12);
121    let w = width as f64;
122    let h = height as f64;
123    let pad = 8.0;
124    let n = valid.len().max(2);
125
126    let points: String = valid
127        .iter()
128        .enumerate()
129        .map(|(i, &v)| {
130            let x = pad + (i as f64 / (n - 1) as f64) * (w - 2.0 * pad);
131            let y = pad + (1.0 - (v - min_v) / range) * (h - 2.0 * pad);
132            format!("{x:.1},{y:.1}")
133        })
134        .collect::<Vec<_>>()
135        .join(" ");
136
137    format!(
138        r##"<svg viewBox="0 0 {width} {height}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="{label}">
139  <rect width="100%" height="100%" fill="#f9fafb"/>
140  <polyline fill="none" stroke="{color}" stroke-width="2" points="{points}"/>
141</svg>"##,
142        width = width,
143        height = height,
144        color = color,
145        label = html_escape(label),
146        points = points,
147    )
148}
149
150fn metrics_table_html(m: &PerformanceMetrics) -> String {
151    let rows = [
152        ("Trades", format_num(m.num_trades, 0)),
153        ("Win rate", format_pct(m.win_rate)),
154        ("Profit factor", format_num(m.profit_factor, 2)),
155        ("Max drawdown", format_pct(m.max_drawdown_pct)),
156        ("CAGR", format_pct(m.cagr)),
157        ("Sharpe", format_num(m.sharpe_ratio, 2)),
158        ("Sortino", format_num(m.sortino_ratio, 2)),
159        ("Total return", format_pct(m.total_return)),
160        ("Final equity", format_num(m.final_equity, 2)),
161        ("Avg trade PnL", format_num(m.avg_trade_pnl, 2)),
162    ];
163    table_from_pairs(&rows)
164}
165
166fn stats_kv_html(stats: &std::collections::HashMap<String, f64>) -> String {
167    if stats.is_empty() {
168        return "<p>No run stats</p>".to_string();
169    }
170    let mut keys: Vec<_> = stats.keys().collect();
171    keys.sort();
172    let rows: Vec<(&str, String)> = keys
173        .iter()
174        .map(|k| (k.as_str(), format_num(stats[*k], 4)))
175        .collect();
176    table_from_pairs(&rows)
177}
178
179fn trade_stats_html(trades: &DataFrame) -> String {
180    let height = trades.height();
181    if height == 0 {
182        return "<p>No trades recorded</p>".to_string();
183    }
184    let pnls = extract_f64_column(trades, "pnl_net");
185    let wins = pnls.iter().filter(|p| **p > 0.0).count();
186    let losses = pnls.iter().filter(|p| **p <= 0.0).count();
187    let best = pnls.iter().copied().fold(f64::NEG_INFINITY, f64::max);
188    let worst = pnls.iter().copied().fold(f64::INFINITY, f64::min);
189    let sum: f64 = pnls.iter().sum();
190
191    let rows = [
192        ("Closed trades", height.to_string()),
193        ("Winning", wins.to_string()),
194        ("Losing", losses.to_string()),
195        ("Net PnL (sum)", format_num(sum, 2)),
196        ("Best trade", format_num(best, 2)),
197        ("Worst trade", format_num(worst, 2)),
198    ];
199    table_from_pairs(&rows)
200}
201
202fn table_from_pairs(rows: &[(&str, String)]) -> String {
203    let body: String = rows
204        .iter()
205        .map(|(k, v)| format!("<tr><th>{}</th><td>{}</td></tr>", html_escape(k), html_escape(v)))
206        .collect();
207    format!("<table><tbody>{body}</tbody></table>")
208}
209
210fn format_num(v: f64, decimals: usize) -> String {
211    if !v.is_finite() {
212        return "—".to_string();
213    }
214    format!("{:.prec$}", v, prec = decimals)
215}
216
217fn format_pct(v: f64) -> String {
218    if !v.is_finite() {
219        return "—".to_string();
220    }
221    format!("{:.2}%", v * 100.0)
222}
223
224fn html_escape(s: &str) -> String {
225    s.replace('&', "&amp;")
226        .replace('<', "&lt;")
227        .replace('>', "&gt;")
228        .replace('"', "&quot;")
229}
230
231#[cfg(test)]
232mod tests {
233    use super::*;
234    use crate::{BacktestConfig, BacktestEngine};
235    use polars::prelude::*;
236
237    fn mini_report() -> BacktestReport {
238        let df = DataFrame::new(vec![
239            Column::new("timestamp".into(), (0i64..6).collect::<Vec<_>>()),
240            Column::new("close".into(), vec![100.0, 101.0, 102.5, 103.0, 102.0, 101.0]),
241            Column::new("signal".into(), vec![0.0, 1.0, 1.0, 1.0, 0.0, 0.0]),
242        ])
243        .unwrap();
244        BacktestEngine::new(BacktestConfig::default())
245            .backtest_with_report(df.lazy())
246            .unwrap()
247    }
248
249    #[test]
250    fn tearsheet_html_contains_core_sections() {
251        let html = render_tearsheet_html(&mini_report(), &TearsheetOptions::default());
252        assert!(html.contains("<!DOCTYPE html>"));
253        assert!(html.contains("Performance Metrics"));
254        assert!(html.contains("Equity Curve"));
255        assert!(html.contains("Drawdown"));
256        assert!(html.contains("Trade Summary"));
257        assert!(html.contains("<svg"));
258    }
259}
quantwave_backtest/tearsheet.rs

quantwave_backtest/
tearsheet.rs
