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

xarray_plotly/__init__.py

@@ -56,6 +56,9 @@ from xarray_plotly.common import SLOT_ORDERS, Colors, auto
 from xarray_plotly.figures import (
     add_secondary_y,
     overlay,
+    share_axis_labels,
+    simplify_facet_titles,
+    subplots,
     update_traces,
 )
 
@@ -66,6 +69,9 @@ __all__ = [
     "auto",
     "config",
     "overlay",
+    "share_axis_labels",
+    "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,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -69,6 +71,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: sixth dimension.
             animation_frame: Dimension for animation. Default: seventh dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.line()`.
 
         Returns:
@@ -84,6 +88,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -97,6 +103,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -111,6 +119,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: fifth dimension.
             animation_frame: Dimension for animation. Default: sixth dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.bar()`.
 
         Returns:
@@ -125,6 +135,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -138,6 +150,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -152,6 +166,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: fifth dimension.
             animation_frame: Dimension for animation. Default: sixth dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -166,6 +182,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -178,6 +196,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -191,6 +211,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: fourth dimension.
             animation_frame: Dimension for animation. Default: fifth dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -204,6 +226,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -218,6 +242,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -237,6 +263,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: fifth dimension.
             animation_frame: Dimension for animation. Default: sixth dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.scatter()`.
 
         Returns:
@@ -252,6 +280,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -264,6 +294,8 @@ class DataArrayPlotlyAccessor:
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -280,6 +312,8 @@ class DataArrayPlotlyAccessor:
             facet_row: Dimension for subplot rows. Default: None (aggregated).
             animation_frame: Dimension for animation. Default: None (aggregated).
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.box()`.
 
         Returns:
@@ -293,6 +327,8 @@ class DataArrayPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -302,14 +338,17 @@ 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",
+        shared_axis_labels: bool = True,
         **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,9 +359,14 @@ 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.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.imshow()`.
                 Use `zmin` and `zmax` to manually set color scale bounds.
 
@@ -334,9 +378,12 @@ 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,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -348,6 +395,8 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -360,6 +409,8 @@ class DataArrayPlotlyAccessor:
             facet_col: Dimension for subplot columns. Default: second dimension.
             facet_row: Dimension for subplot rows. Default: third dimension.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.pie()`.
 
         Returns:
@@ -372,6 +423,8 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -452,6 +505,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -466,6 +521,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.line()`.
 
         Returns:
@@ -482,6 +539,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -496,6 +555,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -509,6 +570,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.bar()`.
 
         Returns:
@@ -524,6 +587,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -538,6 +603,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -551,6 +618,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -566,6 +635,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -579,6 +650,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -591,6 +664,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -605,6 +680,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -620,6 +697,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -634,6 +713,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.scatter()`.
 
         Returns:
@@ -650,6 +731,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -663,6 +746,8 @@ class DatasetPlotlyAccessor:
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -675,6 +760,8 @@ class DatasetPlotlyAccessor:
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.box()`.
 
         Returns:
@@ -689,6 +776,8 @@ class DatasetPlotlyAccessor:
             facet_row=facet_row,
             animation_frame=animation_frame,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **px_kwargs,
         )
 
@@ -701,6 +790,8 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         colors: Colors = None,
+        facet_titles: FacetTitlesMode = "default",
+        shared_axis_labels: bool = True,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -712,6 +803,8 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             colors: Color specification (scale name, list, or dict). See module docs.
+            shared_axis_labels: If True (default), repeated axis titles on faceted
+                plots are replaced with a single shared, centered label per axis.
             **px_kwargs: Additional arguments passed to `plotly.express.pie()`.
 
         Returns:
@@ -725,5 +818,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             colors=colors,
+            facet_titles=facet_titles,
+            shared_axis_labels=shared_axis_labels,
             **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"),
 }