Make plotly a first-class plotting backend

README.md

@@ -29,6 +29,12 @@ Or the development version:
 pip install https://github.com/DHI/modelskill/archive/main.zip
 ```
 
+Interactive plots (`backend="plotly"`) require an extra dependency:
+
+```bash
+pip install "modelskill[plotly]"
+```
+
 ## Getting started
 
 Define model results and observations:
@@ -62,6 +68,29 @@ c2           113 -0.00  0.35   0.35  0.29  0.98  0.13  0.90
 
 See the [user guide](https://dhi.github.io/modelskill/user-guide/getting-started.html) for more.
 
+## Plotting backends
+
+Plots can either be static and report-friendly ([matplotlib](https://matplotlib.org/), the
+default) or interactive with zoom functionality ([plotly](https://plotly.com/python/)).
+
+```python
+cc["HKNA"].plot.timeseries(figsize=(10, 4), backend="plotly")
+```
+
+![timeseries](https://raw.githubusercontent.com/DHI/modelskill/main/images/plotly_timeseries.png)
+
+Every plot takes a `backend` argument -- `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` and `hist` plots on observations and model results,
+and the standalone functions in `ms.plotting`.
+
+The same arguments (`title`, `figsize` in inches, `xlim`, `ylim`, ...) work with both
+backends. The matplotlib backend returns a `matplotlib.axes.Axes` (or `Figure` for
+`taylor`), the plotly backend a `plotly.graph_objects.Figure`. Extra `**kwargs` go to the
+underlying matplotlib call, or to
+[`Figure.update_layout`](https://plotly.com/python/reference/layout/) respectively.
+
 ## Where can I get help?
 * Documentation - [https://dhi.github.io/modelskill/](https://dhi.github.io/modelskill/)
 * Examples - [https://dhi.github.io/modelskill/examples/](https://dhi.github.io/modelskill/examples/)

docs/user-guide/plotting.qmd

@@ -1,5 +1,22 @@
 # Plotting
 
+## Backends
+
+Every plot can be rendered by either of two backends, selected with the `backend` argument:
+
+* `"matplotlib"` (the default) - static, report-friendly figures, returns a `matplotlib.axes.Axes` (or a `Figure` for `taylor`)
+* `"plotly"` - [interactive](https://plotly.com/python/) figures with zoom and hover, returns a `plotly.graph_objects.Figure`
+
+The plotly backend requires an optional dependency:
+
+```bash
+pip install "modelskill[plotly]"
+```
+
+Both backends take the same arguments — `title`, `figsize` (in inches for both), `xlim`, `ylim` and so on. Extra `**kwargs` go to the underlying matplotlib call, or to plotly's [`Figure.update_layout`](https://plotly.com/python/reference/layout/) respectively, so a matplotlib-only argument such as `cmap` is rejected by the plotly backend. `ax` is matplotlib-only; the plotly backend always returns a new figure.
+
+Both backends return the figure rather than showing it, so in a script you need `.show()` (or `fig.write_html(...)`).
+
 ## Plotting observations and model results
 
 [](`~modelskill.PointObservation`)s and [](`~modelskill.PointModelResult`)s can be plotted using their `plot` accessor:
@@ -17,6 +34,10 @@ mr = ms.PointModelResult('../data/SW/ts_storm_4.dfs0', item=0) # TODO coords
 o.plot.timeseries();
 ```
 
+```{python}
+o.plot.timeseries(backend="plotly")
+```
+
 ```{python}
 mr.plot.timeseries();
 ```
@@ -71,6 +92,12 @@ cmp.plot.timeseries();
 cmp.plot.scatter();
 ```
 
+The same plot with the interactive backend:
+
+```{python}
+cmp.plot.scatter(backend="plotly")
+```
+
 
 ## Vertical profiles
 

pyproject.toml

@@ -44,11 +44,12 @@ classifiers = [
 
 [project.optional-dependencies]
 networks = ["mikeio1d", "networkx"]
+plotly = ["plotly >= 4.5"]
 
 [dependency-groups]
 dev = ["pytest", "plotly >= 4.5", "ruff==0.6.2", "netCDF4", "dask"]
 
-docs = ["quartodoc==0.11.1", "nbformat", "nbconvert", "ipykernel", "griffe<2"]
+docs = ["quartodoc==0.11.1", "nbformat", "nbconvert", "ipykernel", "griffe<2", "plotly >= 4.5"]
 
 test = [
     "pytest",
@@ -58,6 +59,7 @@ test = [
     "mypy==1.19.1",
     "types-PyYAML",
     "geopandas",
+    "plotly >= 4.5",
 ]
 
 notebooks = ["nbformat", "nbconvert", "jupyter", "plotly", "shapely", "seaborn"]