xarray-plotly 0.0.1__py3-none-any.whl

xarray_plotly/config.py

@@ -0,0 +1,203 @@
+"""
+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 : bool
+        Use `long_name` attribute for labels. Default True.
+    label_use_standard_name : bool
+        Fall back to `standard_name` if `long_name` not available. Default True.
+    label_include_units : bool
+        Append units to labels. Default True.
+    label_unit_format : str
+        Format string for units. Use `{units}` as placeholder. Default "[{units}]".
+    slot_orders : dict
+        Slot orders per plot type. Keys are plot types, values are tuples of slot names.
+    """
+
+    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
+    -------
+    dict
+        Dictionary of current option values.
+
+    Examples
+    --------
+    >>> from xarray_plotly import config
+    >>> config.get_options()
+    {'label_use_long_name': True, 'label_include_units': True, ...}
+    """
+    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.
+
+    Parameters
+    ----------
+    label_use_long_name : bool, optional
+        Use `long_name` attribute for labels.
+    label_use_standard_name : bool, optional
+        Fall back to `standard_name` if `long_name` not available.
+    label_include_units : bool, optional
+        Append units to labels.
+    label_unit_format : str, optional
+        Format string for units. Use `{units}` as placeholder.
+    slot_orders : dict, optional
+        Slot orders per plot type.
+
+    Yields
+    ------
+    None
+        When used as a context manager, yields nothing.
+
+    Examples
+    --------
+    Set globally:
+
+    >>> from xarray_plotly import config
+    >>> config.set_options(label_include_units=False)
+
+    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.
+
+    Parameters
+    ----------
+    renderer : str, optional
+        The Plotly renderer to use. Default is "notebook".
+        Other options include "jupyterlab", "colab", "kaggle", etc.
+
+    Examples
+    --------
+    >>> 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,
+    )