xarray-plotly 0.0.13__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
 
@@ -13,7 +13,7 @@ from xarray_plotly.config import DEFAULT_SLOT_ORDERS, _options
 
 if TYPE_CHECKING:
     import pandas as pd
-    from xarray import DataArray
+    from xarray import DataArray, Dataset
 
 
 class _AUTO:
@@ -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.
@@ -251,7 +258,21 @@ def _get_qualitative_scale_names() -> frozenset[str]:
     )
 
 
-def resolve_colors(colors: Colors, px_kwargs: dict[str, Any]) -> dict[str, Any]:
+def _sample_colorscale(name: str, n: int) -> list[str]:
+    """Sample *n* evenly-spaced colors from a named Plotly colorscale."""
+    scale = px.colors.get_colorscale(name)
+    samplepoints = [i / max(n - 1, 1) for i in range(n)]
+    result: list[str] = px.colors.sample_colorscale(scale, samplepoints)
+    return result
+
+
+def resolve_colors(
+    colors: Colors,
+    px_kwargs: dict[str, Any],
+    *,
+    color_dim: Hashable | None = None,
+    darray: DataArray | Dataset | None = None,
+) -> dict[str, Any]:
     """Map unified `colors` parameter to appropriate Plotly px_kwargs.
 
     Direct color_* kwargs take precedence and trigger a warning if
@@ -260,6 +281,14 @@ def resolve_colors(colors: Colors, px_kwargs: dict[str, Any]) -> dict[str, Any]:
     Args:
         colors: Unified color specification (str, list, dict, or None).
         px_kwargs: Existing kwargs to pass to Plotly Express.
+        color_dim: Dimension name used for discrete color grouping.
+            When provided together with *darray*, a continuous colorscale
+            string is sampled into a discrete sequence whose length
+            matches the number of coordinates along this dimension.
+            Use for chart types that only accept discrete color
+            parameters (line, area, box, pie).
+        darray: Source DataArray or Dataset; used with *color_dim* to
+            determine the number of discrete colors to sample.
 
     Returns:
         Updated px_kwargs with color parameters injected.
@@ -284,6 +313,10 @@ def resolve_colors(colors: Colors, px_kwargs: dict[str, Any]) -> dict[str, Any]:
         # Check if it's a qualitative (discrete) palette name
         if colors in _get_qualitative_scale_names():
             px_kwargs["color_discrete_sequence"] = getattr(px.colors.qualitative, colors)
+        elif color_dim is not None and darray is not None:
+            # Sample from continuous scale into a discrete sequence
+            n = darray.sizes[color_dim]
+            px_kwargs["color_discrete_sequence"] = _sample_colorscale(colors, n)
         else:
             # Assume continuous scale
             px_kwargs["color_continuous_scale"] = colors

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"),
 }