xarray-plotly 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

xarray_plotly/__init__.py

@@ -53,13 +53,19 @@ from xarray import DataArray, Dataset, register_dataarray_accessor, register_dat
 from xarray_plotly import config
 from xarray_plotly.accessor import DataArrayPlotlyAccessor, DatasetPlotlyAccessor
 from xarray_plotly.common import SLOT_ORDERS, auto
+from xarray_plotly.figures import (
+    add_secondary_y,
+    overlay,
+    update_traces,
+)
 
 __all__ = [
     "SLOT_ORDERS",
-    "DataArrayPlotlyAccessor",
-    "DatasetPlotlyAccessor",
+    "add_secondary_y",
     "auto",
     "config",
+    "overlay",
+    "update_traces",
     "xpx",
 ]
 

xarray_plotly/accessor.py

@@ -34,7 +34,7 @@ class DataArrayPlotlyAccessor:
         ```
     """
 
-    __all__: ClassVar = ["line", "bar", "area", "scatter", "box", "imshow", "pie"]
+    __all__: ClassVar = ["line", "bar", "fast_bar", "area", "scatter", "box", "imshow", "pie"]
 
     def __init__(self, darray: DataArray) -> None:
         self._da = darray
@@ -160,6 +160,41 @@ class DataArrayPlotlyAccessor:
             **px_kwargs,
         )
 
+    def fast_bar(
+        self,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create a bar-like chart using stacked areas for better performance.
+
+        Slot order: x -> color -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis. Default: first dimension.
+            color: Dimension for color/stacking. Default: second dimension.
+            facet_col: Dimension for subplot columns. Default: third dimension.
+            facet_row: Dimension for subplot rows. Default: fourth dimension.
+            animation_frame: Dimension for animation. Default: fifth dimension.
+            **px_kwargs: Additional arguments passed to `plotly.express.area()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.fast_bar(
+            self._da,
+            x=x,
+            color=color,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
     def scatter(
         self,
         *,
@@ -257,6 +292,11 @@ class DataArrayPlotlyAccessor:
 
         Slot order: y (rows) -> x (columns) -> facet_col -> animation_frame
 
+        Note:
+            **Difference from px.imshow**: Color bounds are computed from the
+            entire dataset by default, ensuring consistent coloring across
+            animation frames. Use `zmin`/`zmax` to override.
+
         Args:
             x: Dimension for x-axis (columns). Default: second dimension.
             y: Dimension for y-axis (rows). Default: first dimension.
@@ -344,7 +384,7 @@ class DatasetPlotlyAccessor:
         ```
     """
 
-    __all__: ClassVar = ["line", "bar", "area", "scatter", "box", "pie"]
+    __all__: ClassVar = ["line", "bar", "fast_bar", "area", "scatter", "box", "pie"]
 
     def __init__(self, dataset: Dataset) -> None:
         self._ds = dataset
@@ -496,6 +536,42 @@ class DatasetPlotlyAccessor:
             **px_kwargs,
         )
 
+    def fast_bar(
+        self,
+        var: str | None = None,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create a bar-like chart using stacked areas for better performance.
+
+        Args:
+            var: Variable to plot. If None, plots all variables with "variable" dimension.
+            x: Dimension for x-axis.
+            color: Dimension for color/stacking.
+            facet_col: Dimension for subplot columns.
+            facet_row: Dimension for subplot rows.
+            animation_frame: Dimension for animation.
+            **px_kwargs: Additional arguments passed to `plotly.express.area()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        da = self._get_dataarray(var)
+        return plotting.fast_bar(
+            da,
+            x=x,
+            color=color,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
     def scatter(
         self,
         var: str | None = None,

xarray_plotly/config.py

@@ -26,6 +26,7 @@ DEFAULT_SLOT_ORDERS: dict[str, tuple[str, ...]] = {
         "animation_frame",
     ),
     "bar": ("x", "color", "pattern_shape", "facet_col", "facet_row", "animation_frame"),
+    "fast_bar": ("x", "color", "facet_col", "facet_row", "animation_frame"),
     "area": (
         "x",
         "color",

xarray_plotly/figures.py

@@ -0,0 +1,448 @@
+"""
+Helper functions for combining and manipulating Plotly figures.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    import plotly.graph_objects as go
+
+
+def _iter_all_traces(fig: go.Figure) -> Iterator:
+    """Iterate over all traces in a figure, including animation frames.
+
+    Yields traces from fig.data first, then from each frame in fig.frames.
+    Useful for applying styling to all traces including those in animations.
+
+    Args:
+        fig: Plotly Figure.
+
+    Yields:
+        Each trace object from the figure.
+    """
+    yield from fig.data
+    for frame in fig.frames or []:
+        yield from frame.data
+
+
+def _get_subplot_axes(fig: go.Figure) -> set[tuple[str, str]]:
+    """Extract (xaxis, yaxis) pairs from figure traces.
+
+    Args:
+        fig: A Plotly figure.
+
+    Returns:
+        Set of (xaxis, yaxis) tuples, e.g., {('x', 'y'), ('x2', 'y2')}.
+    """
+    axes_pairs = set()
+    for trace in fig.data:
+        xaxis = getattr(trace, "xaxis", None) or "x"
+        yaxis = getattr(trace, "yaxis", None) or "y"
+        axes_pairs.add((xaxis, yaxis))
+    return axes_pairs
+
+
+def _validate_compatible_structure(base: go.Figure, overlay: go.Figure) -> None:
+    """Validate that overlay's subplot structure is compatible with base.
+
+    Args:
+        base: The base figure.
+        overlay: The overlay figure to check.
+
+    Raises:
+        ValueError: If overlay has subplots not present in base.
+    """
+    base_axes = _get_subplot_axes(base)
+    overlay_axes = _get_subplot_axes(overlay)
+
+    extra_axes = overlay_axes - base_axes
+    if extra_axes:
+        raise ValueError(
+            f"Overlay figure has subplots not present in base figure: {extra_axes}. "
+            "Ensure both figures have the same facet structure."
+        )
+
+
+def _validate_animation_compatibility(base: go.Figure, overlay: go.Figure) -> None:
+    """Validate animation frame compatibility between base and overlay.
+
+    Args:
+        base: The base figure.
+        overlay: The overlay figure to check.
+
+    Raises:
+        ValueError: If overlay has animation but base doesn't, or frame names don't match.
+    """
+    base_has_frames = bool(base.frames)
+    overlay_has_frames = bool(overlay.frames)
+
+    if overlay_has_frames and not base_has_frames:
+        raise ValueError(
+            "Overlay figure has animation frames but base figure does not. "
+            "Cannot add animated overlay to static base figure."
+        )
+
+    if base_has_frames and overlay_has_frames:
+        base_frame_names = {frame.name for frame in base.frames}
+        overlay_frame_names = {frame.name for frame in overlay.frames}
+
+        if base_frame_names != overlay_frame_names:
+            missing_in_overlay = base_frame_names - overlay_frame_names
+            extra_in_overlay = overlay_frame_names - base_frame_names
+            msg = "Animation frame names don't match between base and overlay."
+            if missing_in_overlay:
+                msg += f" Missing in overlay: {missing_in_overlay}."
+            if extra_in_overlay:
+                msg += f" Extra in overlay: {extra_in_overlay}."
+            raise ValueError(msg)
+
+
+def _merge_frames(
+    base: go.Figure,
+    overlays: list[go.Figure],
+    base_trace_count: int,
+    overlay_trace_counts: list[int],
+) -> list:
+    """Merge animation frames from base and overlay figures.
+
+    Args:
+        base: The base figure with animation frames.
+        overlays: List of overlay figures (may or may not have frames).
+        base_trace_count: Number of traces in the base figure.
+        overlay_trace_counts: Number of traces in each overlay figure.
+
+    Returns:
+        List of merged frames.
+    """
+    import plotly.graph_objects as go
+
+    merged_frames = []
+
+    for base_frame in base.frames:
+        frame_name = base_frame.name
+        merged_data = list(base_frame.data)
+
+        for overlay, _overlay_trace_count in zip(overlays, overlay_trace_counts, strict=False):
+            if overlay.frames:
+                # Find matching frame in overlay
+                overlay_frame = next((f for f in overlay.frames if f.name == frame_name), None)
+                if overlay_frame:
+                    merged_data.extend(overlay_frame.data)
+            else:
+                # Static overlay: replicate traces to this frame
+                merged_data.extend(overlay.data)
+
+        merged_frames.append(
+            go.Frame(
+                data=merged_data,
+                name=frame_name,
+                traces=list(range(base_trace_count + sum(overlay_trace_counts))),
+            )
+        )
+
+    return merged_frames
+
+
+def overlay(base: go.Figure, *overlays: go.Figure) -> go.Figure:
+    """Overlay multiple Plotly figures on the same axes.
+
+    Creates a new figure with the base figure's layout, sliders, and buttons,
+    with all overlay traces added on top. Correctly handles faceted figures
+    and animation frames.
+
+    Args:
+        base: The base figure whose layout is preserved.
+        *overlays: One or more figures to overlay on the base.
+
+    Returns:
+        A new combined figure.
+
+    Raises:
+        ValueError: If overlay has subplots not in base, animation frames don't match,
+            or overlay has animation but base doesn't.
+
+    Example:
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xarray_plotly import xpx, overlay
+        >>>
+        >>> da = xr.DataArray(np.random.rand(10, 3), dims=["time", "cat"])
+        >>> area_fig = xpx(da).area()
+        >>> line_fig = xpx(da).line()
+        >>> combined = overlay(area_fig, line_fig)
+        >>>
+        >>> # With animation
+        >>> da3d = xr.DataArray(np.random.rand(10, 3, 4), dims=["x", "cat", "time"])
+        >>> area = xpx(da3d).area(animation_frame="time")
+        >>> line = xpx(da3d).line(animation_frame="time")
+        >>> combined = overlay(area, line)
+    """
+    import plotly.graph_objects as go
+
+    if not overlays:
+        # No overlays: return a deep copy of base
+        return copy.deepcopy(base)
+
+    # Validate all overlays
+    for overlay in overlays:
+        _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
+    for overlay in overlays:
+        for trace in overlay.data:
+            combined.add_trace(copy.deepcopy(trace))
+
+    # Handle animation frames
+    if base.frames:
+        base_trace_count = len(base.data)
+        overlay_trace_counts = [len(overlay.data) for overlay in overlays]
+        merged_frames = _merge_frames(base, list(overlays), base_trace_count, overlay_trace_counts)
+        combined.frames = merged_frames
+
+    return combined
+
+
+def _build_secondary_y_mapping(base_axes: set[tuple[str, str]]) -> dict[str, str]:
+    """Build mapping from primary y-axes to secondary y-axes.
+
+    Args:
+        base_axes: Set of (xaxis, yaxis) pairs from base figure.
+
+    Returns:
+        Dict mapping primary yaxis names to secondary yaxis names.
+        E.g., {'y': 'y4', 'y2': 'y5', 'y3': 'y6'}
+    """
+    primary_y_axes = sorted({yaxis for _, yaxis in base_axes})
+
+    # Find the highest existing yaxis number
+    max_y_num = 1  # 'y' is 1
+    for yaxis in primary_y_axes:
+        num = 1 if yaxis == "y" else int(yaxis[1:])
+        max_y_num = max(max_y_num, num)
+
+    # Create mapping: primary_yaxis -> secondary_yaxis
+    y_mapping = {}
+    next_y_num = max_y_num + 1
+    for yaxis in primary_y_axes:
+        y_mapping[yaxis] = f"y{next_y_num}"
+        next_y_num += 1
+
+    return y_mapping
+
+
+def add_secondary_y(
+    base: go.Figure,
+    secondary: go.Figure,
+    *,
+    secondary_y_title: str | None = None,
+) -> go.Figure:
+    """Add a secondary y-axis with traces from another figure.
+
+    Creates a new figure with the base figure's layout and secondary y-axes
+    on the right side. All traces from the secondary figure are plotted against
+    the secondary y-axes. Supports faceted figures when both have matching
+    facet structure.
+
+    Args:
+        base: The base figure (left y-axis).
+        secondary: The figure whose traces use the secondary y-axis (right).
+        secondary_y_title: Optional title for the secondary y-axis.
+            If not provided, uses the secondary figure's y-axis title.
+
+    Returns:
+        A new figure with both primary and secondary y-axes.
+
+    Raises:
+        ValueError: If facet structures don't match, or if animation
+            frames don't match.
+
+    Example:
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xarray_plotly import xpx, add_secondary_y
+        >>>
+        >>> # Two variables with different scales
+        >>> temp = xr.DataArray([20, 22, 25, 23], dims=["time"], name="Temperature (°C)")
+        >>> precip = xr.DataArray([0, 5, 12, 2], dims=["time"], name="Precipitation (mm)")
+        >>>
+        >>> temp_fig = xpx(temp).line()
+        >>> precip_fig = xpx(precip).bar()
+        >>> combined = add_secondary_y(temp_fig, precip_fig)
+        >>>
+        >>> # With facets
+        >>> data = xr.DataArray(np.random.rand(10, 3), dims=["x", "facet"])
+        >>> fig1 = xpx(data).line(facet_col="facet")
+        >>> fig2 = xpx(data * 100).bar(facet_col="facet")  # Different scale
+        >>> combined = add_secondary_y(fig1, fig2)
+    """
+    import plotly.graph_objects as go
+
+    # Get axis pairs from both figures
+    base_axes = _get_subplot_axes(base)
+    secondary_axes = _get_subplot_axes(secondary)
+
+    # Validate same facet structure
+    if base_axes != secondary_axes:
+        raise ValueError(
+            f"Base and secondary figures must have the same facet structure. "
+            f"Base has {base_axes}, secondary has {secondary_axes}."
+        )
+
+    # Validate animation compatibility
+    _validate_animation_compatibility(base, secondary)
+
+    # Build mapping from primary y-axes to secondary y-axes
+    y_mapping = _build_secondary_y_mapping(base_axes)
+
+    # 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
+    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)
+
+    # Configure secondary y-axes
+    for primary_yaxis, secondary_yaxis in y_mapping.items():
+        # Get title - only set on first secondary axis or use provided title
+        title = None
+        if secondary_y_title is not None:
+            # Only set title on the first secondary axis to avoid repetition
+            if primary_yaxis == "y":
+                title = secondary_y_title
+        elif primary_yaxis == "y" and secondary.layout.yaxis and secondary.layout.yaxis.title:
+            # Try to get from secondary's layout
+            title = secondary.layout.yaxis.title.text
+
+        # Configure the secondary axis
+        axis_config = {
+            "title": title,
+            "overlaying": primary_yaxis,
+            "side": "right",
+            "anchor": "free" if primary_yaxis != "y" else None,
+        }
+        # Remove None values
+        axis_config = {k: v for k, v in axis_config.items() if v is not None}
+
+        # Convert y2 -> yaxis2, y3 -> yaxis3, etc. for layout property name
+        layout_prop = "yaxis" if secondary_yaxis == "y" else f"yaxis{secondary_yaxis[1:]}"
+        combined.update_layout(**{layout_prop: axis_config})
+
+    # Handle animation frames
+    if base.frames:
+        merged_frames = _merge_secondary_y_frames(base, secondary, y_mapping)
+        combined.frames = merged_frames
+
+    return combined
+
+
+def _merge_secondary_y_frames(
+    base: go.Figure,
+    secondary: go.Figure,
+    y_mapping: dict[str, str],
+) -> list:
+    """Merge animation frames for secondary y-axis combination.
+
+    Args:
+        base: The base figure with animation frames.
+        secondary: The secondary figure (may or may not have frames).
+        y_mapping: Mapping from primary y-axis names to secondary y-axis names.
+
+    Returns:
+        List of merged frames with secondary traces assigned to secondary y-axes.
+    """
+    import plotly.graph_objects as go
+
+    merged_frames = []
+    base_trace_count = len(base.data)
+    secondary_trace_count = len(secondary.data)
+
+    for base_frame in base.frames:
+        frame_name = base_frame.name
+        merged_data = list(base_frame.data)
+
+        if secondary.frames:
+            # Find matching frame in secondary
+            secondary_frame = next((f for f in secondary.frames if f.name == frame_name), None)
+            if secondary_frame:
+                # Add secondary frame data with remapped y-axis
+                for trace_data in secondary_frame.data:
+                    trace_copy = copy.deepcopy(trace_data)
+                    original_yaxis = getattr(trace_copy, "yaxis", None) or "y"
+                    trace_copy.yaxis = y_mapping.get(original_yaxis, original_yaxis)
+                    merged_data.append(trace_copy)
+        else:
+            # Static secondary: replicate traces to this frame
+            for trace in secondary.data:
+                trace_copy = copy.deepcopy(trace)
+                original_yaxis = getattr(trace_copy, "yaxis", None) or "y"
+                trace_copy.yaxis = y_mapping.get(original_yaxis, original_yaxis)
+                merged_data.append(trace_copy)
+
+        merged_frames.append(
+            go.Frame(
+                data=merged_data,
+                name=frame_name,
+                traces=list(range(base_trace_count + secondary_trace_count)),
+            )
+        )
+
+    return merged_frames
+
+
+def update_traces(fig: go.Figure, selector: dict | None = None, **kwargs) -> go.Figure:
+    """Update traces in both base figure and all animation frames.
+
+    Plotly's `update_traces()` only updates the base figure, not animation frames.
+    This function updates both, ensuring trace styles persist during animation.
+
+    Args:
+        fig: A Plotly figure, optionally with animation frames.
+        selector: Dict to match specific traces, e.g. ``{"name": "Germany"}``.
+            If None, updates all traces.
+        **kwargs: Trace properties to update, e.g. ``line_width=4``, ``line_dash="dot"``.
+
+    Returns:
+        The modified figure (same object, mutated in place).
+
+    Example:
+        >>> import plotly.express as px
+        >>> from xarray_plotly import update_traces
+        >>>
+        >>> df = px.data.gapminder()
+        >>> fig = px.line(df, x="year", y="gdpPercap", color="country", animation_frame="continent")
+        >>>
+        >>> # Update all traces
+        >>> update_traces(fig, line_width=3)
+        >>>
+        >>> # Update specific trace by name
+        >>> update_traces(fig, selector={"name": "Germany"}, line_width=5, line_dash="dot")
+    """
+    for trace in _iter_all_traces(fig):
+        if selector is None:
+            trace.update(**kwargs)
+        else:
+            # Check if trace matches all selector criteria
+            if all(getattr(trace, k, None) == v for k, v in selector.items()):
+                trace.update(**kwargs)
+
+    return fig

xarray_plotly/plotting.py

@@ -4,6 +4,7 @@ Plotly Express plotting functions for DataArray objects.
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
@@ -18,6 +19,9 @@ from xarray_plotly.common import (
     get_value_col,
     to_dataframe,
 )
+from xarray_plotly.figures import (
+    _iter_all_traces,
+)
 
 if TYPE_CHECKING:
     import plotly.graph_objects as go
@@ -167,6 +171,167 @@ def bar(
     )
 
 
+def _classify_trace_sign(y_values: np.ndarray) -> str:
+    """Classify a trace as 'positive', 'negative', or 'mixed' based on its values."""
+    y_arr = np.asarray(y_values)
+    y_clean = y_arr[np.isfinite(y_arr) & (np.abs(y_arr) > 1e-9)]
+    if len(y_clean) == 0:
+        return "zero"
+    has_pos = bool(np.any(y_clean > 0))
+    has_neg = bool(np.any(y_clean < 0))
+    if has_pos and has_neg:
+        return "mixed"
+    elif has_neg:
+        return "negative"
+    elif has_pos:
+        return "positive"
+    return "zero"
+
+
+def _style_traces_as_bars(fig: go.Figure) -> None:
+    """Style area chart traces to look like bar charts with proper pos/neg stacking.
+
+    Classifies each trace (by name) across all data and animation frames,
+    then assigns stackgroups: positive traces stack upward, negative stack downward.
+    """
+    # Collect all traces (main + animation frames)
+    all_traces = list(_iter_all_traces(fig))
+
+    # Classify each trace name by aggregating sign info across all occurrences
+    sign_flags: dict[str, dict[str, bool]] = {}
+    for trace in all_traces:
+        if trace.name not in sign_flags:
+            sign_flags[trace.name] = {"has_pos": False, "has_neg": False}
+        if trace.y is not None and len(trace.y) > 0:
+            y_arr = np.asarray(trace.y)
+            y_clean = y_arr[np.isfinite(y_arr) & (np.abs(y_arr) > 1e-9)]
+            if len(y_clean) > 0:
+                if np.any(y_clean > 0):
+                    sign_flags[trace.name]["has_pos"] = True
+                if np.any(y_clean < 0):
+                    sign_flags[trace.name]["has_neg"] = True
+
+    # Build classification map
+    class_map: dict[str, str] = {}
+    mixed_traces: list[str] = []
+    for name, flags in sign_flags.items():
+        if flags["has_pos"] and flags["has_neg"]:
+            class_map[name] = "mixed"
+            mixed_traces.append(name)
+        elif flags["has_neg"]:
+            class_map[name] = "negative"
+        elif flags["has_pos"]:
+            class_map[name] = "positive"
+        else:
+            class_map[name] = "zero"
+
+    # Warn about mixed traces
+    if mixed_traces:
+        warnings.warn(
+            f"fast_bar: traces {mixed_traces} have mixed positive/negative values "
+            "and cannot be stacked. They are shown as dashed lines. "
+            "Consider using bar() for proper stacking of mixed data.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+    # Apply styling to all traces
+    for trace in all_traces:
+        color = trace.line.color
+        cls = class_map.get(trace.name, "positive")
+
+        if cls in ("positive", "negative"):
+            trace.stackgroup = cls
+            trace.fillcolor = color
+            trace.line = {"width": 0, "color": color, "shape": "hv"}
+        elif cls == "mixed":
+            # Mixed: no stacking, show as dashed line
+            trace.stackgroup = None
+            trace.fill = None
+            trace.line = {"width": 2, "color": color, "shape": "hv", "dash": "dash"}
+        else:  # zero
+            trace.stackgroup = None
+            trace.fill = None
+            trace.line = {"width": 0, "color": color, "shape": "hv"}
+
+
+def fast_bar(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    color: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create a bar-like chart using stacked areas for better performance.
+
+    Uses `px.area` with stepped lines and no outline to create a bar-like
+    appearance. Renders faster than `bar()` for large datasets because it
+    uses a single polygon per trace instead of individual rectangles.
+
+    The y-axis shows DataArray values. Dimensions fill slots in order:
+    x -> color -> facet_col -> facet_row -> animation_frame
+
+    Traces are classified by their values: purely positive traces stack upward,
+    purely negative traces stack downward. Traces with mixed signs are shown
+    as dashed lines without stacking.
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis. Default: first dimension.
+    color
+        Dimension for color/stacking. Default: second dimension.
+    facet_col
+        Dimension for subplot columns. Default: third dimension.
+    facet_row
+        Dimension for subplot rows. Default: fourth dimension.
+    animation_frame
+        Dimension for animation. Default: fifth dimension.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.area()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "fast_bar",
+        x=x,
+        color=color,
+        facet_col=facet_col,
+        facet_row=facet_row,
+        animation_frame=animation_frame,
+    )
+
+    df = to_dataframe(darray)
+    value_col = get_value_col(darray)
+    labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
+
+    fig = px.area(
+        df,
+        x=slots.get("x"),
+        y=value_col,
+        color=slots.get("color"),
+        facet_col=slots.get("facet_col"),
+        facet_row=slots.get("facet_row"),
+        animation_frame=slots.get("animation_frame"),
+        line_shape="hv",
+        labels=labels,
+        **px_kwargs,
+    )
+
+    _style_traces_as_bars(fig)
+
+    return fig
+
+
 def area(
     darray: DataArray,
     *,
@@ -408,6 +573,14 @@ def imshow(
     Both x and y are dimensions. Dimensions fill slots in order:
     y (rows) -> x (columns) -> facet_col -> animation_frame
 
+    .. note::
+        **Difference from plotly.express.imshow**: By default, color bounds
+        (zmin/zmax) are computed from the **entire dataset**, ensuring
+        consistent coloring across animation frames and facets. In contrast,
+        ``px.imshow`` auto-scales each frame independently, which can make
+        animations visually confusing. Set ``zmin`` and ``zmax`` explicitly
+        to override this behavior.
+
     Parameters
     ----------
     darray
@@ -422,7 +595,7 @@ def imshow(
         Dimension for animation. Default: fourth dimension.
     robust
         If True, compute color bounds using 2nd and 98th percentiles
-        for robustness against outliers. Default: False.
+        for robustness against outliers. Default: False (uses min/max).
     **px_kwargs
         Additional arguments passed to `plotly.express.imshow()`.
         Use `zmin` and `zmax` to manually set color scale bounds.

{xarray_plotly-0.0.6.dist-info → xarray_plotly-0.0.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.6
+Version: 0.0.8
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT
@@ -28,7 +28,7 @@ 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.14.11; extra == "dev"
+Requires-Dist: ruff==0.14.13; extra == "dev"
 Requires-Dist: pre-commit==4.5.1; extra == "dev"
 Requires-Dist: nbstripout==0.8.2; extra == "dev"
 Provides-Extra: docs

xarray_plotly-0.0.8.dist-info/RECORD

@@ -0,0 +1,12 @@
+xarray_plotly/__init__.py,sha256=vAM2TCeLnSkSjwCDETlBI_1SukhVeth7HFMaFIWl_ps,3384
+xarray_plotly/accessor.py,sha256=eP4_GPBCN-c32M8s1LJv4Zn4PvHHO9HsP5oPQMDDd6I,23150
+xarray_plotly/common.py,sha256=YTiaPLJ0Gh20mHV8-72J8DjWk-XaSYaT_ZiqXp6cecU,7192
+xarray_plotly/config.py,sha256=gS6IqWdx82PQs1yZzl_diGHlnmVTladuWZzk1lYgIsQ,6569
+xarray_plotly/figures.py,sha256=5SxTTPCgaEMRC5Bz7Ew1leJXDNMA1ZchbY_dO82SHY4,15574
+xarray_plotly/plotting.py,sha256=Fl_UklCN8AYtPj0t3m8zXwcz6MsFLdmQrKZC68IH1OM,20668
+xarray_plotly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xarray_plotly-0.0.8.dist-info/licenses/LICENSE,sha256=AvVEfNqbhIm9jHvt0acJNjW1JUKa2a70Zb5rJdEXCJI,1064
+xarray_plotly-0.0.8.dist-info/METADATA,sha256=ezKDOXZ7CklqOB5KDBh32Lm1nri63OF_OoeCKhuIt9c,3415
+xarray_plotly-0.0.8.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+xarray_plotly-0.0.8.dist-info/top_level.txt,sha256=GtMkvuZvLAYTjYXtwoNUa0ag42CJARZJK1CZemYD7pg,14
+xarray_plotly-0.0.8.dist-info/RECORD,,

{xarray_plotly-0.0.6.dist-info → xarray_plotly-0.0.8.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

xarray_plotly-0.0.6.dist-info/RECORD

@@ -1,11 +0,0 @@
-xarray_plotly/__init__.py,sha256=o8w-prP-J-XWr6Bx5vqqpQEz1maAc0Sycq2q7ll5nuI,3294
-xarray_plotly/accessor.py,sha256=2vVvAv6K92wUyhQjAge3v85f2gk5mkrRC3VjBWJTGeo,20529
-xarray_plotly/common.py,sha256=YTiaPLJ0Gh20mHV8-72J8DjWk-XaSYaT_ZiqXp6cecU,7192
-xarray_plotly/config.py,sha256=-Sp6TNx-8Zk6x0WmJ5j_KGHPRY639ju3_RSemrlmuXY,6492
-xarray_plotly/plotting.py,sha256=upUt6620pUKUdIYAvDrxFuxBtQm79ZM11IleSajPScU,14799
-xarray_plotly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xarray_plotly-0.0.6.dist-info/licenses/LICENSE,sha256=AvVEfNqbhIm9jHvt0acJNjW1JUKa2a70Zb5rJdEXCJI,1064
-xarray_plotly-0.0.6.dist-info/METADATA,sha256=YiTD_OutpKfk-VCxi_eZKEAR8vK2sWoRgaa2DA_Xvr0,3415
-xarray_plotly-0.0.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xarray_plotly-0.0.6.dist-info/top_level.txt,sha256=GtMkvuZvLAYTjYXtwoNUa0ag42CJARZJK1CZemYD7pg,14
-xarray_plotly-0.0.6.dist-info/RECORD,,