xarray-plotly 0.0.1__py3-none-any.whl

xarray_plotly/__init__.py

@@ -0,0 +1,73 @@
+"""
+xarray_plotly: Interactive Plotly Express plotting for xarray.
+
+This package provides interactive plotting for xarray DataArray objects
+using Plotly Express.
+
+Examples
+--------
+>>> 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"],
+... )
+
+>>> # Auto-assignment: time->x, city->color, scenario->facet_col
+>>> fig = xpx(da).line()
+
+>>> # Explicit assignment
+>>> fig = xpx(da).line(x="time", color="scenario", facet_col="city")
+
+>>> # Skip a slot
+>>> fig = xpx(da).line(color=None)  # time->x, city->facet_col, scenario->facet_row
+"""
+
+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.
+
+    Parameters
+    ----------
+    da : DataArray
+        The DataArray to plot.
+
+    Returns
+    -------
+    DataArrayPlotlyAccessor
+        The accessor with plotting methods.
+
+    Examples
+    --------
+    >>> 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,336 @@
+"""
+Accessor classes for Plotly Express plotting on DataArray and Dataset.
+"""
+
+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:
+    """
+    Enables use of Plotly Express plotting functions on a DataArray.
+
+    Methods return Plotly Figure objects for interactive visualization.
+
+    Examples
+    --------
+    >>> import xarray as xr
+    >>> import numpy as np
+    >>> da = xr.DataArray(np.random.rand(10, 3), dims=["time", "city"])
+    >>> fig = da.plotly.line()  # Auto-assign dims: time->x, city->color
+    >>> fig.show()
+
+    >>> fig = da.plotly.line(x="time", color=None)  # Explicit assignment
+    >>> fig.update_layout(title="My Plot")
+    """
+
+    __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 using Plotly Express.
+
+        The y-axis always shows the DataArray values. Dimensions are assigned
+        to other slots by their order:
+        x -> color -> line_dash -> symbol -> facet_col -> facet_row -> animation_frame
+
+        Parameters
+        ----------
+        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
+        """
+        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 using Plotly Express.
+
+        The y-axis always shows the DataArray values. Dimensions are assigned
+        to other slots by their order:
+        x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+        Parameters
+        ----------
+        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
+        """
+        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 using Plotly Express.
+
+        The y-axis always shows the DataArray values. Dimensions are assigned
+        to other slots by their order:
+        x -> color -> pattern_shape -> facet_col -> facet_row -> animation_frame
+
+        Parameters
+        ----------
+        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
+        """
+        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 using Plotly Express.
+
+        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 colored
+        by value).
+
+        Parameters
+        ----------
+        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
+        """
+        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 using Plotly Express.
+
+        The y-axis always shows the DataArray values. By default, only the
+        first dimension is assigned to x; all other dimensions are aggregated
+        into the box statistics.
+
+        Parameters
+        ----------
+        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
+        """
+        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 using Plotly Express.
+
+        Dimensions are assigned to plot slots by their order:
+        y (rows) -> x (columns) -> facet_col -> animation_frame
+
+        Parameters
+        ----------
+        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
+        """
+        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,247 @@
+"""
+Common utilities for Plotly Express plotting.
+
+This module provides the dimension-to-slot assignment algorithm and
+shared utilities for converting xarray data to Plotly-compatible formats.
+"""
+
+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 `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)
+
+    Parameters
+    ----------
+    dims
+        Dimension names.
+    plot_type
+        Type of plot (line, bar, area, scatter, box, imshow).
+    allow_unassigned
+        If True, allow dimensions to remain unassigned. Default False.
+    **slot_kwargs
+        Explicit slot assignments. Use `auto` for positional assignment,
+        a dimension name for explicit assignment, or `None` to skip the slot.
+
+    Returns
+    -------
+    dict
+        Mapping of slot names to dimension names.
+
+    Raises
+    ------
+    ValueError
+        If plot_type is unknown, a dimension doesn't exist, or dimensions
+        are left unassigned (unless allow_unassigned=True).
+    """
+    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.
+
+    Parameters
+    ----------
+    attrs
+        Attributes dictionary from DataArray or coordinate.
+    fallback
+        Fallback label if no attributes match.
+
+    Returns
+    -------
+    str
+        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 `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.
+
+    Parameters
+    ----------
+    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
+    -------
+    dict
+        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