From eb3bcc99c186cd255873904b3450d441b94056a7 Mon Sep 17 00:00:00 2001
From: FBumann <117816358+FBumann@users.noreply.github.com>
Date: Sat, 10 Jan 2026 17:33:28 +0100
Subject: [PATCH] Add missing infos to docstring

---
 xarray_plotly/accessor.py |  5 +++++
 xarray_plotly/plotting.py | 10 +++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/xarray_plotly/accessor.py b/xarray_plotly/accessor.py
index 95e1351..ff45d26 100644
--- a/xarray_plotly/accessor.py
+++ b/xarray_plotly/accessor.py
@@ -257,6 +257,11 @@ def imshow(
 
         Slot order: y (rows) -> x (columns) -> facet_col -> animation_frame
 
+        Note:
+            **Difference from px.imshow**: Color bounds are computed from the
+            entire dataset by default, ensuring consistent coloring across
+            animation frames. Use `zmin`/`zmax` to override.
+
         Args:
             x: Dimension for x-axis (columns). Default: second dimension.
             y: Dimension for y-axis (rows). Default: first dimension.
diff --git a/xarray_plotly/plotting.py b/xarray_plotly/plotting.py
index ed1142b..638de94 100644
--- a/xarray_plotly/plotting.py
+++ b/xarray_plotly/plotting.py
@@ -408,6 +408,14 @@ def imshow(
     Both x and y are dimensions. Dimensions fill slots in order:
     y (rows) -> x (columns) -> facet_col -> animation_frame
 
+    .. note::
+        **Difference from plotly.express.imshow**: By default, color bounds
+        (zmin/zmax) are computed from the **entire dataset**, ensuring
+        consistent coloring across animation frames and facets. In contrast,
+        ``px.imshow`` auto-scales each frame independently, which can make
+        animations visually confusing. Set ``zmin`` and ``zmax`` explicitly
+        to override this behavior.
+
     Parameters
     ----------
     darray
@@ -422,7 +430,7 @@ def imshow(
         Dimension for animation. Default: fourth dimension.
     robust
         If True, compute color bounds using 2nd and 98th percentiles
-        for robustness against outliers. Default: False.
+        for robustness against outliers. Default: False (uses min/max).
     **px_kwargs
         Additional arguments passed to `plotly.express.imshow()`.
         Use `zmin` and `zmax` to manually set color scale bounds.