xarray-plotly 0.0.1__tar.gz → 0.0.2__tar.gz

xarray_plotly-0.0.2/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: xarray_plotly
+Version: 0.0.2
+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>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: nbstripout>=0.6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
+Requires-Dist: mkdocs-plotly-plugin>=0.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/)
+[![Docs](https://img.shields.io/badge/docs-fbumann.github.io-blue)](https://fbumann.github.io/xarray_plotly/)
+
+## 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()
+```
+
+## Documentation
+
+Full documentation: [https://fbumann.github.io/xarray_plotly](https://fbumann.github.io/xarray_plotly)
+
+## License
+
+MIT

xarray_plotly-0.0.2/README.md

@@ -0,0 +1,43 @@
+# 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/)
+[![Docs](https://img.shields.io/badge/docs-fbumann.github.io-blue)](https://fbumann.github.io/xarray_plotly/)
+
+## 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()
+```
+
+## Documentation
+
+Full documentation: [https://fbumann.github.io/xarray_plotly](https://fbumann.github.io/xarray_plotly)
+
+## License
+
+MIT

xarray_plotly-0.0.2/docs/api.md

@@ -0,0 +1,28 @@
+# API Reference
+
+::: xarray_plotly.xpx
+
+::: xarray_plotly.accessor.DataArrayPlotlyAccessor
+    options:
+      members:
+        - line
+        - bar
+        - area
+        - scatter
+        - box
+        - imshow
+
+::: xarray_plotly.config
+    options:
+      members:
+        - notebook
+        - get_options
+        - set_options
+        - Options
+
+::: xarray_plotly.common
+    options:
+      members:
+        - auto
+        - SLOT_ORDERS
+        - assign_slots

{xarray_plotly-0.0.1 → xarray_plotly-0.0.2}/docs/getting-started.ipynb

@@ -80,7 +80,7 @@
     "    attrs={\"long_name\": \"Temperature Anomaly\", \"units\": \"°C\"},\n",
     ")\n",
     "\n",
-    "da"
+    "da.to_dataframe()"
    ]
   },
   {

xarray_plotly-0.0.2/docs/index.md

@@ -0,0 +1,11 @@
+::: xarray_plotly
+    options:
+      show_root_heading: true
+      members: false
+
+## Next Steps
+
+- [Getting Started](getting-started.ipynb) - Interactive tutorial
+- [Plot Types](examples/plot-types.ipynb) - All available plot types
+- [Advanced Usage](examples/advanced.ipynb) - Configuration and customization
+- [API Reference](api.md) - Full API documentation

{xarray_plotly-0.0.1 → xarray_plotly-0.0.2}/mkdocs.yml

@@ -42,7 +42,7 @@ plugins:
       handlers:
         python:
           options:
-            docstring_style: numpy
+            docstring_style: google
             show_source: true
             show_root_heading: true
             members_order: source

xarray_plotly-0.0.2/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-0.0.2/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,
+        )