xarray-plotly 0.0.4__tar.gz → 0.0.6__tar.gz

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/.github/workflows/ci.yml

@@ -40,3 +40,35 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: false
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build docs
+        run: uv run mkdocs build
+
+  ci-success:
+    name: CI Success
+    needs: [test, docs]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check all jobs passed
+        run: |
+          if [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "Test job failed or was cancelled"
+            exit 1
+          fi
+          if [[ "${{ needs.docs.result }}" != "success" ]]; then
+            echo "Docs job failed or was cancelled"
+            exit 1
+          fi
+          echo "All CI checks passed!"

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/.github/workflows/docs.yml

@@ -1,7 +1,7 @@
 name: Docs
 
 on:
-  push:
+  pull_request:
     branches: [main]
   release:
     types: [published]
@@ -26,6 +26,7 @@ jobs:
         run: uv run mkdocs build
 
       - name: Deploy to GitHub Pages
+        if: github.event_name == 'release'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.4
+Version: 0.0.6
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT
@@ -44,8 +44,8 @@ Dynamic: license-file
 
 **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/)
+[![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)

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/README.md

@@ -2,8 +2,8 @@
 
 **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/)
+[![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)

xarray_plotly-0.0.6/docs/examples/datasets.ipynb

@@ -0,0 +1,261 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Dataset Plotting\n",
+    "\n",
+    "Plot multiple variables from an xarray Dataset with automatic or custom slot assignment."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import xarray as xr\n",
+    "\n",
+    "from xarray_plotly import config, xpx\n",
+    "\n",
+    "config.notebook()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a Dataset with multiple variables\n",
+    "time = np.arange(50)\n",
+    "cities = [\"NYC\", \"LA\", \"Chicago\"]\n",
+    "\n",
+    "ds = xr.Dataset(\n",
+    "    {\n",
+    "        \"temperature\": ([\"time\", \"city\"], 20 + 5 * np.random.randn(50, 3).cumsum(axis=0) / 10),\n",
+    "        \"humidity\": ([\"time\", \"city\"], 50 + 10 * np.random.randn(50, 3).cumsum(axis=0) / 10),\n",
+    "        \"pressure\": ([\"time\", \"city\"], 1013 + np.random.randn(50, 3).cumsum(axis=0)),\n",
+    "    },\n",
+    "    coords={\"time\": time, \"city\": cities},\n",
+    ")\n",
+    "ds"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot All Variables\n",
+    "\n",
+    "When you call a plot method on a Dataset without specifying `var`, all variables are combined into a single DataArray with a new `\"variable\"` dimension:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# All variables: time -> x, variable -> color, city -> line_dash\n",
+    "xpx(ds).line()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Control Where \"variable\" Goes\n",
+    "\n",
+    "The `\"variable\"` dimension can be assigned to any slot:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Variables as facet columns\n",
+    "xpx(ds).line(facet_col=\"variable\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Variables as rows, cities as columns\n",
+    "xpx(ds).line(facet_row=\"variable\", facet_col=\"city\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Configure Default \"variable\" Position\n",
+    "\n",
+    "By default, `\"variable\"` is placed as the **second** dimension so it maps to `color`. This keeps your first dimension (e.g., time) on the x-axis.\n",
+    "\n",
+    "You can change this globally with `config.set_options()`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Default: position=1 (second) -> variable goes to color\n",
+    "# Note: to_array() puts \"variable\" first, but xpx() reorders it to position 1\n",
+    "print(\"Raw to_array() dims:\", ds.to_array().dims)  # (variable, time, city)\n",
+    "print(\"After xpx reorder:   (time, variable, city)\")  # time->x, variable->color\n",
+    "xpx(ds).line(title=\"Default: variable as color (position=1)\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Position 0: variable goes first (x-axis) - usually not what you want!\n",
+    "with config.set_options(dataset_variable_position=0):\n",
+    "    fig = xpx(ds).line(title=\"position=0: variable on x-axis (probably not desired)\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Position -1: variable goes last -> city gets color, variable gets line_dash\n",
+    "with config.set_options(dataset_variable_position=-1):\n",
+    "    fig = xpx(ds).line(title=\"position=-1: variable as line_dash\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot a Single Variable\n",
+    "\n",
+    "Use `var=\"name\"` to plot just one variable:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xpx(ds).line(var=\"temperature\", title=\"Temperature Only\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Different Plot Types"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Bar chart - latest values by city\n",
+    "xpx(ds.isel(time=-1)).bar(x=\"city\", color=\"variable\", barmode=\"group\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Box plot - distribution by variable\n",
+    "xpx(ds).box(x=\"variable\", color=\"city\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Area chart\n",
+    "xpx(ds).area(var=\"humidity\", title=\"Humidity Over Time\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Scatter\n",
+    "xpx(ds).scatter(var=\"temperature\", title=\"Temperature Scatter\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Pie chart - snapshot at one time\n",
+    "xpx(ds.isel(time=-1)).pie(var=\"temperature\", names=\"city\", title=\"Temperature Distribution\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Combining Slot Assignments\n",
+    "\n",
+    "Mix explicit assignments with auto-assignment:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Explicit: variable -> facet_col, let city auto-assign to color\n",
+    "xpx(ds).line(facet_col=\"variable\", color=\"city\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Skip color slot with None\n",
+    "xpx(ds).line(var=\"temperature\", color=None)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/mkdocs.yml

@@ -69,6 +69,7 @@ nav:
   - Getting Started: getting-started.ipynb
   - Examples:
       - Plot Types: examples/plot-types.ipynb
+      - Dataset Plotting: examples/datasets.ipynb
       - Dimensions & Facets: examples/dimensions.ipynb
       - Plotly Express Options: examples/kwargs.ipynb
       - Figure Customization: examples/figure.ipynb

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/tests/test_accessor.py

@@ -292,3 +292,52 @@ class TestDatasetPlotlyAccessor:
         """Test box plot with all variables."""
         fig = self.ds.plotly.box()
         assert isinstance(fig, go.Figure)
+
+
+class TestImshowBounds:
+    """Tests for imshow global bounds and robust mode."""
+
+    def test_imshow_global_bounds(self) -> None:
+        """Test that imshow uses global min/max by default."""
+        da = xr.DataArray(
+            np.array([[[1, 2], [3, 4]], [[5, 6], [7, 100]]]),
+            dims=["time", "y", "x"],
+        )
+        fig = da.plotly.imshow(animation_frame="time")
+        # Check coloraxis for zmin/zmax (plotly stores them there)
+        coloraxis = fig.layout.coloraxis
+        assert coloraxis.cmin == 1.0
+        assert coloraxis.cmax == 100.0
+
+    def test_imshow_robust_bounds(self) -> None:
+        """Test that robust=True uses percentile-based bounds."""
+        # Create data with outlier
+        data = np.random.rand(10, 20) * 100
+        data[0, 0] = 10000  # extreme outlier
+        da = xr.DataArray(data, dims=["y", "x"])
+
+        fig = da.plotly.imshow(robust=True)
+        # With robust=True, cmax should be much less than the outlier
+        coloraxis = fig.layout.coloraxis
+        assert coloraxis.cmax < 10000
+        assert coloraxis.cmax < 200  # Should be around 98th percentile (~98)
+
+    def test_imshow_user_zmin_zmax_override(self) -> None:
+        """Test that user-provided zmin/zmax overrides auto bounds."""
+        da = xr.DataArray(np.random.rand(10, 20) * 100, dims=["y", "x"])
+        fig = da.plotly.imshow(zmin=0, zmax=50)
+        coloraxis = fig.layout.coloraxis
+        assert coloraxis.cmin == 0
+        assert coloraxis.cmax == 50
+
+    def test_imshow_animation_consistent_bounds(self) -> None:
+        """Test that animation frames have consistent color bounds."""
+        da = xr.DataArray(
+            np.array([[[0, 10], [20, 30]], [[40, 50], [60, 70]]]),
+            dims=["time", "y", "x"],
+        )
+        fig = da.plotly.imshow(animation_frame="time")
+        # All frames should use global min (0) and max (70)
+        coloraxis = fig.layout.coloraxis
+        assert coloraxis.cmin == 0.0
+        assert coloraxis.cmax == 70.0

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/xarray_plotly/accessor.py

@@ -7,6 +7,7 @@ from xarray import DataArray, Dataset
 
 from xarray_plotly import plotting
 from xarray_plotly.common import SlotValue, auto
+from xarray_plotly.config import _options
 
 
 class DataArrayPlotlyAccessor:
@@ -249,6 +250,7 @@ class DataArrayPlotlyAccessor:
         y: SlotValue = auto,
         facet_col: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        robust: bool = False,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive heatmap image.
@@ -260,7 +262,9 @@ class DataArrayPlotlyAccessor:
             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.
+            robust: If True, use 2nd/98th percentiles for color bounds (handles outliers).
             **px_kwargs: Additional arguments passed to `plotly.express.imshow()`.
+                Use `zmin` and `zmax` to manually set color scale bounds.
 
         Returns:
             Interactive Plotly Figure.
@@ -271,6 +275,7 @@ class DataArrayPlotlyAccessor:
             y=y,
             facet_col=facet_col,
             animation_frame=animation_frame,
+            robust=robust,
             **px_kwargs,
         )
 
