explore: allow overlaying map layers or showing maps side-by-side (#183)

* add geopandas to the dev deps

* implement composable maps

* use the composable maps by default

* avoid modifying the existing map

* try to control styling

* get the grid layout to actually work

* also wrap bare maps in `MapsWithSliders` (needs a new name)

* make sure we have sliders before creating the hbox

* get the typing right

* support a grid of maps

* add `pyinstrument` to the deps

* allow synchronizing the maps

* refactor to make changing the list of maps shorter

* simplify merge using duck typing

* make `merge` private

* add a "add_layer" method as a imperative API version

* move the import of `BaseLayer` out of the typing imports

* bump lock file

* revert returning the sliders wrapper for a bare map

* tests for `MapWithSliders`

* typing

* link the maps in java script

* avoid the infinite loop of events

* synchronize widgets when using the `|` notation

* fix the slider merging

* changelog

* demonstrate the new capabilities in the tutorials

Author: keewis

docs/changelog.md

@@ -2,6 +2,8 @@
 
 ## 0.3.1 (_unreleased_)
 
+- support interactive facet plots and combining maps ({pull}`183`)
+
 ## 0.3.0 (2025-09-26)
 
 ### New features

docs/tutorials/h3.ipynb

@@ -183,8 +183,8 @@
     "\n",
     "We can quickly visualize the data using {py:meth}`xarray.DataArray.dggs.explore`, which is powered by [lonboard](https://github.com/developmentseed/lonboard).\n",
     "\n",
-    "```{warning}\n",
-    "This is currently restricted to 1D `DataArray` objects, so we need to select a single timestep.\n",
+    "```{note}\n",
+    "The slider requires a running kernel, so this won't work in static documentation.\n",
     "```"
    ]
   },
@@ -195,7 +195,27 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ds[\"air\"].isel(time=15).dggs.explore()"
+    "ds[\"air\"].dggs.explore()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16",
+   "metadata": {},
+   "source": [
+    "We can also combine multiple maps:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds[\"air\"].dggs.explore(alpha=0.8, cmap=\"viridis\") | ds[\"air\"].dggs.explore(\n",
+    "    alpha=0.8, cmap=\"coolwarm\", center=273.15\n",
+    ")"
    ]
   }
  ],
@@ -210,7 +230,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

docs/tutorials/healpix.ipynb

@@ -202,8 +202,8 @@
     "\n",
     "We can quickly visualize the data using {py:meth}`xarray.DataArray.dggs.explore`, which is powered by [lonboard](https://github.com/developmentseed/lonboard).\n",
     "\n",
-    "```{warning}\n",
-    "This is currently restricted to 1D `DataArray` objects, so we need to select a single timestep.\n",
+    "```{note}\n",
+    "The slider requires a running kernel, so this won't work in static documentation.\n",
     "```"
    ]
   },
@@ -214,7 +214,27 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ds[\"air\"].isel(time=15).dggs.explore()"
+    "ds[\"air\"].dggs.explore()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17",
+   "metadata": {},
+   "source": [
+    "We can also combine multiple maps:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "18",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds[\"air\"].dggs.explore(alpha=0.8, cmap=\"viridis\") | ds[\"air\"].dggs.explore(\n",
+    "    alpha=0.8, cmap=\"coolwarm\", center=273.15\n",
+    ")"
    ]
   }
  ],
@@ -229,7 +249,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

pixi.lock

@@ -215,6 +215,8 @@ jupyterlab = "*"
 jupyter-resource-usage = "*"
 jupyterlab_code_formatter = "*"
 python-build = ">=1.3.0,<2"
+geopandas = ">=1.1.1,<2"
+pyinstrument = ">=5.1.1,<6"
 
 [tool.pixi.environments]
 nightly = { features = ["tests", "nightly"], no-default-feature = true }

pyproject.toml

@@ -1,11 +1,13 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 from functools import partial
 from typing import Any
 
 import ipywidgets
 import numpy as np
 import xarray as xr
-from lonboard import Map
+from lonboard import BaseLayer, Map
 
 
 def on_slider_change(change, container):
@@ -39,7 +41,115 @@ def render(self):
         # add any additional control widgets here
         control_box = ipywidgets.HBox([self.dimension_sliders])
 
