Make plotly a first-class plotting backend

[ecomodeller]

Summary

backend="plotly" used to exist on exactly two plots (scatter and Comparer.plot.timeseries), silently ignore figsize, and blow up with plotly's internal Bad property path: cmap if you passed a matplotlib argument. The plotly scatter also called fig.show() and returned None.

This makes plotly a peer of matplotlib rather than a special case.

Same plots.backend= is now on every plot method: scatter, hist, kde, qq, box, residual_hist and taylor on both Comparer and ComparerCollection; Comparer.plot.timeseries; ComparerCollection.plot.spatial_overview and .temporal_coverage; the timeseries/hist plots on observations and model results; and the standalone functions in ms.plotting including wind_rose.

Same arguments.figsize is in inches for both backends and is translated to plotly's width/height. ax is rejected with a clear message on the plotly backend instead of being silently dropped. A matplotlib-only argument now gets a modelskill error naming the offending keyword and pointing at the plotly layout reference. Directional quantities get a 0-360 compass axis in plotly too.

Same contract. Every plot returns a figure/axes; the plotly scatter no longer calls fig.show().

New plotting/_backend.py owns the backend vocabulary (names, validation, return types, rejecting ax), and plotting/_plotly.py owns the plotly renderers plus the plotly layout interop (the optional import, figsize translation, directional axes), so there is one place to look for plotly behaviour and _backend.py stays backend-neutral.

Deliberate breaking changes

1. The plotly scatter no longer displays itself -- it used to call fig.show() and return None. Notebooks still render it as the cell result; scripts need .show().
2. plotly scatter default size 600x600 -> 800x800, because figsize (default (8, 8)) is now honored.
3. **kwargs on the matplotlib Comparer.plot.timeseries are no longer ignored -- they are forwarded to Series.plot(). cmp.plot.timeseries(width=1000) used to do nothing silently and now raises; width is a plotly argument.
4. ax= with backend="plotly" now raises on timeseries instead of being silently ignored (scatter already raised).
5. Invalid-backend message changed from "Plotting backend: x not supported" / "backend must be one of [...]" to "Invalid backend 'x'. Valid options are: [...]".
6. Non-uniform histogram bin edges raise on the plotly backend. plotly's xbins can only express uniformly spaced bins, so hist(bins=[0, 0.5, 1.0, 3.0], backend="plotly") raises rather than silently drawing uniform bins. Note also that an integer bins is an upper bound to plotly, not an exact bin count.
7. PlotlyTimeSeriesPlotter removed from the private modelskill.timeseries._plotter. Backend is a per-call argument now, so the two plotter classes collapse into one TimeSeriesPlotter (MatplotlibTimeSeriesPlotter kept as an alias, TimeSeries.plotter still resolves).

1-4 are all cases where the old behaviour was silently wrong. Worth a changelog line.

Docs

The plotting user guide has a new Backends section, and renders the observation timeseries and the comparer scatter with both backends so the interactive version is on the page. plotly is now explicit in the docs dependency group (the docs build got it via dev by accident).

Notes for review

• The taylor plotly diagram draws dotted centered-RMS-difference contours rather than matplotlib's labelled contour set; the reference point, correlation ticks and radial std axis match.
• spatial_overview's domain-geometry lookup moved to a _model_geometry helper shared by both backends.
• _reglabel moved to _misc.reglabel and the residual grey to _misc.RESIDUAL_COLOR (both used by both backends); _scatter_plotly moved to _plotly.scatter.
• directional is now an argument to ms.plotting.scatter handled by both backends, rather than a tick fixup applied by the callers afterwards. A directional scatter spans 0-360 unless xlim/ylim say otherwise, which is what matplotlib already did.
• spatial_overview classifies observations once for both backends, so plotly raises on an unsupported observation type rather than dropping it silently.
• Worth a second opinion on whether TimeSeries.plotter should go entirely now that nothing swaps it.
• The plotly extra itself is not installed by CI; plotly comes in via the test dependency group, so the missing-plotly path is covered by a unit test rather than end to end.

🤖 Generated with Claude Code