@@ -349,9 +354,26 @@ class DatasetPlotlyAccessor:
         return list(self.__all__) + list(super().__dir__())
 
     def _get_dataarray(self, var: str | None) -> DataArray:
-        """Get DataArray from Dataset, either single var or all via to_array()."""
+        """Get DataArray from Dataset, either single var or all via to_array().
+
+        When combining all variables, "variable" is placed at the position
+        specified by config.dataset_variable_position (default 1, second position).
+        Supports Python-style negative indexing: -1 = last, -2 = second-to-last, etc.
+        """
         if var is None:
-            return self._ds.to_array(dim="variable")
+            da = self._ds.to_array(dim="variable")
+            pos = _options.dataset_variable_position
+            # Move "variable" to configured position
+            if len(da.dims) > 1 and pos != 0:
+                dims = list(da.dims)
+                dims.remove("variable")
+                # Use Python-style indexing (handles negative indices correctly)
+                # Clamp to valid range: -1 -> last, -2 -> second-to-last, etc.
+                n = len(dims)
+                insert_pos = max(0, n + pos + 1) if pos < 0 else min(pos, n)
+                dims.insert(insert_pos, "variable")
+                da = da.transpose(*dims)
+            return da
         return self._ds[var]
 
     def line(

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/xarray_plotly/config.py

@@ -58,6 +58,9 @@ class Options:
         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.
+        dataset_variable_position: Position of "variable" dim when plotting all Dataset
+            variables. Default 1 (second position, typically color). Set to 0 for first
+            position (x-axis), or -1 for last position.
     """
 
     label_use_long_name: bool = True
@@ -67,6 +70,7 @@ class Options:
     slot_orders: dict[str, tuple[str, ...]] = field(
         default_factory=lambda: dict(DEFAULT_SLOT_ORDERS)
     )
+    dataset_variable_position: int = 1
 
     def to_dict(self) -> dict[str, Any]:
         """Return options as a dictionary."""
@@ -76,6 +80,7 @@ class Options:
             "label_include_units": self.label_include_units,
             "label_unit_format": self.label_unit_format,
             "slot_orders": self.slot_orders,
+            "dataset_variable_position": self.dataset_variable_position,
         }
 
 
@@ -106,6 +111,7 @@ def set_options(
     label_include_units: bool | None = None,
     label_unit_format: str | None = None,
     slot_orders: dict[str, tuple[str, ...]] | None = None,
+    dataset_variable_position: int | None = None,
 ) -> Generator[None, None, None]:
     """Set xarray_plotly options globally or as a context manager.
 
@@ -115,6 +121,8 @@ def set_options(
         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.
+        dataset_variable_position: Position of "variable" dim when plotting all Dataset
+            variables. Default 1 (second, typically color). Use 0 for first, -1 for last.
 
     Yields:
         None when used as a context manager.
@@ -136,6 +144,7 @@ def set_options(
         "label_include_units": _options.label_include_units,
         "label_unit_format": _options.label_unit_format,
         "slot_orders": dict(_options.slot_orders),
+        "dataset_variable_position": _options.dataset_variable_position,
     }
 
     # Apply new values (modify in place to keep reference)
@@ -149,6 +158,8 @@ def set_options(
         _options.label_unit_format = label_unit_format
     if slot_orders is not None:
         _options.slot_orders = dict(slot_orders)
+    if dataset_variable_position is not None:
+        _options.dataset_variable_position = dataset_variable_position
 
     try:
         yield
@@ -159,6 +170,7 @@ def set_options(
         _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"]
+        _options.dataset_variable_position = old_values["dataset_variable_position"]
 
 
 def notebook(renderer: str = "notebook") -> None:

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/xarray_plotly/plotting.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+import numpy as np
 import plotly.express as px
 
 from xarray_plotly.common import (
@@ -398,6 +399,7 @@ def imshow(
     y: SlotValue = auto,
     facet_col: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    robust: bool = False,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -418,8 +420,12 @@ def imshow(
         Dimension for subplot columns. Default: third dimension.
     animation_frame
         Dimension for animation. Default: fourth dimension.
+    robust
+        If True, compute color bounds using 2nd and 98th percentiles
+        for robustness against outliers. Default: False.
     **px_kwargs
         Additional arguments passed to `plotly.express.imshow()`.
+        Use `zmin` and `zmax` to manually set color scale bounds.
 
     Returns
     -------
@@ -440,6 +446,20 @@ def imshow(
     ]
     plot_data = darray.transpose(*transpose_order) if transpose_order else darray
 
+    # Compute global color bounds if not provided
+    if "zmin" not in px_kwargs or "zmax" not in px_kwargs:
+        values = plot_data.values
+        if robust:
+            # Use percentiles for outlier robustness
+            zmin = float(np.nanpercentile(values, 2))
+            zmax = float(np.nanpercentile(values, 98))
+        else:
+            # Use global min/max across all data
+            zmin = float(np.nanmin(values))
+            zmax = float(np.nanmax(values))
+        px_kwargs.setdefault("zmin", zmin)
+        px_kwargs.setdefault("zmax", zmax)
+
     return px.imshow(
         plot_data,
         facet_col=slots.get("facet_col"),

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/xarray_plotly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.4
+Version: 0.0.6
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT
@@ -44,8 +44,8 @@ Dynamic: license-file
 
 **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/)
+[![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)

{xarray_plotly-0.0.4 → xarray_plotly-0.0.6}/xarray_plotly.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ pyproject.toml
 docs/api.md
 docs/getting-started.ipynb
 docs/index.md
+docs/examples/datasets.ipynb
 docs/examples/dimensions.ipynb
 docs/examples/figure.ipynb
 docs/examples/kwargs.ipynb