xarray-plotly 0.0.3__py3-none-any.whl

xarray_plotly/__init__.py

@@ -0,0 +1,81 @@
+"""Interactive Plotly Express plotting for xarray.
+
+This package provides a `plotly` accessor for xarray DataArray objects,
+enabling interactive visualization with Plotly Express.
+
+Features:
+    - **Interactive plots**: Zoom, pan, hover, toggle traces
+    - **Automatic dimension assignment**: Dimensions fill slots (x, color, facet) by position
+    - **Multiple plot types**: line, bar, area, scatter, box, imshow
+    - **Faceting and animation**: Built-in subplot grids and animated plots
+    - **Customizable**: Returns Plotly Figure objects for further modification
+
+Usage:
+    Accessor style::
+
+        import xarray_plotly
+        fig = da.plotly.line()
+
+    Function style (recommended for IDE completion)::
+
+        from xarray_plotly import xpx
+        fig = xpx(da).line()
+
+Example:
+    ```python
+    import xarray as xr
+    import numpy as np
+    from xarray_plotly import xpx
+
+    da = xr.DataArray(
+        np.random.rand(10, 3, 2),
+        dims=["time", "city", "scenario"],
+    )
+    fig = xpx(da).line()  # Auto: time->x, city->color, scenario->facet_col
+    fig = xpx(da).line(x="time", color="scenario")  # Explicit
+    fig = xpx(da).line(color=None)  # Skip slot
+    ```
+"""
+
+from importlib.metadata import version
+
+from xarray import DataArray, register_dataarray_accessor
+
+from xarray_plotly import config
+from xarray_plotly.accessor import DataArrayPlotlyAccessor
+from xarray_plotly.common import SLOT_ORDERS, auto
+
+__all__ = [
+    "SLOT_ORDERS",
+    "DataArrayPlotlyAccessor",
+    "auto",
+    "config",
+    "xpx",
+]
+
+
+def xpx(da: DataArray) -> DataArrayPlotlyAccessor:
+    """Get the plotly accessor for a DataArray with full IDE code completion.
+
+    This is an alternative to `da.plotly` that provides proper type hints
+    and code completion in IDEs.
+
+    Args:
+        da: The DataArray to plot.
+
+    Returns:
+        The accessor with plotting methods (line, bar, area, scatter, box, imshow).
+
+    Example:
+        ```python
+        from xarray_plotly import xpx
+        fig = xpx(da).line()  # Full code completion works here
+        ```
+    """
+    return DataArrayPlotlyAccessor(da)
+
+
+__version__ = version("xarray_plotly")
+
+# Register the accessor
+register_dataarray_accessor("plotly")(DataArrayPlotlyAccessor)

xarray_plotly/accessor.py

