Filter non-matching elements when groups is set with na_color=None

When `groups` is specified and `na_color=None`, non-matching shapes and
points are now filtered out entirely instead of rendered as invisible
geometry. This avoids wasting rendering time on transparent elements.

- Add _filter_groups_transparent_na() helper
- Apply filtering in _render_shapes and _render_points
- Update groups docstring to document na_color=None behavior
- Add regression tests (baseline images pending from CI)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -213,8 +213,9 @@ def render_shapes(
             `fill_alpha` will overwrite the value present in the cmap.
         groups : list[str] | str | None
             When using `color` and the key represents discrete labels, `groups` can be used to show only a subset of
-            them. Other values are set to NA. If element is None, broadcasting behaviour is attempted (use the same
-            values for all elements).
+            them. Other values are set to NA. When ``na_color=None``, non-matching elements are filtered out entirely
+            (shapes and points only). If element is None, broadcasting behaviour is attempted (use the same values for
+            all elements).
         palette :  list[str] | str | None
             Palette for discrete annotations. List of valid color names that should be used for the categories. Must
             match the number of groups. If element is None, broadcasting behaviour is attempted (use the same values for

src/spatialdata_plot/pl/render.py

@@ -118,6 +118,22 @@ def _build_datashader_color_key(
     return color_key
 
 
+def _filter_groups_transparent_na(
+    groups: str | list[str],
+    color_source_vector: pd.Categorical,
+    color_vector: pd.Series | np.ndarray | list[str],
+) -> tuple[np.ndarray, pd.Categorical, np.ndarray]:
+    """Return a boolean mask and filtered color vectors for groups filtering.
+
+    Used when ``na_color=None`` (fully transparent) so that non-matching
+    elements are removed entirely instead of rendered invisibly.
+    """
+    keep = color_source_vector.isin(groups)
+    filtered_csv = color_source_vector[keep]
+    filtered_cv = np.asarray(color_vector)[keep]
+    return keep, filtered_csv, filtered_cv
+
+
 def _split_colorbar_params(params: dict[str, object] | None) -> tuple[dict[str, object], dict[str, object], str | None]:
     """Split colorbar params into layout hints, Matplotlib kwargs, and label override."""
     layout: dict[str, object] = {}
@@ -221,6 +237,15 @@ def _render_shapes(
 
     values_are_categorical = color_source_vector is not None
 
+    # When groups are specified and na_color is fully transparent (na_color=None),
+    # filter out non-matching elements instead of showing them as invisible geometry.
+    if groups is not None and values_are_categorical and render_params.cmap_params.na_color.alpha == "00":
+        keep, color_source_vector, color_vector = _filter_groups_transparent_na(
+            groups, color_source_vector, color_vector
+        )
+        shapes = shapes[keep].reset_index(drop=True)
+        sdata_filt[element] = shapes
+
     # color_source_vector is None when the values aren't categorical
     if values_are_categorical and render_params.transfunc is not None:
         color_vector = render_params.transfunc(color_vector)
@@ -840,6 +865,24 @@ def _render_points(
         )
         points_dd = points_with_color_dd
 
+    # When groups are specified and na_color is fully transparent (na_color=None),
+    # filter out non-matching points instead of rendering invisible geometry.
+    if groups is not None and color_source_vector is not None and render_params.cmap_params.na_color.alpha == "00":
+        keep, color_source_vector, color_vector = _filter_groups_transparent_na(
+            groups, color_source_vector, color_vector
+        )
+        # filter the materialized points, adata, and re-register in sdata_filt
+        points = points[keep].reset_index(drop=True)
+        adata = adata[keep].copy()
+        points_dd = dask.dataframe.from_pandas(points, npartitions=1)
+        sdata_filt.points[element] = PointsModel.parse(points_dd, coordinates={"x": "x", "y": "y"})
+        set_transformation(
+            element=sdata_filt.points[element],
+            transformation=transformation_in_cs,
+            to_coordinate_system=coordinate_system,
+        )
+        n_points = int(keep.sum())
+
     # color_source_vector is None when the values aren't categorical
     if color_source_vector is None and render_params.transfunc is not None:
         color_vector = render_params.transfunc(color_vector)

tests/pl/test_render_points.py

@@ -576,6 +576,11 @@ def test_plot_can_annotate_points_with_nan_in_df_continuous_datashader(self, sda
         sdata_blobs["blobs_points"]["cont_color"] = pd.Series([np.nan, 2, 9, 13] * 50)
         sdata_blobs.pl.render_points("blobs_points", color="cont_color", size=40, method="datashader").pl.show()
 
+    def test_plot_groups_na_color_none_filters_points(self, sdata_blobs: SpatialData):
+        """When groups is set and na_color=None, non-matching points are filtered out entirely."""
+        sdata_blobs["blobs_points"]["cat_color"] = pd.Series(["a", "b", "c", "a"] * 50, dtype="category")
+        sdata_blobs.pl.render_points("blobs_points", color="cat_color", groups=["a"], na_color=None, size=30).pl.show()
+
 
 def test_raises_when_table_does_not_annotate_element(sdata_blobs: SpatialData):
     # Work on an independent copy since we mutate tables

tests/pl/test_render_shapes.py

@@ -983,6 +983,11 @@ def test_plot_can_annotate_shapes_with_nan_in_df_continuous_datashader(self, sda
         sdata_blobs["blobs_polygons"]["cont_color"] = [np.nan, 2, 3, 4, 5]
         sdata_blobs.pl.render_shapes("blobs_polygons", color="cont_color", method="datashader").pl.show()
 
+    def test_plot_groups_na_color_none_filters_shapes(self, sdata_blobs: SpatialData):
+        """When groups is set and na_color=None, non-matching shapes are filtered out entirely."""
+        sdata_blobs["blobs_polygons"]["cat_color"] = pd.Series(["a", "b", "a", "b", "a"], dtype="category")
+        sdata_blobs.pl.render_shapes("blobs_polygons", color="cat_color", groups=["a"], na_color=None).pl.show()
+
 
 def test_plot_can_handle_nan_values_in_color_data(sdata_blobs: SpatialData, caplog):
     """Test that NaN values in color data are handled gracefully and logged."""