Filter non-matching labels when groups is set without explicit na_color

Consistent with shapes/points: when groups is specified, non-matching
label IDs are zeroed out (rendered as background) by default. Setting
na_color explicitly restores the old "show in grey" behavior.

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

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -213,8 +213,8 @@ 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. By default, non-matching elements are filtered out entirely (shapes and points only; labels are
-            raster-based and cannot be filtered). To show non-matching elements, set ``na_color`` explicitly.
+            them. By default, non-matching elements are hidden. To show non-matching elements, set ``na_color``
+            explicitly.
             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
@@ -399,8 +399,9 @@ def render_points(
             value is used instead.
         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. By default, non-matching points are filtered out entirely. To show non-matching points, set
+            ``na_color`` explicitly.
+            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
@@ -672,7 +673,7 @@ def render_labels(
             table_name to be used for the element if you would like a specific table to be used.
         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. The list can contain multiple discrete labels to be visualized.
+            them. By default, non-matching labels are hidden. To show non-matching labels, set ``na_color`` explicitly.
         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. The list can contain multiple palettes (one per group) to be visualized. If

src/spatialdata_plot/pl/render.py

@@ -1531,6 +1531,26 @@ def _render_labels(
         else:
             assert color_source_vector is None
 
+    # When groups are specified, zero out non-matching label IDs so they render as background.
+    # Only show non-matching labels if the user explicitly sets na_color.
+    _na = render_params.cmap_params.na_color
+    if (
+        groups is not None
+        and categorical
+        and color_source_vector is not None
+        and (_na.default_color_set or _na.alpha == "00")
+    ):
+        keep_vec = color_source_vector.isin(groups)
+        matching_ids = instance_id[keep_vec]
+        keep_mask = np.isin(label.values, matching_ids)
+        label = label.copy()
+        label.values[~keep_mask] = 0
+        instance_id = instance_id[keep_vec]
+        color_source_vector = color_source_vector[keep_vec]
+        color_vector = color_vector[keep_vec]
+        if isinstance(color_vector.dtype, pd.CategoricalDtype):
+            color_vector = color_vector.remove_unused_categories()
+
     def _draw_labels(seg_erosionpx: int | None, seg_boundaries: bool, alpha: float) -> matplotlib.image.AxesImage:
         labels = _map_color_seg(
             seg=label.values,