@@ -0,0 +1,275 @@
+"""Accessor classes for Plotly Express plotting on DataArray."""
+
+from typing import Any, ClassVar
+
+import plotly.graph_objects as go
+from xarray import DataArray
+
+from xarray_plotly import plotting
+from xarray_plotly.common import SlotValue, auto
+
+
+class DataArrayPlotlyAccessor:
+    """Plotly Express plotting accessor for xarray DataArray.
+
+    Dimensions are automatically assigned to plot slots by position.
+    All methods return Plotly Figure objects for interactive visualization.
+
+    Available methods: line, bar, area, scatter, box, imshow
+
+    Args:
+        darray: The DataArray to plot.
+
+    Example:
+        ```python
+        import xarray as xr
+        import numpy as np
+
+        da = xr.DataArray(np.random.rand(10, 3), dims=["time", "city"])
+        fig = da.plotly.line()  # Auto: time->x, city->color
+        fig = da.plotly.line(color="time", x="city")  # Explicit
+        fig = da.plotly.line(color=None)  # Skip slot
+        fig.update_layout(title="My Plot")  # Customize
+        ```
+    """
+
+    __all__: ClassVar = ["line", "bar", "area", "scatter", "box", "imshow"]
+
+    def __init__(self, darray: DataArray) -> None:
+        self._da = darray
+
+    def __dir__(self) -> list[str]:
+        """List available plot methods."""
+        return list(self.__all__) + list(super().__dir__())
+
+    def line(
+        self,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = auto,
+        line_dash: SlotValue = auto,
+        symbol: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive line plot.
+
+        Slot order: x -> color -> line_dash -> symbol -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis. Default: first dimension.
+            color: Dimension for color grouping. Default: second dimension.
+            line_dash: Dimension for line dash style. Default: third dimension.
+            symbol: Dimension for marker symbol. Default: fourth dimension.
+            facet_col: Dimension for subplot columns. Default: fifth dimension.
+            facet_row: Dimension for subplot rows. Default: sixth dimension.
+            animation_frame: Dimension for animation. Default: seventh dimension.
+            **px_kwargs: Additional arguments passed to `plotly.express.line()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.line(
+            self._da,
+            x=x,
+            color=color,
+            line_dash=line_dash,
+            symbol=symbol,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
+    def bar(
+        self,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = auto,
+        pattern_shape: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive bar chart.
+
+        Slot order: x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis. Default: first dimension.
+            color: Dimension for color grouping. Default: second dimension.
+            pattern_shape: Dimension for bar fill pattern. Default: third dimension.
+            facet_col: Dimension for subplot columns. Default: fourth dimension.
+            facet_row: Dimension for subplot rows. Default: fifth dimension.
+            animation_frame: Dimension for animation. Default: sixth dimension.
+            **px_kwargs: Additional arguments passed to `plotly.express.bar()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.bar(
+            self._da,
+            x=x,
+            color=color,
+            pattern_shape=pattern_shape,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
+    def area(
+        self,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = auto,
+        pattern_shape: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive stacked area chart.
+
+        Slot order: x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis. Default: first dimension.
+            color: Dimension for color/stacking. Default: second dimension.
+            pattern_shape: Dimension for fill pattern. Default: third dimension.
+            facet_col: Dimension for subplot columns. Default: fourth dimension.
+            facet_row: Dimension for subplot rows. Default: fifth dimension.
+            animation_frame: Dimension for animation. Default: sixth dimension.
+            **px_kwargs: Additional arguments passed to `plotly.express.area()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.area(
+            self._da,
+            x=x,
+            color=color,
+            pattern_shape=pattern_shape,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
+    def scatter(
+        self,
+        *,
+        x: SlotValue = auto,
+        y: SlotValue | str = "value",
+        color: SlotValue = auto,
+        symbol: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        facet_row: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive scatter plot.
+
+        By default, y-axis shows the DataArray values. Set y to a dimension
+        name to create dimension-vs-dimension plots (e.g., lat vs lon).
+
+        Slot order: x -> color -> symbol -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis. Default: first dimension.
+            y: What to plot on y-axis. Default "value" uses DataArray values.
+                Can be a dimension name for dimension vs dimension plots.
+            color: Dimension for color grouping, or "value" for DataArray values.
+            symbol: Dimension for marker symbol. Default: third dimension.
+            facet_col: Dimension for subplot columns. Default: fourth dimension.
+            facet_row: Dimension for subplot rows. Default: fifth dimension.
+            animation_frame: Dimension for animation. Default: sixth dimension.
+            **px_kwargs: Additional arguments passed to `plotly.express.scatter()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.scatter(
+            self._da,
+            x=x,
+            y=y,
+            color=color,
+            symbol=symbol,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
+    def box(
+        self,
+        *,
+        x: SlotValue = auto,
+        color: SlotValue = None,
+        facet_col: SlotValue = None,
+        facet_row: SlotValue = None,
+        animation_frame: SlotValue = None,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive box plot.
+
+        By default, only the first dimension is assigned to x; all other
+        dimensions are aggregated into the box statistics.
+
+        Slot order: x -> color -> facet_col -> facet_row -> animation_frame
+
+        Args:
+            x: Dimension for x-axis categories. Default: first dimension.
+            color: Dimension for color grouping. Default: None (aggregated).
+            facet_col: Dimension for subplot columns. Default: None (aggregated).
+            facet_row: Dimension for subplot rows. Default: None (aggregated).
+            animation_frame: Dimension for animation. Default: None (aggregated).
+            **px_kwargs: Additional arguments passed to `plotly.express.box()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.box(
+            self._da,
+            x=x,
+            color=color,
+            facet_col=facet_col,
+            facet_row=facet_row,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )
+
+    def imshow(
+        self,
+        *,
+        x: SlotValue = auto,
+        y: SlotValue = auto,
+        facet_col: SlotValue = auto,
+        animation_frame: SlotValue = auto,
+        **px_kwargs: Any,
+    ) -> go.Figure:
+        """Create an interactive heatmap image.
+
+        Slot order: y (rows) -> x (columns) -> facet_col -> animation_frame
+
+        Args:
+            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.
+            **px_kwargs: Additional arguments passed to `plotly.express.imshow()`.
+
+        Returns:
+            Interactive Plotly Figure.
+        """
+        return plotting.imshow(
+            self._da,
+            x=x,
+            y=y,
+            facet_col=facet_col,
+            animation_frame=animation_frame,
+            **px_kwargs,
+        )

xarray_plotly/common.py

@@ -0,0 +1,229 @@
+"""Common utilities for dimension-to-slot assignment and data conversion."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xarray_plotly.config import DEFAULT_SLOT_ORDERS, _options
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Sequence
+
+    import pandas as pd
+    from xarray import DataArray
+
+
+class _AUTO:
+    """Sentinel value for automatic slot assignment."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "auto"
+
+
+auto = _AUTO()
+
+SlotValue = _AUTO | str | None
+"""Type alias for slot values: auto, explicit dimension name, or None (skip)."""
+
+# Re-export for backward compatibility
+SLOT_ORDERS = DEFAULT_SLOT_ORDERS
+"""Slot orders per plot type.
+
+For most plots, y-axis shows DataArray values (not a dimension slot).
+For imshow, both y and x are dimensions (rows and columns of the heatmap).
+
+Note:
+    To customize slot orders, use `config.set_options(slot_orders=...)`.
+"""
+
+
+def assign_slots(
+    dims: Sequence[Hashable],
+    plot_type: str,
+    *,
+    allow_unassigned: bool = False,
+    **slot_kwargs: SlotValue,
+) -> dict[str, Hashable]:
+    """Assign dimensions to plot slots based on position.
+
+    Positional assignment: dimensions fill slots in order.
+    - Explicit assignments lock a dimension to a slot
+    - None skips a slot
+    - Remaining dims fill remaining slots by position
+    - Error if dims left over after all slots filled (unless allow_unassigned=True)
+
+    Args:
+        dims: Dimension names from the DataArray.
+        plot_type: Type of plot (line, bar, area, scatter, box, imshow).
+        allow_unassigned: If True, allow dimensions to remain unassigned.
+        **slot_kwargs: Explicit slot assignments. Use `auto` for positional,
+            a dimension name for explicit, or `None` to skip.
+
+    Returns:
+        Mapping of slot names to dimension names.
+
+    Raises:
+        ValueError: If plot_type is unknown, dimension doesn't exist, or
+            dimensions are left unassigned (unless allow_unassigned=True).
+
+    Example:
+        ```python
+        assign_slots(["time", "city", "scenario"], "line")
+        # {'x': 'time', 'color': 'city', 'line_dash': 'scenario'}
+
+        assign_slots(["time", "city"], "line", color="time", x="city")
+        # {'x': 'city', 'color': 'time'}
+
+        assign_slots(["time", "city", "scenario"], "line", color=None)
+        # {'x': 'time', 'line_dash': 'city', 'symbol': 'scenario'}
+        ```
+    """
+    slot_orders = _options.slot_orders
+    if plot_type not in slot_orders:
+        msg = f"Unknown plot type: {plot_type!r}. Available types: {list(slot_orders.keys())}"
+        raise ValueError(msg)
+
+    slot_order = slot_orders[plot_type]
+    dims_list = list(dims)
+
+    slots: dict[str, Hashable] = {}
+    used_dims: set[Hashable] = set()
+    available_slots = list(slot_order)
+
+    # Pass 1: Process explicit assignments (non-auto, non-None)
+    for slot in slot_order:
+        value = slot_kwargs.get(slot, auto)
+
+        if value is None:
+            # Skip this slot
+            if slot in available_slots:
+                available_slots.remove(slot)
+        elif not isinstance(value, _AUTO):
+            # Explicit assignment - can be a dimension name or "value" (DataArray values)
+            if value == "value":
+                slots[slot] = "value"
+            elif value not in dims_list:
+                msg = (
+                    f"Dimension {value!r} assigned to slot {slot!r} "
+                    f"is not in the data dimensions: {dims_list}"
+                )
+                raise ValueError(msg)
+            else:
+                slots[slot] = value
+                used_dims.add(value)
+            if slot in available_slots:
+                available_slots.remove(slot)
+
+    # Pass 2: Fill remaining slots with remaining dims (by position)
+    remaining_dims = [d for d in dims_list if d not in used_dims]
+    for slot, dim in zip(available_slots, remaining_dims, strict=False):
+        slots[slot] = dim
+        used_dims.add(dim)
+
+    # Check for unassigned dimensions
+    unassigned = [d for d in dims_list if d not in used_dims]
+    if unassigned and not allow_unassigned:
+        msg = (
+            f"Unassigned dimension(s): {unassigned}. "
+            "Reduce with .sel(), .isel(), or .mean() before plotting."
+        )
+        raise ValueError(msg)
+
+    return slots
+
+
+def get_value_col(darray: DataArray) -> str:
+    """Get the column name for DataArray values."""
+    return str(darray.name) if darray.name is not None else "value"
+
+
+def to_dataframe(darray: DataArray) -> pd.DataFrame:
+    """Convert a DataArray to a long-form DataFrame for Plotly Express."""
+    if darray.name is None:
+        darray = darray.rename("value")
+    df: pd.DataFrame = darray.to_dataframe().reset_index()
+    return df
+
+
+def _get_label_from_attrs(attrs: dict, fallback: str) -> str:
+    """Extract a label from xarray attributes based on current config.
+
+    Args:
+        attrs: Attributes dictionary from DataArray or coordinate.
+        fallback: Fallback label if no attributes match.
+
+    Returns:
+        The formatted label.
+    """
+    label = None
+
+    if _options.label_use_long_name:
+        label = attrs.get("long_name")
+
+    if label is None and _options.label_use_standard_name:
+        label = attrs.get("standard_name")
+
+    if label is None:
+        return fallback
+
+    if _options.label_include_units:
+        units = attrs.get("units")
+        if units:
+            return f"{label} {_options.label_unit_format.format(units=units)}"
+
+    return str(label)
+
+
+def get_label(darray: DataArray, name: Hashable) -> str:
+    """Get a human-readable label for a dimension or the value column.
+
+    Uses long_name/standard_name and units from attributes based on
+    current configuration (see `config.set_options`).
+    """
+    # Check if it's asking for the value column label
+    value_col = get_value_col(darray)
+    if str(name) == value_col or name == "value":
+        return _get_label_from_attrs(darray.attrs, value_col)
+
+    # It's a dimension/coordinate
+    if name in darray.coords:
+        coord = darray.coords[name]
+        return _get_label_from_attrs(coord.attrs, str(name))
+
+    return str(name)
+
+
+def build_labels(
+    darray: DataArray,
+    slots: dict[str, Hashable],
+    value_col: str,
+    *,
+    include_value: bool = True,
+) -> dict[str, str]:
+    """Build a labels dict for Plotly Express from slot assignments.
+
+    Args:
+        darray: The source DataArray.
+        slots: Slot assignments from assign_slots().
+        value_col: The name of the value column in the DataFrame.
+        include_value: Whether to include a label for the value column.
+
+    Returns:
+        Mapping of column names to human-readable labels.
+    """
+    labels: dict[str, str] = {}
+
+    # Add labels for assigned dimensions
+    for slot_value in slots.values():
+        if slot_value and slot_value != "value":
+            key = str(slot_value)
+            if key not in labels:
+                labels[key] = get_label(darray, slot_value)
+
+    # Add label for value column
+    if include_value and value_col not in labels:
+        labels[value_col] = get_label(darray, "value")
+
+    return labels

xarray_plotly/config.py

@@ -0,0 +1,178 @@
+"""Configuration for xarray_plotly.
+
+This module provides a global configuration system similar to xarray and pandas,
+allowing users to customize label extraction and slot assignment behavior.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+# Default slot orders per plot type
+DEFAULT_SLOT_ORDERS: dict[str, tuple[str, ...]] = {
+    "line": (
+        "x",
+        "color",
+        "line_dash",
+        "symbol",
+        "facet_col",
+        "facet_row",
+        "animation_frame",
+    ),
+    "bar": ("x", "color", "pattern_shape", "facet_col", "facet_row", "animation_frame"),
+    "area": (
+        "x",
+        "color",
+        "pattern_shape",
+        "facet_col",
+        "facet_row",
+        "animation_frame",
+    ),
+    "scatter": (
+        "x",
+        "color",
+        "symbol",
+        "facet_col",
+        "facet_row",
+        "animation_frame",
+    ),
+    "imshow": ("y", "x", "facet_col", "animation_frame"),
+    "box": ("x", "color", "facet_col", "facet_row", "animation_frame"),
+}
+
+
+@dataclass
+class Options:
+    """Configuration options for xarray_plotly.
+
+    Attributes:
+        label_use_long_name: Use `long_name` attribute for labels. Default True.
+        label_use_standard_name: Fall back to `standard_name` if `long_name` not available.
+        label_include_units: Append units to labels. Default True.
+        label_unit_format: Format string for units. Use `{units}` as placeholder.
+        slot_orders: Slot orders per plot type. Keys are plot types, values are tuples.
+    """
+
+    label_use_long_name: bool = True
+    label_use_standard_name: bool = True
+    label_include_units: bool = True
+    label_unit_format: str = "[{units}]"
+    slot_orders: dict[str, tuple[str, ...]] = field(
+        default_factory=lambda: dict(DEFAULT_SLOT_ORDERS)
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return options as a dictionary."""
+        return {
+            "label_use_long_name": self.label_use_long_name,
+            "label_use_standard_name": self.label_use_standard_name,
+            "label_include_units": self.label_include_units,
+            "label_unit_format": self.label_unit_format,
+            "slot_orders": self.slot_orders,
+        }
+
+
+# Global options instance
+_options = Options()
+
+
+def get_options() -> dict[str, Any]:
+    """Get the current xarray_plotly options.
+
+    Returns:
+        Dictionary of current option values.
+
+    Example:
+        ```python
+        from xarray_plotly import config
+        config.get_options()
+        ```
+    """
+    return _options.to_dict()
+
+
+@contextmanager
+def set_options(
+    *,
+    label_use_long_name: bool | None = None,
+    label_use_standard_name: bool | None = None,
+    label_include_units: bool | None = None,
+    label_unit_format: str | None = None,
+    slot_orders: dict[str, tuple[str, ...]] | None = None,
+) -> Generator[None, None, None]:
+    """Set xarray_plotly options globally or as a context manager.
+
+    Args:
+        label_use_long_name: Use `long_name` attribute for labels.
+        label_use_standard_name: Fall back to `standard_name` if `long_name` not available.
+        label_include_units: Append units to labels.
+        label_unit_format: Format string for units. Use `{units}` as placeholder.
+        slot_orders: Slot orders per plot type.
+
+    Yields:
+        None when used as a context manager.
+
+    Example:
+        ```python
+        from xarray_plotly import config, xpx
+
+        # Use as context manager
+        with config.set_options(label_include_units=False):
+            fig = xpx(da).line()  # No units in labels
+        # Units are back after the context
+        ```
+    """
+    # Store old values
+    old_values = {
+        "label_use_long_name": _options.label_use_long_name,
+        "label_use_standard_name": _options.label_use_standard_name,
+        "label_include_units": _options.label_include_units,
+        "label_unit_format": _options.label_unit_format,
+        "slot_orders": dict(_options.slot_orders),
+    }
+
+    # Apply new values (modify in place to keep reference)
+    if label_use_long_name is not None:
+        _options.label_use_long_name = label_use_long_name
+    if label_use_standard_name is not None:
+        _options.label_use_standard_name = label_use_standard_name
+    if label_include_units is not None:
+        _options.label_include_units = label_include_units
+    if label_unit_format is not None:
+        _options.label_unit_format = label_unit_format
+    if slot_orders is not None:
+        _options.slot_orders = dict(slot_orders)
+
+    try:
+        yield
+    finally:
+        # Restore old values (modify in place)
+        _options.label_use_long_name = old_values["label_use_long_name"]
+        _options.label_use_standard_name = old_values["label_use_standard_name"]
+        _options.label_include_units = old_values["label_include_units"]
+        _options.label_unit_format = old_values["label_unit_format"]
+        _options.slot_orders = old_values["slot_orders"]
+
+
+def notebook(renderer: str = "notebook") -> None:
+    """Configure Plotly for Jupyter notebook rendering.
+
+    Args:
+        renderer: The Plotly renderer to use. Default is "notebook".
+            Other options include "jupyterlab", "colab", "kaggle", etc.
+
+    Example:
+        ```python
+        from xarray_plotly import config
+        config.notebook()  # Configure for Jupyter notebooks
+        ```
+    """
+    import plotly.io as pio
+
+    pio.renderers.default = renderer

xarray_plotly/plotting.py

@@ -0,0 +1,448 @@
+"""
+Plotly Express plotting functions for DataArray objects.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import plotly.express as px
+
+from xarray_plotly.common import (
+    SlotValue,
+    assign_slots,
+    auto,
+    build_labels,
+    get_label,
+    get_value_col,
+    to_dataframe,
+)
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go
+    from xarray import DataArray
+
+
+def line(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    color: SlotValue = auto,
+    line_dash: SlotValue = auto,
+    symbol: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create an interactive line plot from a DataArray.
+
+    The y-axis shows DataArray values. Dimensions fill slots in order:
+    x -> color -> line_dash -> symbol -> facet_col -> facet_row -> animation_frame
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis. Default: first dimension.
+    color
+        Dimension for color grouping. Default: second dimension.
+    line_dash
+        Dimension for line dash style. Default: third dimension.
+    symbol
+        Dimension for marker symbol. Default: fourth dimension.
+    facet_col
+        Dimension for subplot columns. Default: fifth dimension.
+    facet_row
+        Dimension for subplot rows. Default: sixth dimension.
+    animation_frame
+        Dimension for animation. Default: seventh dimension.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.line()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "line",
+        x=x,
+        color=color,
+        line_dash=line_dash,
+        symbol=symbol,
+        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", {})}
+
+    return px.line(
+        df,
+        x=slots.get("x"),
+        y=value_col,
+        color=slots.get("color"),
+        line_dash=slots.get("line_dash"),
+        symbol=slots.get("symbol"),
+        facet_col=slots.get("facet_col"),
+        facet_row=slots.get("facet_row"),
+        animation_frame=slots.get("animation_frame"),
+        labels=labels,
+        **px_kwargs,
+    )
+
+
+def bar(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    color: SlotValue = auto,
+    pattern_shape: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create an interactive bar chart from a DataArray.
+
+    The y-axis shows DataArray values. Dimensions fill slots in order:
+    x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis. Default: first dimension.
+    color
+        Dimension for color grouping. Default: second dimension.
+    pattern_shape
+        Dimension for bar fill pattern. Default: third dimension.
+    facet_col
+        Dimension for subplot columns. Default: fourth dimension.
+    facet_row
+        Dimension for subplot rows. Default: fifth dimension.
+    animation_frame
+        Dimension for animation. Default: sixth dimension.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.bar()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "bar",
+        x=x,
+        color=color,
+        pattern_shape=pattern_shape,
+        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", {})}
+
+    return px.bar(
+        df,
+        x=slots.get("x"),
+        y=value_col,
+        color=slots.get("color"),
+        pattern_shape=slots.get("pattern_shape"),
+        facet_col=slots.get("facet_col"),
+        facet_row=slots.get("facet_row"),
+        animation_frame=slots.get("animation_frame"),
+        labels=labels,
+        **px_kwargs,
+    )
+
+
+def area(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    color: SlotValue = auto,
+    pattern_shape: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create an interactive stacked area chart from a DataArray.
+
+    The y-axis shows DataArray values. Dimensions fill slots in order:
+    x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis. Default: first dimension.
+    color
+        Dimension for color/stacking. Default: second dimension.
+    pattern_shape
+        Dimension for fill pattern. Default: third dimension.
+    facet_col
+        Dimension for subplot columns. Default: fourth dimension.
+    facet_row
+        Dimension for subplot rows. Default: fifth dimension.
+    animation_frame
+        Dimension for animation. Default: sixth dimension.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.area()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "area",
+        x=x,
+        color=color,
+        pattern_shape=pattern_shape,
+        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", {})}
+
+    return px.area(
+        df,
+        x=slots.get("x"),
+        y=value_col,
+        color=slots.get("color"),
+        pattern_shape=slots.get("pattern_shape"),
+        facet_col=slots.get("facet_col"),
+        facet_row=slots.get("facet_row"),
+        animation_frame=slots.get("animation_frame"),
+        labels=labels,
+        **px_kwargs,
+    )
+
+
+def box(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    color: SlotValue = None,
+    facet_col: SlotValue = None,
+    facet_row: SlotValue = None,
+    animation_frame: SlotValue = None,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create an interactive box plot from a DataArray.
+
+    The y-axis shows DataArray values. By default, only x is auto-assigned;
+    other dimensions are aggregated into the box statistics.
+
+    Dimensions fill slots in order: x -> color -> facet_col -> facet_row -> animation_frame
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis categories. Default: first dimension.
+    color
+        Dimension for color grouping. Default: None (aggregated).
+    facet_col
+        Dimension for subplot columns. Default: None (aggregated).
+    facet_row
+        Dimension for subplot rows. Default: None (aggregated).
+    animation_frame
+        Dimension for animation. Default: None (aggregated).
+    **px_kwargs
+        Additional arguments passed to `plotly.express.box()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "box",
+        allow_unassigned=True,
+        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", {})}
+
+    return px.box(
+        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"),
+        labels=labels,
+        **px_kwargs,
+    )
+
+
+def scatter(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    y: SlotValue | str = "value",
+    color: SlotValue = auto,
+    symbol: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    facet_row: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **px_kwargs: Any,
+) -> go.Figure:
+    """
+    Create an interactive scatter plot from a DataArray.
+
+    By default, y-axis shows DataArray values. Set y to a dimension name
+    for dimension-vs-dimension plots (e.g., lat vs lon colored by value).
+
+    Dimensions fill slots in order:
+    x -> color -> symbol -> facet_col -> facet_row -> animation_frame
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    x
+        Dimension for x-axis. Default: first dimension.
+    y
+        What to plot on y-axis. Default "value" uses DataArray values.
+        Can be a dimension name for dimension vs dimension plots.
+    color
+        Dimension for color grouping. Default: second dimension.
+        Use "value" to color by DataArray values (useful with y=dimension).
+    symbol
+        Dimension for marker symbol. Default: third dimension.
+    facet_col
+        Dimension for subplot columns. Default: fourth dimension.
+    facet_row
+        Dimension for subplot rows. Default: fifth dimension.
+    animation_frame
+        Dimension for animation. Default: sixth dimension.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.scatter()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    # If y is a dimension, exclude it from slot assignment
+    y_is_dim = y != "value" and y in darray.dims
+    dims_for_slots = [d for d in darray.dims if d != y] if y_is_dim else list(darray.dims)
+
+    slots = assign_slots(
+        dims_for_slots,
+        "scatter",
+        x=x,
+        color=color,
+        symbol=symbol,
+        facet_col=facet_col,
+        facet_row=facet_row,
+        animation_frame=animation_frame,
+    )
+
+    df = to_dataframe(darray)
+    value_col = get_value_col(darray)
+
+    # Resolve y and color columns (may be "value" -> actual column name)
+    y_col = value_col if y == "value" else y
+    color_col = value_col if slots.get("color") == "value" else slots.get("color")
+
+    # Build labels
+    labels = {**build_labels(darray, slots, value_col), **px_kwargs.pop("labels", {})}
+    if y_is_dim and str(y) not in labels:
+        labels[str(y)] = get_label(darray, y)
+
+    return px.scatter(
+        df,
+        x=slots.get("x"),
+        y=y_col,
+        color=color_col,
+        symbol=slots.get("symbol"),
+        facet_col=slots.get("facet_col"),
+        facet_row=slots.get("facet_row"),
+        animation_frame=slots.get("animation_frame"),
+        labels=labels,
+        **px_kwargs,
+    )
+
+
+def imshow(
+    darray: DataArray,
+    *,
+    x: SlotValue = auto,
+    y: SlotValue = auto,
+    facet_col: SlotValue = auto,
+    animation_frame: SlotValue = auto,
+    **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
+
+    Parameters
+    ----------
+    darray
+        The DataArray to plot.
+    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.
+    **px_kwargs
+        Additional arguments passed to `plotly.express.imshow()`.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    slots = assign_slots(
+        list(darray.dims),
+        "imshow",
+        y=y,
+        x=x,
+        facet_col=facet_col,
+        animation_frame=animation_frame,
+    )
+
+    # Transpose to: y (rows), x (cols), facet_col, animation_frame
+    transpose_order = [
+        slots[k] for k in ("y", "x", "facet_col", "animation_frame") if slots.get(k) is not None
+    ]
+    plot_data = darray.transpose(*transpose_order) if transpose_order else darray
+
+    return px.imshow(
+        plot_data,
+        facet_col=slots.get("facet_col"),
+        animation_frame=slots.get("animation_frame"),
+        **px_kwargs,
+    )

xarray_plotly-0.0.3.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: xarray_plotly
+Version: 0.0.3
+Summary: Interactive Plotly Express plotting accessor for xarray
+Author: Felix
+License: MIT
+Project-URL: Homepage, https://github.com/FBumann/xarray_plotly
+Project-URL: Documentation, https://fbumann.github.io/xarray_plotly
+Project-URL: Repository, https://github.com/FBumann/xarray_plotly
+Keywords: xarray,plotly,visualization,interactive,plotting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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==8.3.5; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: mypy==1.14.1; extra == "dev"
+Requires-Dist: ruff==0.9.2; extra == "dev"
+Requires-Dist: pre-commit==4.0.1; extra == "dev"
+Requires-Dist: nbstripout==0.8.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs==1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material==9.5.49; extra == "docs"
+Requires-Dist: mkdocstrings[python]==0.27.0; 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
+
+**Interactive Plotly Express plotting for xarray**
+
+[![PyPI version](https://badge.fury.io/py/xarray_plotly.svg)](https://badge.fury.io/py/xarray_plotly)
+[![Python](https://img.shields.io/pypi/pyversions/xarray_plotly.svg)](https://pypi.org/project/xarray_plotly/)
+[![CI](https://github.com/FBumann/xarray_plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/FBumann/xarray_plotly/actions)
+[![Docs](https://img.shields.io/badge/docs-fbumann.github.io-blue)](https://fbumann.github.io/xarray_plotly/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install xarray_plotly
+```
+
+## Quick Start
+
+```python
+import xarray as xr
+import numpy as np
+import xarray_plotly  # registers the accessor
+
+da = xr.DataArray(
+    np.random.randn(100, 3).cumsum(axis=0),
+    dims=["time", "city"],
+    coords={"time": np.arange(100), "city": ["NYC", "LA", "Chicago"]},
+)
+
+# Accessor style
+fig = da.plotly.line()
+fig.show()
+
+# Or with xpx() for IDE code completion
+from xarray_plotly import xpx
+fig = xpx(da).line()
+```
+
+**Why `xpx()`?** The accessor (`da.plotly`) works but IDEs can't provide code completion for it. This is because xarray accessors are registered dynamically at runtime, making them invisible to static type checkers. The `xpx()` function provides the same functionality with full IDE support. This limitation could only be solved by xarray itself, if at all — it may be a fundamental Python limitation.
+
+## Documentation
+
+Full documentation: [https://fbumann.github.io/xarray_plotly](https://fbumann.github.io/xarray_plotly)
+
+## License
+
+MIT

xarray_plotly-0.0.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+xarray_plotly/__init__.py,sha256=lmRFXU6azK9Il9mWH5qFP2I6QeYxq2-XvLuiJK0spVU,2244
+xarray_plotly/accessor.py,sha256=ekntB7TnOZEKEyXAt0F8pnFgdfmYcIbzPq0Nfyy3Xt0,9523
+xarray_plotly/common.py,sha256=YTiaPLJ0Gh20mHV8-72J8DjWk-XaSYaT_ZiqXp6cecU,7192
+xarray_plotly/config.py,sha256=oHHUd0vOOWJkAifyp7ShDJqklj1UXjeRwZijFAGdp1s,5597
+xarray_plotly/plotting.py,sha256=A8J3TIOtUhTGpyp8wk680wo3I8MVe0z_ZWnI67rkkbw,12393
+xarray_plotly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xarray_plotly-0.0.3.dist-info/licenses/LICENSE,sha256=AvVEfNqbhIm9jHvt0acJNjW1JUKa2a70Zb5rJdEXCJI,1064
+xarray_plotly-0.0.3.dist-info/METADATA,sha256=Uw5AyuxuLp7SWnwnbRnVBTbt8NcgkyulBmdgPJ0xJ88,3415
+xarray_plotly-0.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xarray_plotly-0.0.3.dist-info/top_level.txt,sha256=GtMkvuZvLAYTjYXtwoNUa0ag42CJARZJK1CZemYD7pg,14
+xarray_plotly-0.0.3.dist-info/RECORD,,

xarray_plotly-0.0.3.dist-info/WHEEL

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

xarray_plotly-0.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FBumann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xarray_plotly-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+xarray_plotly