Fix shapes datashader colorbar exceeding data range (#561)

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",
         )
 
@@ -796,8 +802,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(
@@ -852,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
@@ -918,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)