docs: add subplots examples to combining notebook

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: FBumann

docs/examples/combining.ipynb

@@ -10,7 +10,9 @@
     "xarray-plotly provides helper functions to combine multiple figures:\n",
     "\n",
     "- **`overlay`**: Overlay traces on the same axes\n",
-    "- **`add_secondary_y`**: Plot with two independent y-axes"
+    "- **`add_secondary_y`**: Plot with two independent y-axes\n",
+    "- **`subplots`**: Arrange independent figures in a grid\n",
+    "- **`slider_to_dropdown`**: Convert animation slider to a dropdown menu"
    ]
   },
   {
@@ -23,7 +25,7 @@
     "import plotly.express as px\n",
     "import xarray as xr\n",
     "\n",
-    "from xarray_plotly import add_secondary_y, config, overlay, xpx\n",
+    "from xarray_plotly import add_secondary_y, config, overlay, subplots, xpx\n",
     "\n",
     "config.notebook()"
    ]
@@ -440,6 +442,134 @@
    "cell_type": "markdown",
    "id": "27",
    "metadata": {},
+   "source": [
+    "## subplots\n",
+    "\n",
+    "Arrange independent figures side-by-side in a grid. Each figure gets its own\n",
+    "subplot cell with axes and title automatically derived from the source figure."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28",
+   "metadata": {},
+   "source": [
+    "### Different Variables Side by Side"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "29",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# One figure per variable, arranged in a row\n",
+    "us_pop = population.sel(country=\"United States\")\n",
+    "us_gdp = gdp_per_capita.sel(country=\"United States\")\n",
+    "us_life = life_expectancy.sel(country=\"United States\")\n",
+    "\n",
+    "pop_fig = xpx(us_pop).bar(title=\"Population\")\n",
+    "gdp_fig = xpx(us_gdp).line(title=\"GDP per Capita\")\n",
+    "life_fig = xpx(us_life).line(title=\"Life Expectancy\")\n",
+    "\n",
+    "grid = subplots(pop_fig, gdp_fig, life_fig, cols=3)\n",
+    "grid.update_layout(title=\"United States Overview\", height=350, showlegend=False)\n",
+    "grid"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30",
+   "metadata": {},
+   "source": [
+    "### 2x2 Grid\n",
+    "\n",
+    "Use `cols=2` and pass four figures for a 2x2 layout."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "31",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# One subplot per country\n",
+    "fig_us = xpx(population.sel(country=\"United States\")).bar(title=\"United States\")\n",
+    "fig_cn = xpx(population.sel(country=\"China\")).bar(title=\"China\")\n",
+    "fig_de = xpx(population.sel(country=\"Germany\")).bar(title=\"Germany\")\n",
+    "fig_br = xpx(population.sel(country=\"Brazil\")).bar(title=\"Brazil\")\n",
+    "\n",
+    "grid = subplots(fig_us, fig_cn, fig_de, fig_br, cols=2)\n",
+    "grid.update_layout(height=500, showlegend=False)\n",
+    "grid"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "32",
+   "metadata": {},
+   "source": [
+    "### Mixed Chart Types\n",
+    "\n",
+    "Each cell can use a different chart type. Subplot titles fall back to the\n",
+    "y-axis label when no explicit title is set."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "33",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# No explicit title — subplot titles come from the y-axis label (DataArray name)\n",
+    "pop_bar = xpx(us_pop).bar()\n",
+    "gdp_line = xpx(us_gdp).line()\n",
+    "life_scatter = xpx(us_life).scatter()\n",
+    "\n",
+    "grid = subplots(pop_bar, gdp_line, life_scatter, cols=3)\n",
+    "grid.update_layout(height=350, showlegend=False)\n",
+    "grid"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "34",
+   "metadata": {},
+   "source": [
+    "### Limitations\n",
+    "\n",
+    "`subplots` requires single-panel figures — faceted and animated figures are not supported."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Faceted figure → rejected\n",
+    "faceted = xpx(population).line(facet_col=\"country\")\n",
+    "try:\n",
+    "    subplots(faceted)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")\n",
+    "\n",
+    "# Animated figure → rejected\n",
+    "animated = xpx(population).bar(animation_frame=\"country\")\n",
+    "try:\n",
+    "    subplots(animated)\n",
+    "except ValueError as e:\n",
+    "    print(f\"ValueError: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36",
+   "metadata": {},
    "source": [
     "---\n",
     "\n",
@@ -450,7 +580,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "28",
+   "id": "37",
    "metadata": {},
    "source": [
     "### overlay: Mismatched Facet Structure\n",
@@ -461,7 +591,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "29",
+   "id": "38",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -479,7 +609,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "30",
+   "id": "39",
    "metadata": {},
    "source": [
     "### overlay: Animated Overlay on Static Base\n",
@@ -490,7 +620,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "31",
+   "id": "40",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -508,7 +638,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "32",
+   "id": "41",
    "metadata": {},
    "source": [
     "### overlay: Mismatched Animation Frames\n",
@@ -519,7 +649,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "33",
+   "id": "42",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -535,7 +665,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "34",
+   "id": "43",
    "metadata": {},
    "source": [
     "### add_secondary_y: Mismatched Facet Structure\n",
@@ -546,7 +676,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "35",
+   "id": "44",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -564,7 +694,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "36",
+   "id": "45",
    "metadata": {},
    "source": [
     "### add_secondary_y: Animated Secondary on Static Base\n",
@@ -575,7 +705,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "37",
+   "id": "46",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -593,7 +723,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "38",
+   "id": "47",
    "metadata": {},
    "source": [
     "### add_secondary_y: Mismatched Animation Frames"
@@ -602,7 +732,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "39",
+   "id": "48",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -618,15 +748,16 @@
   },
   {
    "cell_type": "markdown",
-   "id": "40",
+   "id": "49",
    "metadata": {},
    "source": [
     "## Summary\n",
     "\n",
     "| Function | Facets | Animation | Static + Animated |\n",
     "|----------|--------|-----------|-------------------|\n",
     "| `overlay` | Yes (must match) | Yes (frames must match) | Static overlay on animated base OK |\n",
-    "| `add_secondary_y` | Yes (must match) | Yes (frames must match) | Static secondary on animated base OK |"
+    "| `add_secondary_y` | Yes (must match) | Yes (frames must match) | Static secondary on animated base OK |\n",
+    "| `subplots` | No (single-panel only) | No | N/A |"
    ]
   }
  ],