release: v0.12.0

docs/plotly_migration_plan.md

@@ -0,0 +1,100 @@
+# Plan: replace matplotlib with plotly in `manifoldbt.plot`
+
+Branch: `feat/plot-plotly-backend`
+
+## Why
+
+Decision from the plotting benchmark (research/plotting_bench/): plotly is the
+single interactive renderer going forward. It has a native Python API (already
+an optional dependency and already used by `chart(interactive=True)`), covers
+2D and 3D, has no watermark or attribution constraint (MIT), and its rendered
+output is markedly more modern than the current matplotlib charts. Every chart
+gains crosshair, hover tooltips, wheel-zoom and pan for free, and the tearsheet
+upgrades from static base64 PNGs to fully interactive embedded charts.
+
+## Scope
+
+`crates/bt-python/python/manifoldbt/plot/` (2,922 lines, 19 public functions)
+plus `sweep.py:plot_metric` and packaging metadata. The Rust side is untouched.
+
+## Public API contract (kept)
+
+Every public function keeps its name, module, required arguments and data
+semantics. What changes:
+
+| Aspect | Before | After |
+|---|---|---|
+| Return type | matplotlib `Figure` | plotly `go.Figure` |
+| `show=True` | `plt.show()` window | browser tab (plotly `fig.show()`) |
+| `save=` | `.png` via Agg | `.html` (interactive, responsive) or `.png/.svg/.pdf` via kaleido |
+| `ax=` param | draw into given Axes | accepted, ignored (deprecation note in docstring) |
+| `figsize=` | inches | accepted, mapped to pixels (x80) for the default layout size |
+| Theme | rcParams dict | plotly template registered as `manifoldbt` |
+
+Composition changes: `tearsheet()` no longer renders sub-charts through `ax=`;
+it embeds each chart's interactive div directly (see below).
+
+## File-by-file
+
+1. `_theme.py` -- keep the palette constants (they are imported across the
+   module and by user code). Replace the rcParams THEME with a plotly layout
+   template (`go.layout.Template`) using the same colors, fonts and grid alpha.
+   `apply_theme()` registers it and sets it as default; `theme_context()` kept
+   as a no-op context manager for backcompat. Colorscales `bt_diverging`,
+   `bt_sequential`, `bt_correlation` become plain colorscale lists.
+
+2. `_utils.py` -- `finalize(fig, show, save)` routes: `.html` via `write_html`
+   (responsive full-window CSS, `displayModeBar: False`), image extensions via
+   `write_image` with a clear error if kaleido is missing, `show` via
+   `fig.show()`. `get_or_create_ax` replaced by `new_figure(figsize, title)`.
+   `format_pct`, `format_currency`, `auto_title` unchanged.
+
+3. `_decimate.py` (new) -- min/max per pixel-column decimation (pure numpy,
+   from research/plotting_bench/decimate.py, measured: 1.16 ms at 1M points,
+   exact on extremes). Applied to equity/drawdown/benchmark series above
+   ~20k points so saved HTML stays light at 1m resolution.
+
+4. `backtest.py` -- port all 10 functions to plotly. Equity gets the gradient
+   fill + crosshair look validated in research/plotting_bench/equity/.
+   `monthly_returns` becomes `go.Heatmap` with annotations, `annual_returns`
+   a colored bar, histograms are prebinned with numpy then drawn as `go.Bar`
+   so per-bin green/red coloring is preserved, `summary` is a 3-row
+   `make_subplots` with shared x. Rolling charts keep index x (as today).
+
+5. `chart.py` -- `_chart_interactive` (already plotly) becomes the only path;
+   `_draw_candles` and the matplotlib branch are deleted. `interactive=` kept
+   and ignored. The `n_bars` default can later be raised now that candles are
+   vectorized, out of scope here.
+
+6. `research.py` -- `heatmap_2d` and `correlation_matrix` become `go.Heatmap`;
+   `surface_3d` becomes `go.Surface` (camera/lighting tuned in
+   research/plotting_bench/equity/plot_surface_plotly.py); `walk_forward`
+   keeps its three modes on `make_subplots`; `stability` line + band;
+   `monte_carlo` / `stochastic_paths` keep their simulation logic (including
+   the Community 1,000-sim cap) and render the fan with one batched trace for
+   sample paths (None-separated) plus percentile fills and a stats annotation.
+
+7. `tearsheet.py` -- the report keeps its layout and CSS but each chart slot
+   embeds `fig.to_html(full_html=False, include_plotlyjs=False)` instead of a
+   base64 PNG; plotly.js is included once (param `plotlyjs="cdn"|"inline"`,
+   default cdn; inline gives a fully offline report at +4.4 MB).
+   `research_report` returns plotly figures and saves `.html` per figure.
+
+8. Packaging and stragglers -- `pyproject.toml`: `plot = ["plotly>=5.0"]`
+   (kaleido documented for static export, not forced: it ships Chromium,
+   portability-first). `all`/`dev` extras updated. `plot/__init__.py` import
+   guard checks plotly. `sweep.py:plot_metric` rewritten to delegate to
+   `plot.heatmap_2d` / a plotly bar.
+
+## Testing
+
+Smoke script (scratchpad) renders every public function against a real
+backtest (RSI long-only, 10 perps, 2021-2026) and the real 156k sweep grid,
+saving `.html` + `.png` for each; PNGs eyeballed before commit. Existing
+pytest suite run to catch import regressions.
+
+## Out of scope
+
+Window mode (`--app`) helper, decimation inside the Rust core, raising the
+candlestick `n_bars` default, removing matplotlib from the `dev` extra while
+other tooling still uses it (bench scripts).