xarray-plotly 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

xarray_plotly/__init__.py

@@ -56,6 +56,8 @@ from xarray_plotly.common import SLOT_ORDERS, Colors, auto
 from xarray_plotly.figures import (
     add_secondary_y,
     overlay,
+    simplify_facet_titles,
+    subplots,
     update_traces,
 )
 
@@ -66,6 +68,8 @@ __all__ = [
     "auto",
     "config",
     "overlay",
+    "simplify_facet_titles",
+    "subplots",
     "update_traces",
     "xpx",
 ]

xarray_plotly/accessor.py

@@ -6,7 +6,7 @@ import plotly.graph_objects as go
 from xarray import DataArray, Dataset
 
 from xarray_plotly import plotting
-from xarray_plotly.common import Colors, SlotValue, auto
+from xarray_plotly.common import Colors, FacetTitlesMode, SlotValue, auto
 from xarray_plotly.config import _options
 
 
@@ -54,6 +54,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -84,6 +85,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -97,6 +99,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -125,6 +128,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -138,6 +142,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -166,6 +171,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -178,6 +184,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -204,6 +211,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -218,6 +226,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -252,6 +261,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -264,6 +274,7 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -293,6 +304,7 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -302,14 +314,16 @@ class DataArrayPlotlyAccessor:
         x: SlotValue = auto,
         y: SlotValue = auto,
         facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         robust: bool = False,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive heatmap image.
 
-        Slot order: y (rows) -> x (columns) -> facet_col -> animation_frame
+        Slot order: y (rows) -> x (columns) -> facet_col -> facet_row -> animation_frame
 
         Note:
             **Difference from px.imshow**: Color bounds are computed from the
@@ -320,7 +334,10 @@ class DataArrayPlotlyAccessor:
             x: Dimension for x-axis (columns). Default: second dimension.
             y: Dimension for y-axis (rows). Default: first dimension.
             facet_col: Dimension for subplot columns. Default: third dimension.
