xarray-plotly 0.0.11__tar.gz → 0.0.12__tar.gz

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/.github/workflows/ci.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Format check
         run: uv run ruff format --check .
 
+      - name: Type check
+        run: uv run mypy xarray_plotly
+
       - name: Test
         run: uv run pytest --cov=xarray_plotly --cov-report=xml
 

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.11
+Version: 0.0.12
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/docs/examples/kwargs.ipynb

@@ -159,6 +159,71 @@
     "xpx(change).imshow(color_continuous_scale=\"RdBu_r\", color_continuous_midpoint=0)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## colors (unified parameter)\n",
+    "\n",
+    "The `colors` parameter provides a simpler way to set colors without remembering the exact Plotly parameter name. It automatically maps to the correct parameter based on the input type:\n",
+    "\n",
+    "| Input | Maps To |\n",
+    "|-------|---------|\n",
+    "| `\"Viridis\"` (continuous scale name) | `color_continuous_scale` |\n",
+    "| `\"D3\"` (qualitative palette name) | `color_discrete_sequence` |\n",
+    "| `[\"red\", \"blue\"]` (list) | `color_discrete_sequence` |\n",
+    "| `{\"A\": \"red\"}` (dict) | `color_discrete_map` |"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Named qualitative palette\n",
+    "xpx(stocks).line(colors=\"D3\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# List of custom colors\n",
+    "xpx(stocks).line(colors=[\"#E63946\", \"#457B9D\", \"#2A9D8F\", \"#E9C46A\", \"#F4A261\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Dict for explicit mapping\n",
+    "xpx(stocks).line(\n",
+    "    colors={\n",
+    "        \"GOOG\": \"red\",\n",
+    "        \"AAPL\": \"blue\",\n",
+    "        \"AMZN\": \"green\",\n",
+    "        \"FB\": \"purple\",\n",
+    "        \"NFLX\": \"orange\",\n",
+    "        \"MSFT\": \"brown\",\n",
+    "    }\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Continuous scale for heatmaps\n",
+    "xpx(stocks).imshow(colors=\"Plasma\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/tests/test_accessor.py

@@ -401,3 +401,128 @@ class TestImshowBounds:
         coloraxis = fig.layout.coloraxis
         assert coloraxis.cmin == 0.0
         assert coloraxis.cmax == 70.0
