|
| 1 | +--- |
| 2 | +sidebar_position: 9 |
| 3 | +--- |
| 4 | + |
| 5 | +# Backtest Reports |
| 6 | + |
| 7 | +The framework generates self-contained HTML dashboard reports for analyzing backtest results. Reports work for both single and multi-strategy backtests — no external dependencies required. |
| 8 | + |
| 9 | +## Quick Start |
| 10 | + |
| 11 | +```python |
| 12 | +from investing_algorithm_framework import BacktestReport |
| 13 | + |
| 14 | +# Single strategy report |
| 15 | +report = BacktestReport(backtest) |
| 16 | +report.show() # Opens in browser (or renders inline in Jupyter) |
| 17 | +``` |
| 18 | + |
| 19 | +## Creating Reports |
| 20 | + |
| 21 | +### From a Backtest Object |
| 22 | + |
| 23 | +After running a backtest, pass the result directly: |
| 24 | + |
| 25 | +```python |
| 26 | +backtest = app.run_backtest( |
| 27 | + backtest_date_range=backtest_range, |
| 28 | + initial_amount=1000 |
| 29 | +) |
| 30 | + |
| 31 | +report = BacktestReport(backtest) |
| 32 | +report.show(browser=True) |
| 33 | +``` |
| 34 | + |
| 35 | +### From Multiple Backtests |
| 36 | + |
| 37 | +Compare strategies side by side in a single dashboard: |
| 38 | + |
| 39 | +```python |
| 40 | +backtest_a = app.run_backtest(...) |
| 41 | +backtest_b = app.run_backtest(...) |
| 42 | + |
| 43 | +report = BacktestReport(backtests=[backtest_a, backtest_b]) |
| 44 | +report.show() |
| 45 | +``` |
| 46 | + |
| 47 | +This generates a multi-strategy comparison dashboard with: |
| 48 | +- Strategy ranking table (sortable by CAGR, Sharpe, Max DD, etc.) |
| 49 | +- Normalized equity curves overlay |
| 50 | +- Per-strategy detail pages with Summary, Runs, and Performance tabs |
| 51 | +- Compare mode for selected strategies |
| 52 | + |
| 53 | +### From Saved Backtests on Disk |
| 54 | + |
| 55 | +Load previously saved backtests from a directory: |
| 56 | + |
| 57 | +```python |
| 58 | +report = BacktestReport.open(directory_path="./my_backtests") |
| 59 | +report.show() |
| 60 | +``` |
| 61 | + |
| 62 | +The `open()` method recursively finds all valid backtest directories (containing `results.json` and `metrics.json`) and loads them into a single report. |
| 63 | + |
| 64 | +You can also combine disk and in-memory backtests: |
| 65 | + |
| 66 | +```python |
| 67 | +report = BacktestReport.open( |
| 68 | + backtests=[my_new_backtest], |
| 69 | + directory_path="./saved_backtests" |
| 70 | +) |
| 71 | +report.show() |
| 72 | +``` |
| 73 | + |
| 74 | +## Saving Reports |
| 75 | + |
| 76 | +Save the report as a standalone HTML file you can share or open later: |
| 77 | + |
| 78 | +```python |
| 79 | +report = BacktestReport(backtests=[backtest_a, backtest_b]) |
| 80 | +report.save("strategy_comparison.html") |
| 81 | +``` |
| 82 | + |
| 83 | +The output is a single `.html` file with all CSS, JavaScript, and data embedded — no server or internet connection needed to view it. |
| 84 | + |
| 85 | +## Viewing in Jupyter |
| 86 | + |
| 87 | +`show()` automatically detects Jupyter notebooks and renders the dashboard inline: |
| 88 | + |
| 89 | +```python |
| 90 | +# In a Jupyter notebook cell: |
| 91 | +report = BacktestReport.open(directory_path="./backtests") |
| 92 | +report.show() # Renders inline in the notebook |
| 93 | +report.show(browser=True) # Also opens in the browser |
| 94 | +``` |
| 95 | + |
| 96 | +## Dashboard Features |
| 97 | + |
| 98 | +### Overview Page |
| 99 | +- **KPI cards**: Strategies count, backtest windows, best CAGR, best Sharpe, lowest max drawdown |
| 100 | +- **Backtest windows table**: Date ranges, duration, number of strategies per window |
| 101 | +- **Strategy ranking table**: Sortable by any metric, with best-in-class highlighting |
| 102 | +- **Equity curves**: Normalized percentage growth overlay for all strategies |
| 103 | + |
| 104 | +### Strategy Pages |
| 105 | +Each strategy gets a dedicated page with three tabs: |
| 106 | + |
| 107 | +| Tab | Contents | |
| 108 | +|-----|----------| |
| 109 | +| **Summary** | Full KPI grid (CAGR, Sharpe, Sortino, Calmar, Max DD, Profit Factor, Win Rate, Volatility, etc.) | |
| 110 | +| **Runs** | Backtest run comparison table, equity overlay across runs | |
| 111 | +| **Performance** | Monthly returns heatmap, yearly returns bar chart | |
| 112 | + |
| 113 | +Use the run selector pills to switch between summary view and individual backtest runs. |
| 114 | + |
| 115 | +### Compare Mode (Multi-Strategy) |
| 116 | +Select strategies via checkboxes in the ranking table, then click **Compare Selected** to see: |
| 117 | +- Side-by-side equity curves |
| 118 | +- Metric bar charts (CAGR, Sharpe, Max DD, Win Rate) |
| 119 | +- Monthly and yearly return comparisons |
| 120 | + |
| 121 | +### Dark / Light Theme |
| 122 | +Toggle between dark and light mode using the sun icon in the top-right corner. |
| 123 | + |
| 124 | +## Example: Full Workflow |
| 125 | + |
| 126 | +```python |
| 127 | +from datetime import datetime, timezone |
| 128 | +from investing_algorithm_framework import ( |
| 129 | + create_app, BacktestDateRange, BacktestReport |
| 130 | +) |
| 131 | + |
| 132 | +app = create_app() |
| 133 | +# ... configure strategies, market, portfolio ... |
| 134 | + |
| 135 | +# Run backtests across multiple time periods |
| 136 | +date_ranges = [ |
| 137 | + BacktestDateRange( |
| 138 | + start_date=datetime(2022, 1, 1, tzinfo=timezone.utc), |
| 139 | + end_date=datetime(2022, 12, 31, tzinfo=timezone.utc), |
| 140 | + name="2022" |
| 141 | + ), |
| 142 | + BacktestDateRange( |
| 143 | + start_date=datetime(2023, 1, 1, tzinfo=timezone.utc), |
| 144 | + end_date=datetime(2023, 12, 31, tzinfo=timezone.utc), |
| 145 | + name="2023" |
| 146 | + ), |
| 147 | +] |
| 148 | + |
| 149 | +backtests = app.run_vector_backtests( |
| 150 | + strategies=my_strategies, |
| 151 | + backtest_date_ranges=date_ranges, |
| 152 | + initial_amount=1000, |
| 153 | + backtest_storage_directory="./backtests" |
| 154 | +) |
| 155 | + |
| 156 | +# Generate and save the comparison report |
| 157 | +report = BacktestReport(backtests=backtests) |
| 158 | +report.save("comparison_report.html") |
| 159 | +report.show(browser=True) |
| 160 | +``` |
| 161 | + |
| 162 | +## API Reference |
| 163 | + |
| 164 | +### `BacktestReport` |
| 165 | + |
| 166 | +| Method | Description | |
| 167 | +|--------|-------------| |
| 168 | +| `BacktestReport(backtests=[...])` | Create a report from one or more Backtest objects | |
| 169 | +| `BacktestReport(backtest)` | Create a report from a single Backtest (backward compatible) | |
| 170 | +| `BacktestReport.open(directory_path=..., backtests=[...])` | Load backtests from disk and/or combine with in-memory backtests | |
| 171 | +| `report.show(browser=False)` | Display the report. In Jupyter: renders inline. Otherwise: opens browser. Set `browser=True` to force browser. | |
| 172 | +| `report.save(path)` | Save the report as a self-contained HTML file | |
0 commit comments