-            animation_frame: Dimension for animation. Default: fourth dimension.
+            facet_row: Dimension for subplot rows. Default: fourth dimension.
+                Requires plotly>=6.7.0; on older versions this slot is skipped
+                during auto-assignment.
+            animation_frame: Dimension for animation. Default: fifth dimension.
             robust: If True, use 2nd/98th percentiles for color bounds (handles outliers).
             colors: Color scale name (e.g., "Viridis", "RdBu"). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.imshow()`.
@@ -334,9 +351,11 @@ class DataArrayPlotlyAccessor:
             x=x,
             y=y,
             facet_col=facet_col,
+            facet_row=facet_row,
             animation_frame=animation_frame,
             robust=robust,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -348,6 +367,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -372,6 +392,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -452,6 +473,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -482,6 +504,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -496,6 +519,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -524,6 +548,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -538,6 +563,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -566,6 +592,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -579,6 +606,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -605,6 +633,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -620,6 +649,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -650,6 +680,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -663,6 +694,7 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -689,6 +721,7 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )
 
@@ -701,6 +734,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -725,5 +759,6 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             colors=colors,
+            facet_titles=facet_titles,
             **px_kwargs,
         )

xarray_plotly/common.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import functools
 import warnings
 from collections.abc import Hashable, Mapping, Sequence
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import plotly.express as px
 
@@ -39,6 +39,13 @@ Colors = str | Sequence[str] | Mapping[str, str] | None
 - None: Use Plotly defaults
 """
 
+FacetTitlesMode = Literal["value", "default"]
+"""Type alias for facet_titles parameter.
+
+- "default" (default): keep PX's ``"<dim>=<value>"`` subplot titles.
+- "value": strip the ``<dim>=`` prefix, leaving just the value.
+"""
+
 # Re-export for backward compatibility
 SLOT_ORDERS = DEFAULT_SLOT_ORDERS
 """Slot orders per plot type.

xarray_plotly/config.py

@@ -43,7 +43,7 @@ DEFAULT_SLOT_ORDERS: dict[str, tuple[str, ...]] = {
         "facet_row",
         "animation_frame",
     ),
-    "imshow": ("y", "x", "facet_col", "animation_frame"),
+    "imshow": ("y", "x", "facet_col", "facet_row", "animation_frame"),
     "box": ("x", "color", "facet_col", "facet_row", "animation_frame"),
     "pie": ("names", "facet_col", "facet_row"),
 }

xarray_plotly/figures.py

@@ -5,6 +5,7 @@ Helper functions for combining and manipulating Plotly figures.
 from __future__ import annotations
 
 import copy
+import re
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -12,6 +13,190 @@ if TYPE_CHECKING:
 
     import plotly.graph_objects as go
 
+    from xarray_plotly.common import FacetTitlesMode
+
+
+def _get_yaxis_title(fig: go.Figure) -> str:
+    """Extract the primary y-axis title text from a figure.
+
+    Args:
+        fig: A Plotly figure.
+
+    Returns:
+        The y-axis title text, or empty string if not set.
+    """
+    try:
+        return fig.layout.yaxis.title.text or ""
+    except AttributeError:
+        return ""
+
+
+def _ensure_legend_visibility(
+    combined: go.Figure,
+    source_figs: list[go.Figure],
+    trace_slices: list[slice],
+) -> None:
+    """Fix legend visibility on a combined figure.
+
+    Handles three problems that arise when combining Plotly Express figures:
+
+    1. **Unnamed traces** — PX sets ``name=""`` on single-trace (no color)
+       figures.  We derive a name from each source figure's y-axis title.
+    2. **Hidden named traces** — PX sets ``showlegend=False`` on single-trace
+       figures.  We ensure at least one trace per ``legendgroup`` (or each
+       ungrouped named trace) has ``showlegend=True``.
+    3. **Duplicate legend entries** — when two source figures share the same
+       ``legendgroup`` names, we deduplicate so only the first trace per
+       group shows in the legend.
+
+    Args:
+        combined: The combined Plotly figure (mutated in place).
+        source_figs: The original source figures, in trace order.
+        trace_slices: Slices into ``combined.data`` for each source figure.
+    """
+    from collections import defaultdict
+
+    # --- Step 1: label unnamed traces from source y-axis titles -----------
+    labels = [_get_yaxis_title(f) for f in source_figs]
+
+    # If all labels are non-empty and identical, disambiguate
+    unique_labels = {lb for lb in labels if lb}
+    if len(unique_labels) == 1 and all(lb for lb in labels):
+        labels = [f"{labels[0]} ({i + 1})" for i in range(len(labels))]
+
+    for label, sl in zip(labels, trace_slices, strict=False):
+        if not label:
+            continue
+        for trace in combined.data[sl]:
+            if not getattr(trace, "name", None):
+                trace.name = label
+                trace.legendgroup = label
+
+    # --- Step 2 & 3: fix showlegend per legendgroup -----------------------
+    grouped: dict[str, list[Any]] = defaultdict(list)
+    ungrouped: list[Any] = []
+
+    for trace in combined.data:
+        lg = getattr(trace, "legendgroup", None) or ""
+        if lg:
+            grouped[lg].append(trace)
+        else:
+            ungrouped.append(trace)
+
+    for traces in grouped.values():
+        has_visible = False
+        for t in traces:
+            if has_visible:
+                # Deduplicate: only first keeps showlegend
+                t.showlegend = False
+            elif getattr(t, "name", None):
+                t.showlegend = True
+                has_visible = True
+
+    # Ungrouped traces with a name should show in the legend
+    for trace in ungrouped:
+        if getattr(trace, "name", None):
+            trace.showlegend = True
+
+    # --- Step 4: propagate style properties to animation frame traces ------
+    # When Plotly animates, frame trace data overwrites fig.data properties.
+    # PX frame traces carry name="", showlegend=False and default colors,
+    # discarding any styling the user applied via update_traces() before
+    # combining.  Propagate display properties from fig.data into every frame.
+    _STYLE_ATTRS = ("name", "legendgroup", "showlegend", "marker", "line", "opacity")
+    for frame in combined.frames or []:
+        for i, frame_trace in enumerate(frame.data):
+            if i < len(combined.data):
+                src = combined.data[i]
+                for attr in _STYLE_ATTRS:
+                    src_val = getattr(src, attr, None)
+                    if src_val is not None:
+                        setattr(frame_trace, attr, src_val)
+
+
+def _fix_animation_axis_ranges(fig: go.Figure) -> None:
+    """Set axis ranges to encompass data across all animation frames.
+
+    Plotly.js computes autorange from ``fig.data`` only and does not
+    recalculate during animation.  When different frames have very different
+    data ranges (e.g. population of Brazil vs China), values can go off-screen.
+    This function computes the global min/max for each axis across all frames
+    and sets explicit ranges on the layout.
+
+    Only numeric axes are handled; categorical/date axes are left to autorange.
+
+    Args:
+        fig: A Plotly figure with animation frames (mutated in place).
+    """
+    import numpy as np
+
+    if not fig.frames:
+        return
+
+    from collections import defaultdict
+
+    # Collect numeric y-values per axis across all traces (fig.data + frames)
+    y_by_axis: dict[str, list[float]] = defaultdict(list)
+    x_by_axis: dict[str, list[float]] = defaultdict(list)
+
+    # Track which axes have bar traces (for zero-baseline clamping)
+    y_has_vbar: set[str] = set()  # vertical bars → y-axis includes 0
+    x_has_hbar: set[str] = set()  # horizontal bars → x-axis includes 0
+
+    for trace in _iter_all_traces(fig):
+        yaxis = getattr(trace, "yaxis", None) or "y"
+        xaxis = getattr(trace, "xaxis", None) or "x"
+
+        # Track bar orientations
+        if getattr(trace, "type", None) == "bar":
+            orientation = getattr(trace, "orientation", None) or "v"
+            if orientation == "h":
+                x_has_hbar.add(xaxis)
+            else:
+                y_has_vbar.add(yaxis)
+
+        for data_attr, axis_ref, by_axis in [
+            ("y", yaxis, y_by_axis),
+            ("x", xaxis, x_by_axis),
+        ]:
+            vals = getattr(trace, data_attr, None)
+            if vals is None:
+                continue
+            arr = np.asarray(vals)
+            # Skip datetime/timedelta — leave those axes on autorange
+            if np.issubdtype(arr.dtype, np.datetime64) or np.issubdtype(arr.dtype, np.timedelta64):
+                continue
+            try:
+                arr = arr.astype(float)
+                finite = arr[np.isfinite(arr)]
+                if len(finite):
+                    by_axis[axis_ref].extend(finite.tolist())
+            except (ValueError, TypeError):
+                pass  # Non-numeric (categorical) — skip
+
+    # Apply ranges to layout
+    for axis_ref, values in y_by_axis.items():
+        if not values:
+            continue
+        lo, hi = min(values), max(values)
+        if axis_ref in y_has_vbar:
+            lo = min(lo, 0.0)
+            hi = max(hi, 0.0)
+        pad = (hi - lo) * 0.05 or 1  # 5% padding
+        layout_prop = "yaxis" if axis_ref == "y" else f"yaxis{axis_ref[1:]}"
+        fig.layout[layout_prop].range = [lo - pad, hi + pad]
+
+    for axis_ref, values in x_by_axis.items():
+        if not values:
+            continue
+        lo, hi = min(values), max(values)
+        if axis_ref in x_has_hbar:
+            lo = min(lo, 0.0)
+            hi = max(hi, 0.0)
+        pad = (hi - lo) * 0.05 or 1
+        layout_prop = "xaxis" if axis_ref == "x" else f"xaxis{axis_ref[1:]}"
+        fig.layout[layout_prop].range = [lo - pad, hi + pad]
+
 
 def _iter_all_traces(fig: go.Figure) -> Iterator[Any]:
     """Iterate over all traces in a figure, including animation frames.
@@ -194,17 +379,11 @@ def overlay(base: go.Figure, *overlays: go.Figure) -> go.Figure:
         _validate_compatible_structure(base, overlay)
         _validate_animation_compatibility(base, overlay)
 
-    # Create new figure with base's layout
-    combined = go.Figure(layout=copy.deepcopy(base.layout))
-
-    # Add all traces from base
-    for trace in base.data:
-        combined.add_trace(copy.deepcopy(trace))
-
-    # Add all traces from overlays
+    # Create new figure with base's layout and all traces
+    all_traces = [copy.deepcopy(t) for t in base.data]
     for overlay in overlays:
-        for trace in overlay.data:
-            combined.add_trace(copy.deepcopy(trace))
+        all_traces.extend(copy.deepcopy(t) for t in overlay.data)
+    combined = go.Figure(data=all_traces, layout=copy.deepcopy(base.layout))
 
     # Handle animation frames
     if base.frames:
@@ -213,6 +392,17 @@ def overlay(base: go.Figure, *overlays: go.Figure) -> go.Figure:
         merged_frames = _merge_frames(base, list(overlays), base_trace_count, overlay_trace_counts)
         combined.frames = merged_frames
 
+    # Build trace slices for legend fix
+    source_figs = [base, *overlays]
+    slices: list[slice] = []
+    offset = 0
+    for fig in source_figs:
+        n = len(fig.data)
+        slices.append(slice(offset, offset + n))
+        offset += n
+
+    _ensure_legend_visibility(combined, source_figs, slices)
+    _fix_animation_axis_ranges(combined)
     return combined
 
 
@@ -315,19 +505,15 @@ def add_secondary_y(
     rightmost_x = max(x_for_y.values(), key=lambda x: int(x[1:]) if x != "x" else 1)
     rightmost_primary_y = next(y for y, x in x_for_y.items() if x == rightmost_x)
 
-    # Create new figure with base's layout
-    combined = go.Figure(layout=copy.deepcopy(base.layout))
-
-    # Add all traces from base (primary y-axis)
-    for trace in base.data:
-        combined.add_trace(copy.deepcopy(trace))
-
-    # Add all traces from secondary, remapped to secondary y-axes
+    # Build all traces: base (primary) + secondary (remapped to secondary y-axes)
+    all_traces = [copy.deepcopy(t) for t in base.data]
     for trace in secondary.data:
         trace_copy = copy.deepcopy(trace)
         original_yaxis = getattr(trace_copy, "yaxis", None) or "y"
         trace_copy.yaxis = y_mapping[original_yaxis]
-        combined.add_trace(trace_copy)
+        all_traces.append(trace_copy)
+
+    combined = go.Figure(data=all_traces, layout=copy.deepcopy(base.layout))
 
     # Get the rightmost secondary y-axis name for linking
     rightmost_secondary_y = y_mapping[rightmost_primary_y]
@@ -368,6 +554,14 @@ def add_secondary_y(
         merged_frames = _merge_secondary_y_frames(base, secondary, y_mapping)
         combined.frames = merged_frames
 
+    base_n = len(base.data)
+    sec_n = len(secondary.data)
+    _ensure_legend_visibility(
+        combined,
+        [base, secondary],
+        [slice(0, base_n), slice(base_n, base_n + sec_n)],
+    )
+    _fix_animation_axis_ranges(combined)
     return combined
 
 
@@ -426,6 +620,272 @@ def _merge_secondary_y_frames(
     return merged_frames
 
 
+def _get_figure_title(fig: go.Figure) -> str:
+    """Extract a display title from a figure for use as a subplot title.
+
+    Checks, in order: the figure's title, then the y-axis title.
+
+    Args:
+        fig: A Plotly figure.
+
+    Returns:
+        A title string, or empty string if nothing is set.
+    """
+    try:
+        title = fig.layout.title.text
+        if isinstance(title, str) and title:
+            return title
+    except AttributeError:
+        pass
+    return _get_yaxis_title(fig)
+
+
+def subplots(*figs: go.Figure, cols: int = 1) -> go.Figure:
+    """Arrange multiple figures into a subplot grid.
+
+    Creates a new figure with each input figure placed in its own cell.
+    Figures may contain internal subplots (facets) — their axes are remapped
+    to fit within the grid cell.  Subplot titles are derived from each
+    figure's title or y-axis label.
+
+    Args:
+        *figs: One or more Plotly figures to arrange.
+        cols: Number of columns in the grid. Rows are computed automatically.
+
+    Returns:
+        A new figure with subplot grid.
+
+    Raises:
+        ValueError: If no figures are provided, cols < 1, or a figure has
+            animation frames.
+
+    Example:
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xarray_plotly import xpx, subplots
+        >>>
+        >>> temp = xr.DataArray([20, 22, 25], dims=["time"], name="Temperature")
+        >>> rain = xr.DataArray([0, 5, 12], dims=["time"], name="Rainfall")
+        >>> fig1 = xpx(temp).line()
+        >>> fig2 = xpx(rain).bar()
+        >>> grid = subplots(fig1, fig2, cols=2)
+    """
+    import math
+
+    import plotly.graph_objects as go
+
+    if not figs:
+        raise ValueError("At least one figure is required.")
+    if cols < 1:
+        raise ValueError(f"cols must be >= 1, got {cols}.")
+
+    for i, fig in enumerate(figs):
+        if fig.frames:
+            raise ValueError(
+                f"Figure at position {i} has animation frames. "
+                "Animated figures are not supported in subplots()."
+            )
+
+    rows = math.ceil(len(figs) / cols)
+    combined = go.Figure()
+
+    # Grid spacing
+    h_gap = 0.05
+    v_gap = 0.08
+    cell_w = (1.0 - h_gap * (cols - 1)) / cols
+    cell_h = (1.0 - v_gap * (rows - 1)) / rows
+
+    next_x_num = 1
+    next_y_num = 1
+
+    for i, fig in enumerate(figs):
+        row = i // cols  # 0-indexed, top to bottom
+        col = i % cols
+
+        # Cell boundaries (clamped to [0, 1])
+        cell_x0 = max(0.0, col * (cell_w + h_gap))
+        cell_x1 = min(1.0, cell_x0 + cell_w)
+        cell_y1 = min(1.0, 1.0 - row * (cell_h + v_gap))  # top-down
+        cell_y0 = max(0.0, cell_y1 - cell_h)
+
+        # Build axis remapping: old axis ref → new axis ref
+        axis_map, next_x_num, next_y_num = _remap_figure_axes(
+            fig, combined, next_x_num, next_y_num, cell_x0, cell_x1, cell_y0, cell_y1
+        )
+
+        # Add traces with remapped axis refs
+        for trace in fig.data:
+            tc = copy.deepcopy(trace)
+            old_x = getattr(tc, "xaxis", None) or "x"
+            old_y = getattr(tc, "yaxis", None) or "y"
+            tc.xaxis = axis_map[old_x]["new_x"]
+            tc.yaxis = axis_map[old_y]["new_y"]
+            combined.add_trace(tc)
+
+        # Add subplot title as annotation
+        title = _get_figure_title(fig)
+        if title:
+            combined.add_annotation(
+                text=f"<b>{title}</b>",
+                x=(cell_x0 + cell_x1) / 2,
+                y=cell_y1,
+                xref="paper",
+                yref="paper",
+                xanchor="center",
+                yanchor="bottom",
+                showarrow=False,
+                font={"size": 14},
+            )
+
+    return combined
+
+
+# Axis properties safe to copy between figures (display-only, not structural).
+_AXIS_PROPS_TO_COPY = (
+    "title",
+    "type",
+    "tickformat",
+    "ticksuffix",
+    "tickprefix",
+    "dtick",
+    "tick0",
+    "nticks",
+    "showgrid",
+    "gridcolor",
+    "gridwidth",
+    "autorange",
+    "range",
+    "zeroline",
+    "zerolinecolor",
+    "zerolinewidth",
+    "showticklabels",
+)
+
+
+def _axis_layout_key(ref: str) -> str:
+    """Convert axis reference to layout property name.
+
+    ``"x"`` → ``"xaxis"``, ``"x2"`` → ``"xaxis2"``,
+    ``"y"`` → ``"yaxis"``, ``"y3"`` → ``"yaxis3"``.
+    """
+    if ref in ("x", "y"):
+        return f"{ref}axis"
+    prefix = ref[0]  # "x" or "y"
+    num = ref[1:]
+    return f"{prefix}axis{num}"
+
+
+def _new_axis_ref(prefix: str, num: int) -> str:
+    """Build an axis reference string. ``_new_axis_ref("x", 1)`` → ``"x"``, ``("x", 3)`` → ``"x3"``."""
+    return prefix if num == 1 else f"{prefix}{num}"
+
+
+def _remap_figure_axes(
+    fig: go.Figure,
+    combined: go.Figure,
+    next_x_num: int,
+    next_y_num: int,
+    cell_x0: float,
+    cell_x1: float,
+    cell_y0: float,
+    cell_y1: float,
+) -> tuple[dict[str, dict[str, str]], int, int]:
+    """Remap a figure's axes into a grid cell, adding axis configs to the combined layout.
+
+    Args:
+        fig: Source figure.
+        combined: Target combined figure (mutated — axis configs added to layout).
+        next_x_num: Next available x-axis number.
+        next_y_num: Next available y-axis number.
+        cell_x0, cell_x1: Horizontal cell bounds in paper coordinates.
+        cell_y0, cell_y1: Vertical cell bounds in paper coordinates.
+
+    Returns:
+        Tuple of (axis_map, next_x_num, next_y_num).
+        axis_map maps old axis refs to ``{"new_x": ...}`` or ``{"new_y": ...}``.
+    """
+    cell_w = cell_x1 - cell_x0
+    cell_h = cell_y1 - cell_y0
+    src_layout = fig.layout.to_plotly_json()
+
+    x_remap: dict[str, str] = {}
+    y_remap: dict[str, str] = {}
+
+    # Get all unique axis refs
+    x_refs: set[str] = set()
+    y_refs: set[str] = set()
+    for trace in fig.data:
+        x_refs.add(getattr(trace, "xaxis", None) or "x")
+        y_refs.add(getattr(trace, "yaxis", None) or "y")
+
+    # Remap x-axes
+    for old_xref in sorted(x_refs, key=lambda r: int(r[1:]) if len(r) > 1 else 1):
+        new_xref = _new_axis_ref("x", next_x_num)
+        x_remap[old_xref] = new_xref
+
+        src_config = src_layout.get(_axis_layout_key(old_xref), {})
+        src_domain = src_config.get("domain", [0.0, 1.0])
+        new_domain = [
+            max(0.0, cell_x0 + src_domain[0] * cell_w),
+            min(1.0, cell_x0 + src_domain[1] * cell_w),
+        ]
+
+        new_config: dict[str, Any] = {"domain": new_domain}
+        for prop in _AXIS_PROPS_TO_COPY:
+            if prop in src_config:
+                new_config[prop] = src_config[prop]
+
+        combined.layout[_axis_layout_key(new_xref)] = new_config
+        next_x_num += 1
+
+    # Remap y-axes
+    for old_yref in sorted(y_refs, key=lambda r: int(r[1:]) if len(r) > 1 else 1):
+        new_yref = _new_axis_ref("y", next_y_num)
+        y_remap[old_yref] = new_yref
+
+        src_config = src_layout.get(_axis_layout_key(old_yref), {})
+        src_domain = src_config.get("domain", [0.0, 1.0])
+        new_domain = [
+            max(0.0, cell_y0 + src_domain[0] * cell_h),
+            min(1.0, cell_y0 + src_domain[1] * cell_h),
+        ]
+
+        new_config = {"domain": new_domain}
+        for prop in _AXIS_PROPS_TO_COPY:
+            if prop in src_config:
+                new_config[prop] = src_config[prop]
+
+        combined.layout[_axis_layout_key(new_yref)] = new_config
+        next_y_num += 1
+
+    # Set anchors between paired axes
+    for trace in fig.data:
+        old_x = getattr(trace, "xaxis", None) or "x"
+        old_y = getattr(trace, "yaxis", None) or "y"
+        combined.layout[_axis_layout_key(x_remap[old_x])]["anchor"] = y_remap[old_y]
+        combined.layout[_axis_layout_key(y_remap[old_y])]["anchor"] = x_remap[old_x]
+
+    # Propagate matches relationships
+    for old_ref, new_ref in x_remap.items():
+        src_config = src_layout.get(_axis_layout_key(old_ref), {})
+        if "matches" in src_config and src_config["matches"] in x_remap:
+            combined.layout[_axis_layout_key(new_ref)]["matches"] = x_remap[src_config["matches"]]
+
+    for old_ref, new_ref in y_remap.items():
+        src_config = src_layout.get(_axis_layout_key(old_ref), {})
+        if "matches" in src_config and src_config["matches"] in y_remap:
+            combined.layout[_axis_layout_key(new_ref)]["matches"] = y_remap[src_config["matches"]]
+
+    # Build combined return mapping
+    result: dict[str, dict[str, str]] = {}
+    for old_x, new_x in x_remap.items():
+        result[old_x] = {"new_x": new_x}
+    for old_y, new_y in y_remap.items():
+        result[old_y] = {"new_y": new_y}
+
+    return result, next_x_num, next_y_num
+
+
 def update_traces(
     fig: go.Figure, selector: dict[str, Any] | None = None, **kwargs: Any
 ) -> go.Figure:
@@ -465,3 +925,49 @@ def update_traces(
                 trace.update(**kwargs)
 
     return fig
+
+
+# Matches an identifier-style PX facet prefix like "country=" at the start of
+# annotation text.  Defensive: ignores annotations a user added themselves
+# whose text doesn't look like a dim assignment.
+_FACET_TITLE_PREFIX_RE = re.compile(r"^[A-Za-z_]\w*=")
+
+
+def simplify_facet_titles(
+    fig: go.Figure,
+    mode: FacetTitlesMode = "value",
+) -> go.Figure:
+    """Strip the ``<dim>=`` prefix from Plotly Express facet subplot titles.
+
+    PX renders faceted subplot titles as annotations like ``"country=Brazil"``.
+    With ``mode="value"`` (default), the prefix is stripped to just the value
+    (``"Brazil"``).  With ``mode="default"``, the figure is returned unchanged.
+
+    Only annotations whose text matches a Python-identifier prefix followed by
+    ``=`` are touched, so user-added annotations are left alone.
+
+    Args:
+        fig: A Plotly figure (mutated in place).
+        mode: ``"value"`` to strip the prefix, ``"default"`` to keep PX's format.
+
+    Returns:
+        The (possibly mutated) figure, for chaining.
+
+    Raises:
+        ValueError: If ``mode`` is not ``"value"`` or ``"default"``.
+
+    Example:
+        >>> from xarray_plotly import xpx, simplify_facet_titles
+        >>> fig = xpx(da).line(facet_col="country")
+        >>> simplify_facet_titles(fig)  # "country=Brazil" -> "Brazil"
+    """
+    if mode == "default":
+        return fig
+    if mode != "value":
+        raise ValueError(f"facet_titles must be 'value' or 'full', got {mode!r}")
+
+    for ann in fig.layout.annotations or ():
+        text = ann.text
+        if text and _FACET_TITLE_PREFIX_RE.match(text):
+            ann.text = text.split("=", 1)[1]
+    return fig

xarray_plotly/plotting.py

@@ -4,6 +4,7 @@ Plotly Express plotting functions for DataArray objects.
 
 from __future__ import annotations
 
+import inspect
 import warnings
 from typing import TYPE_CHECKING, Any
 
@@ -13,6 +14,7 @@ import plotly.express as px
 
 from xarray_plotly.common import (
     Colors,
+    FacetTitlesMode,
     SlotValue,
     assign_slots,
     auto,
@@ -24,6 +26,7 @@ from xarray_plotly.common import (
 )
 from xarray_plotly.figures import (
     _iter_all_traces,
+    simplify_facet_titles,
 )
 
 if TYPE_CHECKING:
@@ -42,6 +45,7 @@ def line(
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -99,7 +103,7 @@ def line(
     value_col = get_value_col(darray)
     labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
 
-    return px.line(
+    fig = px.line(
         df,
         x=slots.get("x"),
         y=value_col,
@@ -112,6 +116,7 @@ def line(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def bar(
@@ -124,6 +129,7 @@ def bar(
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -178,7 +184,7 @@ def bar(
     value_col = get_value_col(darray)
     labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
 
-    return px.bar(
+    fig = px.bar(
         df,
         x=slots.get("x"),
         y=value_col,
@@ -190,6 +196,7 @@ def bar(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def _classify_trace_sign(y_values: npt.ArrayLike) -> str:
@@ -285,6 +292,7 @@ def fast_bar(
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -359,7 +367,7 @@ def fast_bar(
 
     _style_traces_as_bars(fig)
 
-    return fig
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def area(
@@ -372,6 +380,7 @@ def area(
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -426,7 +435,7 @@ def area(
     value_col = get_value_col(darray)
     labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
 
-    return px.area(
+    fig = px.area(
         df,
         x=slots.get("x"),
         y=value_col,
@@ -438,6 +447,7 @@ def area(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def box(
@@ -449,6 +459,7 @@ def box(
     facet_row: SlotValue = None,
     animation_frame: SlotValue = None,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -503,7 +514,7 @@ def box(
     value_col = get_value_col(darray)
     labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
 
-    return px.box(
+    fig = px.box(
         df,
         x=slots.get("x"),
         y=value_col,
@@ -514,6 +525,7 @@ def box(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def scatter(
@@ -527,6 +539,7 @@ def scatter(
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -600,7 +613,7 @@ def scatter(
     if y_is_dim and str(y) not in labels:
         labels[str(y)] = get_label(darray, y)
 
-    return px.scatter(
+    fig = px.scatter(
         df,
         x=slots.get("x"),
         y=y_col,
@@ -612,6 +625,15 @@ def scatter(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
+
+
+def _imshow_supports_facet_row() -> bool:
+    """Check whether the installed plotly version supports facet_row in px.imshow.
+
+    Support was added in plotly 6.7.0.
+    """
+    return "facet_row" in inspect.signature(px.imshow).parameters
 
 
 def imshow(
@@ -620,16 +642,18 @@ def imshow(
     x: SlotValue = auto,
     y: SlotValue = auto,
     facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
     robust: bool = False,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
     Create an interactive heatmap from a DataArray.
 
     Both x and y are dimensions. Dimensions fill slots in order:
-    y (rows) -> x (columns) -> facet_col -> animation_frame
+    y (rows) -> x (columns) -> facet_col -> facet_row -> animation_frame
 
     .. note::
         **Difference from plotly.express.imshow**: By default, color bounds
@@ -649,8 +673,14 @@ def imshow(
         Dimension for y-axis (rows). Default: first dimension.
     facet_col
         Dimension for subplot columns. Default: third dimension.
+    facet_row
+        Dimension for subplot rows. Default: fourth dimension.
+        Requires plotly>=6.7.0; on older versions this slot is skipped
+        during auto-assignment (the fourth dimension animates instead).
+        Note: ``facet_col_wrap`` is ignored by plotly when ``facet_row``
+        is set.
     animation_frame
-        Dimension for animation. Default: fourth dimension.
+        Dimension for animation. Default: fifth dimension.
     robust
         If True, compute color bounds using 2nd and 98th percentiles
         for robustness against outliers. Default: False (uses min/max).
@@ -668,18 +698,36 @@ def imshow(
     plotly.graph_objects.Figure
     """
     px_kwargs = resolve_colors(colors, px_kwargs)
+
+    # On plotly < 6.7.0, px.imshow has no facet_row: skip auto-assignment so
+    # dimensions fall through to animation_frame instead.
+    if facet_row is auto and not _imshow_supports_facet_row():
+        facet_row = None
+
     slots = assign_slots(
         list(darray.dims),
         "imshow",
         y=y,
         x=x,
         facet_col=facet_col,
+        facet_row=facet_row,
         animation_frame=animation_frame,
     )
 
-    # Transpose to: y (rows), x (cols), facet_col, animation_frame
+    facet_row_kwargs: dict[str, Any] = {}
+    if slots.get("facet_row") is not None:
+        if not _imshow_supports_facet_row():
+            import plotly
+
+            msg = f"facet_row for imshow requires plotly>=6.7.0 (installed: {plotly.__version__})."
+            raise ValueError(msg)
+        facet_row_kwargs["facet_row"] = slots["facet_row"]
+
+    # Transpose to: y (rows), x (cols), facet_col, facet_row, animation_frame
     transpose_order = [
-        slots[k] for k in ("y", "x", "facet_col", "animation_frame") if slots.get(k) is not None
+        slots[k]
+        for k in ("y", "x", "facet_col", "facet_row", "animation_frame")
+        if slots.get(k) is not None
     ]
     plot_data = darray.transpose(*transpose_order) if transpose_order else darray
 
@@ -697,12 +745,14 @@ def imshow(
         px_kwargs.setdefault("zmin", zmin)
         px_kwargs.setdefault("zmax", zmax)
 
-    return px.imshow(
+    fig = px.imshow(
         plot_data,
         facet_col=slots.get("facet_col"),
         animation_frame=slots.get("animation_frame"),
+        **facet_row_kwargs,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)
 
 
 def pie(
@@ -713,6 +763,7 @@ def pie(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     colors: Colors = None,
+    facet_titles: FacetTitlesMode = "default",
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -762,7 +813,7 @@ def pie(
     # Use names dimension for color if not explicitly set
     color_col = color if color is not None else slots.get("names")
 
-    return px.pie(
+    fig = px.pie(
         df,
         names=slots.get("names"),
         values=value_col,
@@ -772,3 +823,4 @@ def pie(
         labels=labels,
         **px_kwargs,
     )
+    return simplify_facet_titles(fig, facet_titles)

{xarray_plotly-0.0.14.dist-info → xarray_plotly-0.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.14
+Version: 0.0.16
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT
@@ -24,20 +24,6 @@ License-File: LICENSE
 Requires-Dist: xarray>=2023.1.0
 Requires-Dist: plotly>=5.0.0
 Requires-Dist: pandas>=1.5.0
-Provides-Extra: dev
-Requires-Dist: pytest==9.0.2; extra == "dev"
-Requires-Dist: pytest-cov==7.0.0; extra == "dev"
-Requires-Dist: mypy==1.19.1; extra == "dev"
-Requires-Dist: ruff==0.15.5; extra == "dev"
-Requires-Dist: pre-commit==4.5.1; extra == "dev"
-Requires-Dist: nbstripout==0.9.1; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: mkdocs==1.6.1; extra == "docs"
-Requires-Dist: mkdocs-material==9.7.4; extra == "docs"
-Requires-Dist: mkdocstrings[python]==1.0.3; extra == "docs"
-Requires-Dist: mkdocs-jupyter==0.25.1; extra == "docs"
-Requires-Dist: mkdocs-plotly-plugin==0.1.3; extra == "docs"
-Requires-Dist: jupyter==1.1.1; extra == "docs"
 Dynamic: license-file
 
 # xarray_plotly

xarray_plotly-0.0.16.dist-info/RECORD

@@ -0,0 +1,12 @@
+xarray_plotly/__init__.py,sha256=LaS1s4OL2g_oMq7Q_flyv7i1qPls7uVd8GJYyrf-XmA,3558
+xarray_plotly/accessor.py,sha256=8xR9Ait3A0SD-gGHQbJAuaWzSQG2pwSkZ0wSRKPV8YI,26959
+xarray_plotly/common.py,sha256=nyOcolEsEyMLv17i8-SXnLDZdDzsb5S9oHMg4c5vImY,11018
+xarray_plotly/config.py,sha256=MtyLQn5qP2D7bLPgFP8lJzsRcUKPnX9Del4antRkvac,6692
+xarray_plotly/figures.py,sha256=geJA0a0OE5x1B-GT0PMUI9fp7_42u3wlmaPHA_JkNUg,34211
+xarray_plotly/plotting.py,sha256=cjzB48_7lV1gRv_g9EmuMVJ-cIdVioZA94TqQqylyoY,26432
+xarray_plotly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xarray_plotly-0.0.16.dist-info/licenses/LICENSE,sha256=AvVEfNqbhIm9jHvt0acJNjW1JUKa2a70Zb5rJdEXCJI,1064
+xarray_plotly-0.0.16.dist-info/METADATA,sha256=Wj4J_FuU5f0GzBeT8BAId35yNsAQZEmXnITqU20KnNw,3519
+xarray_plotly-0.0.16.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+xarray_plotly-0.0.16.dist-info/top_level.txt,sha256=GtMkvuZvLAYTjYXtwoNUa0ag42CJARZJK1CZemYD7pg,14
+xarray_plotly-0.0.16.dist-info/RECORD,,

xarray_plotly-0.0.14.dist-info/RECORD

@@ -1,12 +0,0 @@
-xarray_plotly/__init__.py,sha256=8YaSdbzAakzlRqkq9HkQlMxWOLGg2JfUN-gAkyCGf5U,3472
-xarray_plotly/accessor.py,sha256=XsGREdfGGqzFzpM53AzTbMnCOEtZTv0Sau-dc15meHQ,25313
-xarray_plotly/common.py,sha256=YdxqrK5LPTxDAALeMswxtTyEJuoHYUSess_28axJo2s,10782
-xarray_plotly/config.py,sha256=fOL7cqPHVj_XNLqN1oT2KQZ0DitIjzeYnWyMKcJy0cc,6679
-xarray_plotly/figures.py,sha256=uKC_8kcoFJYXsqMu-QRAsKfY8O_E3r8McBfRiHZxciE,16457
-xarray_plotly/plotting.py,sha256=OTz9ScASHnRQAJ9NvQAABiYALIoTrmYSLMEIZa4Zd44,24331
-xarray_plotly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xarray_plotly-0.0.14.dist-info/licenses/LICENSE,sha256=AvVEfNqbhIm9jHvt0acJNjW1JUKa2a70Zb5rJdEXCJI,1064
-xarray_plotly-0.0.14.dist-info/METADATA,sha256=fKfz7Y0vuHRkhHfNGtObSxC9EWWKZr3eCYaCfzDyK_Y,4163
-xarray_plotly-0.0.14.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-xarray_plotly-0.0.14.dist-info/top_level.txt,sha256=GtMkvuZvLAYTjYXtwoNUa0ag42CJARZJK1CZemYD7pg,14
-xarray_plotly-0.0.14.dist-info/RECORD,,