+
+
+class TestColorsParameter:
+    """Tests for the unified colors parameter."""
+
+    @pytest.fixture(autouse=True)
+    def setup(self) -> None:
+        """Create test DataArrays."""
+        self.da = xr.DataArray(
+            np.random.rand(10, 3),
+            dims=["time", "city"],
+            coords={"city": ["A", "B", "C"]},
+        )
+
+    def test_colors_list_sets_discrete_sequence(self) -> None:
+        """Test that a list of colors sets color_discrete_sequence."""
+        fig = self.da.plotly.line(colors=["red", "blue", "green"])
+        # Check that traces have the expected colors
+        assert len(fig.data) == 3
+        assert fig.data[0].line.color == "red"
+        assert fig.data[1].line.color == "blue"
+        assert fig.data[2].line.color == "green"
+
+    def test_colors_dict_sets_discrete_map(self) -> None:
+        """Test that a dict sets color_discrete_map."""
+        fig = self.da.plotly.line(colors={"A": "red", "B": "blue", "C": "green"})
+        # Traces should be colored according to the mapping
+        assert len(fig.data) == 3
+        # Find traces by name and check their color
+        colors_by_name = {trace.name: trace.line.color for trace in fig.data}
+        assert colors_by_name["A"] == "red"
+        assert colors_by_name["B"] == "blue"
+        assert colors_by_name["C"] == "green"
+
+    def test_colors_continuous_scale_string(self) -> None:
+        """Test that a continuous scale name sets color_continuous_scale."""
+        da = xr.DataArray(
+            np.random.rand(50, 2),
+            dims=["point", "coord"],
+            coords={"coord": ["x", "y"]},
+        )
+        fig = da.plotly.scatter(y="coord", x="point", color="value", colors="Viridis")
+        # Plotly Express uses coloraxis in the layout for continuous scales
+        # Check that the colorscale was applied to the coloraxis
+        assert fig.layout.coloraxis.colorscale is not None
+        colorscale = fig.layout.coloraxis.colorscale
+        # Viridis should be in the colorscale definition
+        assert any("viridis" in str(c).lower() for c in colorscale) or len(colorscale) > 0
+
+    def test_colors_qualitative_palette_string(self) -> None:
+        """Test that a qualitative palette name sets color_discrete_sequence."""
+        import plotly.express as px
+
+        fig = self.da.plotly.line(colors="D3")
+        # D3 palette should be applied - check first trace color is from D3
+        d3_colors = px.colors.qualitative.D3
+        assert fig.data[0].line.color in d3_colors
+
+    def test_colors_ignored_with_warning_when_px_kwargs_present(self) -> None:
+        """Test that colors is ignored with warning when color_* kwargs are present."""
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            fig = self.da.plotly.line(
+                colors="D3", color_discrete_sequence=["orange", "purple", "cyan"]
+            )
+            # Should have raised a warning about colors being ignored
+            assert any(
+                "colors" in str(m.message).lower() and "ignored" in str(m.message).lower()
+                for m in w
+            ), "Expected warning about 'colors' being 'ignored' not found"
+            # The explicit px_kwargs should take precedence
+            assert fig.data[0].line.color == "orange"
+
+    def test_colors_none_uses_defaults(self) -> None:
+        """Test that colors=None uses Plotly defaults."""
+        fig1 = self.da.plotly.line(colors=None)
+        fig2 = self.da.plotly.line()
+        # Both should produce the same result
+        assert fig1.data[0].line.color == fig2.data[0].line.color
+
+    def test_colors_works_with_bar(self) -> None:
+        """Test colors parameter with bar chart."""
+        fig = self.da.plotly.bar(colors=["#e41a1c", "#377eb8", "#4daf4a"])
+        assert fig.data[0].marker.color == "#e41a1c"
+
+    def test_colors_works_with_area(self) -> None:
+        """Test colors parameter with area chart."""
+        fig = self.da.plotly.area(colors=["red", "green", "blue"])
+        assert len(fig.data) == 3
+
+    def test_colors_works_with_scatter(self) -> None:
+        """Test colors parameter with scatter plot."""
+        fig = self.da.plotly.scatter(colors=["red", "green", "blue"])
+        assert len(fig.data) == 3
+
+    def test_colors_works_with_imshow(self) -> None:
+        """Test colors parameter with imshow (continuous scale)."""
+        da = xr.DataArray(np.random.rand(10, 10), dims=["y", "x"])
+        fig = da.plotly.imshow(colors="RdBu")
+        # Plotly Express uses coloraxis in the layout for continuous scales
+        assert fig.layout.coloraxis.colorscale is not None
+        colorscale = fig.layout.coloraxis.colorscale
+        # RdBu should be in the colorscale definition
+        assert any("rdbu" in str(c).lower() for c in colorscale) or len(colorscale) > 0
+
+    def test_colors_works_with_pie(self) -> None:
+        """Test colors parameter with pie chart."""
+        da = xr.DataArray([30, 40, 30], dims=["category"], coords={"category": ["A", "B", "C"]})
+        fig = da.plotly.pie(colors={"A": "red", "B": "blue", "C": "green"})
+        assert isinstance(fig, go.Figure)
+
+    def test_colors_works_with_dataset(self) -> None:
+        """Test colors parameter works with Dataset accessor."""
+        ds = xr.Dataset(
+            {
+                "temp": (["time"], np.random.rand(10)),
+                "precip": (["time"], np.random.rand(10)),
+            }
+        )
+        fig = ds.plotly.line(colors=["red", "blue"])
+        assert len(fig.data) == 2
+        assert fig.data[0].line.color == "red"
+        assert fig.data[1].line.color == "blue"

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/__init__.py

@@ -52,7 +52,7 @@ from xarray import DataArray, Dataset, register_dataarray_accessor, register_dat
 
 from xarray_plotly import config
 from xarray_plotly.accessor import DataArrayPlotlyAccessor, DatasetPlotlyAccessor
