Fix shapes datashader colorbar exceeding data range (#559)

The default datashader reduction for shapes was "sum", causing overlapping
shapes to inflate the colorbar beyond the true data maximum. Changed the
default to "max" which preserves the actual data range and closely matches
the matplotlib rendering.

Also: extract _default_reduction to prevent log/aggregation drift, add
logger_no_warns test helper, short-circuit _want_decorations for diverse
color vectors.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/_logging.py

@@ -113,3 +113,40 @@ def logger_warns(
         if not any(pattern.search(r.getMessage()) for r in records):
             msgs = [r.getMessage() for r in records]
             raise AssertionError(f"Did not find log matching {match!r} in records: {msgs!r}")
+
+
+@contextmanager
+def logger_no_warns(
+    caplog: LogCaptureFixture,
+    logger: logging.Logger,
+    match: str | None = None,
+    level: int = logging.WARNING,
+) -> Iterator[None]:
+    """Assert that no log record matching *match* is emitted.
+
+    Counterpart to :func:`logger_warns`.
+    """
+    initial_record_count = len(caplog.records)
+
+    handler = caplog.handler
+    logger.addHandler(handler)
+    original_level = logger.level
+    logger.setLevel(level)
+
+    with caplog.at_level(level, logger=logger.name):
+        try:
+            yield
+        finally:
+            logger.removeHandler(handler)
+            logger.setLevel(original_level)
+
+    records = [r for r in caplog.records[initial_record_count:] if r.levelno >= level]
+
+    if match is not None:
+        pattern = re.compile(match)
+        matching = [r.getMessage() for r in records if pattern.search(r.getMessage())]
+        if matching:
+            raise AssertionError(f"Found unexpected log matching {match!r}: {matching!r}")
+    elif records:
+        msgs = [r.getMessage() for r in records]
+        raise AssertionError(f"Expected no log records at level>={level}, but got: {msgs!r}")

src/spatialdata_plot/pl/basic.py

@@ -272,8 +272,8 @@ def render_shapes(
 
             datashader_reduction : Literal[
                 "sum", "mean", "any", "count", "std", "var", "max", "min"
-            ], default: "sum"
-                Reduction method for datashader when coloring by continuous values. Defaults to 'sum'.
+            ], default: "max"
+                Reduction method for datashader when coloring by continuous values. Defaults to 'max'.
 
 
         Notes

src/spatialdata_plot/pl/render.py

@@ -34,6 +34,7 @@
     _ds_aggregate,
     _ds_shade_categorical,
     _ds_shade_continuous,
+    _DsReduction,
     _render_ds_image,
     _render_ds_outlines,
 )
@@ -82,11 +83,9 @@ def _want_decorations(color_vector: Any, na_color: Color) -> bool:
     cv = np.asarray(color_vector)
     if cv.size == 0:
         return False
-    # Fast check: if any value differs from the first, there is variety → show decorations.
     first = cv.flat[0]
-    if not (cv == first).all():
+    if any(v != first for v in cv.flat[1:]):
         return True
-    # All values are the same — suppress decorations when that value is the NA color.
     na_hex = na_color.get_hex()
     if isinstance(first, str) and first.startswith("#") and na_hex.startswith("#"):
         return _hex_no_alpha(first) != _hex_no_alpha(na_hex)
@@ -425,10 +424,14 @@ def _render_shapes(
     if method is None:
         method = "datashader" if len(shapes) > 10000 else "matplotlib"
 
+    _default_reduction: _DsReduction = "max"
+
     if method != "matplotlib":
-        # we only notify the user when we switched away from matplotlib
+        _effective_reduction = (
+            render_params.ds_reduction if render_params.ds_reduction is not None else _default_reduction
+        )
         logger.info(
-            f"Using '{method}' backend with '{render_params.ds_reduction}' as reduction"
+            f"Using '{method}' backend with '{_effective_reduction}' as reduction"
             " method to speed up plotting. Depending on the reduction method, the value"
             " range of the plot might change. Set method to 'matplotlib' to disable"
             " this behaviour."
@@ -506,7 +509,7 @@ def _render_shapes(
             col_for_color,
             color_by_categorical,
             render_params.ds_reduction,
-            "mean",
+            _default_reduction,
             "shapes",
         )
 
@@ -784,8 +787,7 @@ def _render_points(
     # from the registered points (see above) avoids duplicate-origin ambiguities.
     color_table_name = table_name
 
-    # When color was already loaded from a table (line 690), pass it directly
-    # to avoid a redundant get_values() call inside _set_color_source_vec.
+    # Reuse color data already loaded from the table to avoid a redundant get_values() call.
     _preloaded = points_pd_with_color[col_for_color] if added_color_from_table and col_for_color is not None else None
 
     color_source_vector, color_vector, _ = _set_color_source_vec(
@@ -840,12 +842,16 @@ def _render_points(
     if method is None:
         method = "datashader" if n_points > 10000 else "matplotlib"
 
+    _default_reduction: _DsReduction = "sum"
+
     if method == "datashader":
-        # we only notify the user when we switched away from matplotlib
+        _effective_reduction = (
+            render_params.ds_reduction if render_params.ds_reduction is not None else _default_reduction
+        )
         logger.info(
-            f"Using '{method}' backend with '{render_params.ds_reduction}' as reduction"
+            f"Using '{method}' backend with '{_effective_reduction}' as reduction"
             " method to speed up plotting. Depending on the reduction method, the value"
-            " range of the plot might change. Set method to 'matplotlib' do disable"
+            " range of the plot might change. Set method to 'matplotlib' to disable"
             " this behaviour."
         )
 
@@ -906,7 +912,7 @@ def _render_points(
             col_for_color,
             color_by_categorical,
             render_params.ds_reduction,
-            "sum",
+            _default_reduction,
             "points",
         )
 

src/spatialdata_plot/pl/utils.py

@@ -2507,9 +2507,6 @@ def _ensure_table_and_layer_exist_in_sdata(
     if ds_reduction and (ds_reduction not in valid_ds_reduction_methods):
         raise ValueError(f"Parameter 'ds_reduction' must be one of the following: {valid_ds_reduction_methods}.")
 
-    if method == "datashader" and ds_reduction is None:
-        param_dict["ds_reduction"] = "sum"
-
     return param_dict
 
 

tests/pl/test_render_points.py

@@ -1,4 +1,3 @@
-import logging
 import math
 
 import dask.dataframe
@@ -24,7 +23,7 @@
 from spatialdata.transformations._utils import _set_transformations
 
 import spatialdata_plot  # noqa: F401
-from spatialdata_plot._logging import logger, logger_warns
+from spatialdata_plot._logging import logger, logger_no_warns, logger_warns
 from spatialdata_plot.pl._datashader import (
     _build_datashader_color_key,
     _ds_aggregate,
@@ -832,13 +831,8 @@ def test_ds_reduction_ignored_for_categorical(caplog):
 def test_ds_reduction_no_warning_when_none(caplog):
     """No spurious warning when ds_reduction is None (the default)."""
     cvs, df = _make_ds_canvas_and_df()
-    with caplog.at_level(logging.WARNING, logger=logger.name):
-        logger.addHandler(caplog.handler)
-        try:
-            _ds_aggregate(cvs, df.copy(), "cat", True, None, "sum", "points")
-        finally:
-            logger.removeHandler(caplog.handler)
-    assert not any("ignored" in r.message.lower() for r in caplog.records)
+    with logger_no_warns(caplog, logger, match="ignored"):
+        _ds_aggregate(cvs, df.copy(), "cat", True, None, "sum", "points")
 
 
 @pytest.mark.parametrize("reduction", ["mean", "max", "min", "count", "std", "var"])
@@ -866,13 +860,8 @@ def test_warn_groups_ignored_continuous_emits(caplog):
 
 def test_warn_groups_ignored_continuous_silent_for_categorical(caplog):
     """No warning when color_source_vector is present (categorical)."""
-    with caplog.at_level(logging.WARNING, logger=logger.name):
-        logger.addHandler(caplog.handler)
-        try:
-            _warn_groups_ignored_continuous(["A"], pd.Categorical(["A", "B"]), "cat_col")
-        finally:
-            logger.removeHandler(caplog.handler)
-    assert not any("ignored" in r.message for r in caplog.records)
+    with logger_no_warns(caplog, logger, match="ignored"):
+        _warn_groups_ignored_continuous(["A"], pd.Categorical(["A", "B"]), "cat_col")
 
 
 def test_color_key_warns_on_short_color_vector(caplog):
@@ -893,13 +882,8 @@ def test_color_key_warns_on_long_color_vector(caplog):
 def test_color_key_no_warning_when_lengths_match(caplog):
     """No warning when lengths match."""
     cat = pd.Categorical(["A", "B", "C"])
-    with caplog.at_level(logging.WARNING, logger=logger.name):
-        logger.addHandler(caplog.handler)
-        try:
-            _build_datashader_color_key(cat, ["#ff0000", "#00ff00", "#0000ff"], "#cccccc")
-        finally:
-            logger.removeHandler(caplog.handler)
-    assert not any("color_vector length" in r.message for r in caplog.records)
+    with logger_no_warns(caplog, logger, match="color_vector length"):
+        _build_datashader_color_key(cat, ["#ff0000", "#00ff00", "#0000ff"], "#cccccc")
 
 
 def test_color_key_unseen_category_gets_na_color(caplog):

tests/pl/test_render_shapes.py

@@ -1142,3 +1142,38 @@ def test_datashader_alpha_not_applied_twice(sdata_blobs: SpatialData):
             "on top of the alpha already in the RGBA channels — causing double transparency."
         )
     plt.close(fig)
+
+
+def test_datashader_colorbar_range_matches_data(sdata_blobs: SpatialData):
+    """Datashader colorbar range must not exceed the actual data range for shapes.
+
+    Regression test for https://github.com/scverse/spatialdata-plot/issues/559.
+    Before the fix, shapes defaulted to 'sum' aggregation, causing overlapping
+    shapes to inflate the colorbar beyond the true data maximum.
+    """
+    n = len(sdata_blobs.shapes["blobs_circles"])
+    rng = np.random.default_rng(0)
+    values = rng.uniform(0, 100, size=n)
+    sdata_blobs.shapes["blobs_circles"]["continuous_val"] = values
+    data_max = float(values.max())
+    data_min = float(values.min())
+
+    fig, ax = plt.subplots()
+    sdata_blobs.pl.render_shapes("blobs_circles", color="continuous_val", method="datashader").pl.show(ax=ax)
+
+    # Find the colorbar axis — it's a child axes with a ScalarMappable
+    cbar_vmax = None
+    cbar_vmin = None
+    for child in fig.get_children():
+        if isinstance(child, matplotlib.axes.Axes) and child is not ax:
+            ylim = child.get_ylim()
+            if ylim != (0.0, 1.0):  # colorbar axes have non-default limits
+                cbar_vmin, cbar_vmax = ylim
+
+    assert cbar_vmax is not None, "Could not find colorbar in figure"
+    assert cbar_vmax <= data_max * 1.01, (
+        f"Colorbar max ({cbar_vmax:.2f}) exceeds data max ({data_max:.2f}); "
+        "datashader aggregation is likely using 'sum' instead of 'max'"
+    )
+    assert cbar_vmin >= data_min * 0.99 - 0.01, f"Colorbar min ({cbar_vmin:.2f}) is below data min ({data_min:.2f})"
+    plt.close(fig)