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,17 +83,26 @@ 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():
         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)
     return bool(first != na_hex)
 
 
+def _log_datashader_method(method: str, ds_reduction: _DsReduction | None, default: _DsReduction) -> None:
+    """Log the datashader backend and effective reduction being used."""
+    effective = ds_reduction if ds_reduction is not None else default
+    logger.info(
+        f"Using '{method}' backend with '{effective}' 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."
+    )
+
+
 def _reparse_points(
     sdata_filt: sd.SpatialData,
     element: str,
@@ -437,14 +447,10 @@ 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
-        logger.info(
-            f"Using '{method}' backend with '{render_params.ds_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."
-        )
+        _log_datashader_method(method, render_params.ds_reduction, _default_reduction)
 
     if method == "datashader":
         _geometry = shapes["geometry"]
@@ -518,7 +524,7 @@ def _render_shapes(
             col_for_color,
             color_by_categorical,
             render_params.ds_reduction,
-            "mean",
+            _default_reduction,
             "shapes",
         )
 
@@ -851,14 +857,10 @@ 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
-        logger.info(
-            f"Using '{method}' backend with '{render_params.ds_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"
-            " this behaviour."
-        )
+        _log_datashader_method(method, render_params.ds_reduction, _default_reduction)
 
         # NOTE: s in matplotlib is in units of points**2
         # use dpi/100 as a factor for cases where dpi!=100
@@ -917,7 +919,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

@@ -1175,3 +1175,38 @@ def test_render_shapes_color_with_conflicting_index_name():
 
     # Should not raise ValueError: cannot insert EntityID, already exists
     sdata.pl.render_shapes("shapes", color="cell_type", table_name="table").pl.show()
+
+
+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)