-from xarray_plotly.common import SLOT_ORDERS, auto
+from xarray_plotly.common import SLOT_ORDERS, Colors, auto
 from xarray_plotly.figures import (
     add_secondary_y,
     overlay,
@@ -61,6 +61,7 @@ from xarray_plotly.figures import (
 
 __all__ = [
     "SLOT_ORDERS",
+    "Colors",
     "add_secondary_y",
     "auto",
     "config",
@@ -110,5 +111,5 @@ def xpx(data: DataArray | Dataset) -> DataArrayPlotlyAccessor | DatasetPlotlyAcc
 __version__ = version("xarray_plotly")
 
 # Register the accessors
-register_dataarray_accessor("plotly")(DataArrayPlotlyAccessor)
-register_dataset_accessor("plotly")(DatasetPlotlyAccessor)
+register_dataarray_accessor("plotly")(DataArrayPlotlyAccessor)  # type: ignore[no-untyped-call]
+register_dataset_accessor("plotly")(DatasetPlotlyAccessor)  # type: ignore[no-untyped-call]

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/accessor.py

@@ -6,7 +6,7 @@ import plotly.graph_objects as go
 from xarray import DataArray, Dataset
 
 from xarray_plotly import plotting
-from xarray_plotly.common import SlotValue, auto
+from xarray_plotly.common import Colors, SlotValue, auto
 from xarray_plotly.config import _options
 
 
@@ -53,6 +53,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -67,6 +68,7 @@ class DataArrayPlotlyAccessor:
             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.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.line()`.
 
         Returns:
@@ -81,6 +83,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -93,6 +96,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -106,6 +110,7 @@ class DataArrayPlotlyAccessor:
             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.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.bar()`.
 
         Returns:
@@ -119,6 +124,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -131,6 +137,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -144,6 +151,7 @@ class DataArrayPlotlyAccessor:
             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.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -157,6 +165,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -168,6 +177,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -180,6 +190,7 @@ class DataArrayPlotlyAccessor:
             facet_col: Dimension for subplot columns. Default: third dimension.
             facet_row: Dimension for subplot rows. Default: fourth dimension.
             animation_frame: Dimension for animation. Default: fifth dimension.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -192,6 +203,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -205,6 +217,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -223,6 +236,7 @@ class DataArrayPlotlyAccessor:
             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.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.scatter()`.
 
         Returns:
@@ -237,6 +251,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -248,6 +263,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = None,
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -263,6 +279,7 @@ class DataArrayPlotlyAccessor:
             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).
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.box()`.
 
         Returns:
@@ -275,6 +292,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -286,6 +304,7 @@ class DataArrayPlotlyAccessor:
         facet_col: SlotValue = auto,
         animation_frame: SlotValue = auto,
         robust: bool = False,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive heatmap image.
@@ -303,6 +322,7 @@ class DataArrayPlotlyAccessor:
             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).
+            colors: Color scale name (e.g., "Viridis", "RdBu"). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.imshow()`.
                 Use `zmin` and `zmax` to manually set color scale bounds.
 
@@ -316,6 +336,7 @@ class DataArrayPlotlyAccessor:
             facet_col=facet_col,
             animation_frame=animation_frame,
             robust=robust,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -326,6 +347,7 @@ class DataArrayPlotlyAccessor:
         color: SlotValue = None,
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -337,6 +359,7 @@ class DataArrayPlotlyAccessor:
             color: Dimension for color grouping. Default: None (uses names).
             facet_col: Dimension for subplot columns. Default: second dimension.
             facet_row: Dimension for subplot rows. Default: third dimension.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.pie()`.
 
         Returns:
@@ -348,6 +371,7 @@ class DataArrayPlotlyAccessor:
             color=color,
             facet_col=facet_col,
             facet_row=facet_row,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -427,6 +451,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive line plot.
@@ -440,6 +465,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.line()`.
 
         Returns:
@@ -455,6 +481,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -468,6 +495,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive bar chart.
@@ -480,6 +508,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.bar()`.
 
         Returns:
@@ -494,6 +523,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -507,6 +537,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive stacked area chart.
@@ -519,6 +550,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -533,6 +565,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -545,6 +578,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create a bar-like chart using stacked areas for better performance.
@@ -556,6 +590,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.area()`.
 
         Returns:
@@ -569,6 +604,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -583,6 +619,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
         animation_frame: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive scatter plot.
@@ -596,6 +633,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.scatter()`.
 
         Returns:
@@ -611,6 +649,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -623,6 +662,7 @@ class DatasetPlotlyAccessor:
         facet_col: SlotValue = None,
         facet_row: SlotValue = None,
         animation_frame: SlotValue = None,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive box plot.
@@ -634,6 +674,7 @@ class DatasetPlotlyAccessor:
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
             animation_frame: Dimension for animation.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.box()`.
 
         Returns:
@@ -647,6 +688,7 @@ class DatasetPlotlyAccessor:
             facet_col=facet_col,
             facet_row=facet_row,
             animation_frame=animation_frame,
+            colors=colors,
             **px_kwargs,
         )
 
@@ -658,6 +700,7 @@ class DatasetPlotlyAccessor:
         color: SlotValue = None,
         facet_col: SlotValue = auto,
         facet_row: SlotValue = auto,
+        colors: Colors = None,
         **px_kwargs: Any,
     ) -> go.Figure:
         """Create an interactive pie chart.
@@ -668,6 +711,7 @@ class DatasetPlotlyAccessor:
             color: Dimension for color grouping.
             facet_col: Dimension for subplot columns.
             facet_row: Dimension for subplot rows.
+            colors: Color specification (scale name, list, or dict). See module docs.
             **px_kwargs: Additional arguments passed to `plotly.express.pie()`.
 
         Returns:
@@ -680,5 +724,6 @@ class DatasetPlotlyAccessor:
             color=color,
             facet_col=facet_col,
             facet_row=facet_row,
+            colors=colors,
             **px_kwargs,
         )

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/common.py

@@ -2,13 +2,16 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import functools
+import warnings
+from collections.abc import Hashable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+import plotly.express as px
 
 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
 
@@ -27,6 +30,15 @@ auto = _AUTO()
 SlotValue = _AUTO | str | None
 """Type alias for slot values: auto, explicit dimension name, or None (skip)."""
 
+Colors = str | Sequence[str] | Mapping[str, str] | None
+"""Type alias for unified colors parameter.
+
+- str: Named color scale (e.g., "Viridis" for continuous, "D3" for discrete)
+- Sequence[str]: List of colors for discrete sequence (e.g., ["red", "blue"])
+- Mapping[str, str]: Explicit mapping of values to colors (e.g., {"A": "red"})
+- None: Use Plotly defaults
+"""
+
 # Re-export for backward compatibility
 SLOT_ORDERS = DEFAULT_SLOT_ORDERS
 """Slot orders per plot type.
@@ -147,7 +159,7 @@ def to_dataframe(darray: DataArray) -> pd.DataFrame:
     return df
 
 
-def _get_label_from_attrs(attrs: dict, fallback: str) -> str:
+def _get_label_from_attrs(attrs: dict[str, object], fallback: str) -> str:
     """Extract a label from xarray attributes based on current config.
 
     Args:
@@ -227,3 +239,60 @@ def build_labels(
         labels[value_col] = get_label(darray, "value")
 
     return labels
+
+
+@functools.cache
+def _get_qualitative_scale_names() -> frozenset[str]:
+    """Get all named qualitative (discrete) color scales from Plotly."""
+    return frozenset(
+        name
+        for name in dir(px.colors.qualitative)
+        if not name.startswith("_") and name[0].isupper()
+    )
+
+
+def resolve_colors(colors: Colors, px_kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Map unified `colors` parameter to appropriate Plotly px_kwargs.
+
+    Direct color_* kwargs take precedence and trigger a warning if
+    colors was also specified.
+
+    Args:
+        colors: Unified color specification (str, list, dict, or None).
+        px_kwargs: Existing kwargs to pass to Plotly Express.
+
+    Returns:
+        Updated px_kwargs with color parameters injected.
+    """
+    if colors is None:
+        return px_kwargs
+
+    # Check if any color_* kwarg is present - these take precedence
+    color_kwargs = [k for k in px_kwargs if k.startswith("color_")]
+    if color_kwargs:
+        warnings.warn(
+            f"`colors` parameter ignored because {color_kwargs[0]!r} "
+            f"was explicitly provided in px_kwargs.",
+            UserWarning,
+            stacklevel=3,
+        )
+        return px_kwargs
+
+    px_kwargs = px_kwargs.copy()
+
+    if isinstance(colors, str):
+        # Check if it's a qualitative (discrete) palette name
+        if colors in _get_qualitative_scale_names():
+            px_kwargs["color_discrete_sequence"] = getattr(px.colors.qualitative, colors)
+        else:
+            # Assume continuous scale
+            px_kwargs["color_continuous_scale"] = colors
+    elif isinstance(colors, Mapping):
+        px_kwargs["color_discrete_map"] = dict(colors)
+    elif isinstance(colors, Sequence):
+        px_kwargs["color_discrete_sequence"] = list(colors)
+    else:
+        msg = f"`colors` must be str, list, dict, or None, got {type(colors).__name__}"
+        raise TypeError(msg)
+
+    return px_kwargs

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/config.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 if TYPE_CHECKING:
     from collections.abc import Generator
@@ -166,12 +166,12 @@ def set_options(
         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"]
-        _options.dataset_variable_position = old_values["dataset_variable_position"]
+        _options.label_use_long_name = cast("bool", old_values["label_use_long_name"])
+        _options.label_use_standard_name = cast("bool", old_values["label_use_standard_name"])
+        _options.label_include_units = cast("bool", old_values["label_include_units"])
+        _options.label_unit_format = cast("str", old_values["label_unit_format"])
+        _options.slot_orders = cast("dict[str, tuple[str, ...]]", old_values["slot_orders"])
+        _options.dataset_variable_position = cast("int", old_values["dataset_variable_position"])
 
 
 def notebook(renderer: str = "notebook") -> None:

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/figures.py

@@ -5,7 +5,7 @@ Helper functions for combining and manipulating Plotly figures.
 from __future__ import annotations
 
 import copy
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -13,7 +13,7 @@ if TYPE_CHECKING:
     import plotly.graph_objects as go
 
 
-def _iter_all_traces(fig: go.Figure) -> Iterator:
+def _iter_all_traces(fig: go.Figure) -> Iterator[Any]:
     """Iterate over all traces in a figure, including animation frames.
 
     Yields traces from fig.data first, then from each frame in fig.frames.
@@ -107,7 +107,7 @@ def _merge_frames(
     overlays: list[go.Figure],
     base_trace_count: int,
     overlay_trace_counts: list[int],
-) -> list:
+) -> list[go.Frame]:
     """Merge animation frames from base and overlay figures.
 
     Args:
@@ -360,7 +360,7 @@ def _merge_secondary_y_frames(
     base: go.Figure,
     secondary: go.Figure,
     y_mapping: dict[str, str],
-) -> list:
+) -> list[go.Frame]:
     """Merge animation frames for secondary y-axis combination.
 
     Args:
@@ -411,7 +411,9 @@ def _merge_secondary_y_frames(
     return merged_frames
 
 
-def update_traces(fig: go.Figure, selector: dict | None = None, **kwargs) -> go.Figure:
+def update_traces(
+    fig: go.Figure, selector: dict[str, Any] | None = None, **kwargs: Any
+) -> go.Figure:
     """Update traces in both base figure and all animation frames.
 
     Plotly's `update_traces()` only updates the base figure, not animation frames.

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly/plotting.py

@@ -8,15 +8,18 @@ import warnings
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
+import numpy.typing as npt
 import plotly.express as px
 
 from xarray_plotly.common import (
+    Colors,
     SlotValue,
     assign_slots,
     auto,
     build_labels,
     get_label,
     get_value_col,
+    resolve_colors,
     to_dataframe,
 )
 from xarray_plotly.figures import (
@@ -38,6 +41,7 @@ def line(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -64,6 +68,13 @@ def line(
         Dimension for subplot rows. Default: sixth dimension.
     animation_frame
         Dimension for animation. Default: seventh dimension.
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.line()`.
 
@@ -71,6 +82,7 @@ def line(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "line",
@@ -111,6 +123,7 @@ def bar(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -135,6 +148,13 @@ def bar(
         Dimension for subplot rows. Default: fifth dimension.
     animation_frame
         Dimension for animation. Default: sixth dimension.
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.bar()`.
 
@@ -142,6 +162,7 @@ def bar(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "bar",
@@ -171,7 +192,7 @@ def bar(
     )
 
 
-def _classify_trace_sign(y_values: np.ndarray) -> str:
+def _classify_trace_sign(y_values: npt.ArrayLike) -> str:
     """Classify a trace as 'positive', 'negative', or 'mixed' based on its values."""
     y_arr = np.asarray(y_values)
     y_clean = y_arr[np.isfinite(y_arr) & (np.abs(y_arr) > 1e-9)]
@@ -263,6 +284,7 @@ def fast_bar(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -293,6 +315,13 @@ def fast_bar(
         Dimension for subplot rows. Default: fourth dimension.
     animation_frame
         Dimension for animation. Default: fifth dimension.
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.area()`.
 
@@ -300,6 +329,7 @@ def fast_bar(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "fast_bar",
@@ -341,6 +371,7 @@ def area(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -365,6 +396,13 @@ def area(
         Dimension for subplot rows. Default: fifth dimension.
     animation_frame
         Dimension for animation. Default: sixth dimension.
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.area()`.
 
@@ -372,6 +410,7 @@ def area(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "area",
@@ -409,6 +448,7 @@ def box(
     facet_col: SlotValue = None,
     facet_row: SlotValue = None,
     animation_frame: SlotValue = None,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -433,6 +473,13 @@ def box(
         Dimension for subplot rows. Default: None (aggregated).
     animation_frame
         Dimension for animation. Default: None (aggregated).
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.box()`.
 
@@ -440,6 +487,7 @@ def box(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "box",
@@ -478,6 +526,7 @@ def scatter(
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
     animation_frame: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -509,6 +558,13 @@ def scatter(
         Dimension for subplot rows. Default: fifth dimension.
     animation_frame
         Dimension for animation. Default: sixth dimension.
+    colors
+        Unified color specification. Can be:
+        - A named continuous scale (e.g., "Viridis")
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.scatter()`.
 
@@ -516,6 +572,7 @@ def scatter(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     # 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)
@@ -565,6 +622,7 @@ def imshow(
     facet_col: SlotValue = auto,
     animation_frame: SlotValue = auto,
     robust: bool = False,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -596,6 +654,11 @@ def imshow(
     robust
         If True, compute color bounds using 2nd and 98th percentiles
         for robustness against outliers. Default: False (uses min/max).
+    colors
+        Unified color specification. For imshow, typically a named
+        continuous scale (e.g., "Viridis", "RdBu"). Lists and dicts
+        are not applicable for heatmaps.
+        Explicit color_continuous_scale in px_kwargs takes precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.imshow()`.
         Use `zmin` and `zmax` to manually set color scale bounds.
@@ -604,6 +667,7 @@ def imshow(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "imshow",
@@ -648,6 +712,7 @@ def pie(
     color: SlotValue = None,
     facet_col: SlotValue = auto,
     facet_row: SlotValue = auto,
+    colors: Colors = None,
     **px_kwargs: Any,
 ) -> go.Figure:
     """
@@ -668,6 +733,12 @@ def pie(
         Dimension for subplot columns. Default: second dimension.
     facet_row
         Dimension for subplot rows. Default: third dimension.
+    colors
+        Unified color specification. Can be:
+        - A named discrete palette (e.g., "D3", "Plotly")
+        - A list of colors (e.g., ["red", "blue", "green"])
+        - A dict mapping values to colors (e.g., {"A": "red", "B": "blue"})
+        Explicit color_* kwargs in px_kwargs take precedence.
     **px_kwargs
         Additional arguments passed to `plotly.express.pie()`.
 
@@ -675,6 +746,7 @@ def pie(
     -------
     plotly.graph_objects.Figure
     """
+    px_kwargs = resolve_colors(colors, px_kwargs)
     slots = assign_slots(
         list(darray.dims),
         "pie",

{xarray_plotly-0.0.11 → xarray_plotly-0.0.12}/xarray_plotly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_plotly
-Version: 0.0.11
+Version: 0.0.12
 Summary: Interactive Plotly Express plotting accessor for xarray
 Author: Felix
 License: MIT