-        return ipywidgets.VBox([self.map, control_box])
+        return MapWithSliders(
+            [self.map, control_box], layout=ipywidgets.Layout(width="100%")
+        )
+
+
+def extract_maps(obj: MapGrid | MapWithSliders | Map):
+    if isinstance(obj, Map):
+        return obj
+
+    return getattr(obj, "maps", (obj.map,))
+
+
+class MapGrid(ipywidgets.GridBox):
+    def __init__(
+        self,
+        maps: MapWithSliders | Map = None,
+        n_columns: int = 2,
+        synchronize: bool = False,
+    ):
+        self.n_columns = n_columns
+        self.synchronize = synchronize
+
+        column_width = 100 // n_columns
+        layout = ipywidgets.Layout(
+            width="100%", grid_template_columns=f"repeat({n_columns}, {column_width}%)"
+        )
+
+        if maps is None:
+            maps = []
+
+        if synchronize and maps:
+            all_maps = [getattr(m, "map", m) for m in maps]
+
+            first = all_maps[0]
+            for second in all_maps[1:]:
+                ipywidgets.jslink((first, "view_state"), (second, "view_state"))
+
+        super().__init__(maps, layout=layout)
+
+    def _replace_maps(self, maps):
+        return type(self)(maps, n_columns=self.n_columns, synchronize=self.synchronize)
+
+    def add_map(self, map_: MapWithSliders | Map):
+        return self._replace_maps(self.maps + (map_,))
+
+    @property
+    def maps(self):
+        return self.children
+
+    def __or__(self, other: MapGrid | MapWithSliders | Map):
+        other_maps = extract_maps(other)
+
+        return self._replace_maps(self.maps + other_maps)
+
+    def __ror__(self, other: MapWithSliders | Map):
+        other_maps = extract_maps(other)
+
+        return self._replace_maps(self.maps + other_maps)
+
+
+class MapWithSliders(ipywidgets.VBox):
+    def change_layout(self, layout):
+        return type(self)(self.children, layout=layout)
+
+    @property
+    def sliders(self) -> list:
+        return list(self.children[1:]) if len(self.children) > 1 else []
+
+    @property
+    def map(self) -> Map:
+        return self.children[0]
+
+    @property
+    def layers(self) -> list[BaseLayer]:
+        return self.map.layers
+
+    def __or__(self, other: MapWithSliders | Map):
+        [other_map] = extract_maps(other)
+
+        return MapGrid([self, other], synchronize=True)
+
+    def _merge(self, layers, sliders):
+        all_layers = list(self.map.layers) + list(layers)
+        new_map = Map(all_layers)
+
+        slider_widgets = []
+        if self.sliders:
+            slider_widgets.extend(self.sliders)
+        if sliders:
+            slider_widgets.extend(sliders)
+
+        widgets = [new_map]
+        if slider_widgets:
+            widgets.append(ipywidgets.HBox(slider_widgets))
+
+        return type(self)(widgets, layout=self.layout)
+
+    def add_layer(self, layer: BaseLayer):
+        self.map.add_layer(layer)
+
+    def __and__(self, other: MapWithSliders | Map | BaseLayer):
+        if isinstance(other, BaseLayer):
+            layers = [other]
+            sliders = []
+        else:
+            layers = other.layers
+            sliders = getattr(other, "sliders", [])
+
+        return self._merge(layers, sliders)
 
 
 def create_arrow_table(polygons, arr, coords=None):

xdggs/plotting.py

@@ -239,3 +239,29 @@ def test_explore(arr, expected_type):
     actual = arr.dggs.explore()
 
     assert isinstance(actual, expected_type)
+
+
+class TestMapWithSliders:
+    @pytest.mark.parametrize(
+        ["sliders", "expected"],
+        (
+            pytest.param([ipywidgets.VBox()], [ipywidgets.VBox()], id="sliders"),
+            pytest.param([], [], id="empty"),
+        ),
+    )
+    def test_sliders(self, sliders, expected) -> None:
+        map_ = plotting.MapWithSliders([lonboard.Map(layers=[]), *sliders])
+
+        assert map_.sliders == expected or isinstance(map_.sliders[0], ipywidgets.VBox)
+
+    def test_map(self):
+        base_map = lonboard.Map(layers=[])
+        wrapped_map = plotting.MapWithSliders([base_map, ipywidgets.HBox()])
+
+        assert wrapped_map.map is base_map
+
+    def test_layers(self):
+        base_map = lonboard.Map(layers=[])
+        wrapped_map = plotting.MapWithSliders([base_map, ipywidgets.HBox()])
+
+        assert wrapped_map.layers == base_map.layers