Address review: deduplicate warning, add tests, cover labels

- Extract `_warn_missing_groups` helper and call it from
  `_filter_groups_transparent_na` (shapes/points) and inline in labels,
  removing duplicated logic from both call sites.
- Distinguish "none matched" (likely wrong column) from "some missing"
  (likely typo) with different warning messages.
- Replace assert with explicit `color_source_vector is not None` guard
  in the shapes condition, matching the points pattern.
- Add 4 tests (shapes + points × all-missing + partial-missing) using
  `logger_warns` to lock the warning behavior.
- Drop `**kwargs` from empty `PatchCollection` fallback.

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

Author: timtreis

src/spatialdata_plot/pl/render.py

@@ -108,16 +108,42 @@ def _reparse_points(
     )
 
 
+def _warn_missing_groups(
+    groups: str | list[str],
+    color_source_vector: pd.Categorical,
+    col_for_color: str | None = None,
+) -> None:
+    """Warn when ``groups`` contains values absent from the color column's categories."""
+    groups_list = [groups] if isinstance(groups, str) else list(groups)
+    missing = set(groups_list) - set(color_source_vector.categories)
+    if not missing:
+        return
+    col_label = f" '{col_for_color}'" if col_for_color else ""
+    if missing == set(groups_list):
+        logger.warning(
+            f"None of the requested groups {sorted(missing)} were found in column{col_label}. "
+            "This usually means `groups` refers to values from a different column than `color`. "
+            "The `groups` parameter selects categories of the column specified via `color`."
+        )
+    else:
+        logger.warning(
+            f"Groups {sorted(missing)} were not found in column{col_label} and will be ignored. "
+            f"Available categories: {sorted(color_source_vector.categories)}."
+        )
+
+
 def _filter_groups_transparent_na(
     groups: str | list[str],
     color_source_vector: pd.Categorical,
     color_vector: pd.Series | np.ndarray | list[str],
+    col_for_color: str | None = None,
 ) -> 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.
     """
+    _warn_missing_groups(groups, color_source_vector, col_for_color)
     keep = color_source_vector.isin(groups)
     filtered_csv = color_source_vector[keep]
     filtered_cv = np.asarray(color_vector)[keep]
@@ -301,17 +327,9 @@ def _render_shapes(
     # When groups are specified, filter out non-matching elements by default.
     # Only show non-matching elements if the user explicitly sets na_color.
     _na = render_params.cmap_params.na_color
-    if groups is not None and values_are_categorical and (_na.default_color_set or _na.alpha == "00"):
-        assert color_source_vector is not None  # guaranteed by values_are_categorical
-        _groups_list = [groups] if isinstance(groups, str) else groups
-        _missing = set(_groups_list) - set(color_source_vector.categories)
-        if _missing:
-            logger.warning(
-                f"Groups {sorted(_missing)} not found in the values of '{col_for_color}'. "
-                "The `groups` parameter filters values of the `color` column."
-            )
+    if groups is not None and color_source_vector is not None and (_na.default_color_set or _na.alpha == "00"):
         keep, color_source_vector, color_vector = _filter_groups_transparent_na(
-            groups, color_source_vector, color_vector
+            groups, color_source_vector, color_vector, col_for_color=col_for_color
         )
         shapes = shapes[keep].reset_index(drop=True)
         if len(shapes) == 0:
@@ -762,15 +780,8 @@ def _render_points(
     # Only show non-matching elements if the user explicitly sets na_color.
     _na = render_params.cmap_params.na_color
     if groups is not None and color_source_vector is not None and (_na.default_color_set or _na.alpha == "00"):
-        _groups_list = [groups] if isinstance(groups, str) else groups
-        _missing = set(_groups_list) - set(color_source_vector.categories)
-        if _missing:
-            logger.warning(
-                f"Groups {sorted(_missing)} not found in the values of '{col_for_color}'. "
-                "The `groups` parameter filters values of the `color` column."
-            )
         keep, color_source_vector, color_vector = _filter_groups_transparent_na(
-            groups, color_source_vector, color_vector
+            groups, color_source_vector, color_vector, col_for_color=col_for_color
         )
         n_points = int(keep.sum())
         if n_points == 0:
@@ -1322,6 +1333,7 @@ def _render_labels(
         and color_source_vector is not None
         and (_na.default_color_set or _na.alpha == "00")
     ):
+        _warn_missing_groups(groups, color_source_vector, col_for_color)
         keep_vec = color_source_vector.isin(groups)
         matching_ids = instance_id[keep_vec]
         keep_mask = np.isin(label.values, matching_ids)

src/spatialdata_plot/pl/utils.py

@@ -554,7 +554,7 @@ def _create_patches(
     )
 
     if patches.empty:
-        return PatchCollection([], **kwargs)
+        return PatchCollection([])
 
     return PatchCollection(
         patches["geometry"].values.tolist(),

tests/pl/test_render_points.py

@@ -22,6 +22,7 @@
 from spatialdata.transformations._utils import _set_transformations
 
 import spatialdata_plot  # noqa: F401
+from spatialdata_plot._logging import logger, logger_warns
 from tests.conftest import DPI, PlotTester, PlotTesterMeta, _viridis_with_under_over, get_standard_RNG
 
 sc.pl.set_rcParams_defaults()
@@ -607,6 +608,24 @@ def test_groups_na_color_none_no_match_points(sdata_blobs: SpatialData):
     ).pl.show()
 
 
+def test_groups_warns_when_no_groups_match_points(sdata_blobs: SpatialData, caplog):
+    """When none of the groups match color categories, a warning should be emitted."""
+    sdata_blobs["blobs_points"]["cat_color"] = pd.Series(["a", "b", "c", "a"] * 50, dtype="category")
+    with logger_warns(caplog, logger, match="None of the requested groups"):
+        sdata_blobs.pl.render_points(
+            "blobs_points", color="cat_color", groups=["nonexistent"], na_color=None, size=30
+        ).pl.show()
+
+
+def test_groups_warns_when_some_groups_missing_points(sdata_blobs: SpatialData, caplog):
+    """When some groups match but others don't, a warning should list the missing ones."""
+    sdata_blobs["blobs_points"]["cat_color"] = pd.Series(["a", "b", "c", "a"] * 50, dtype="category")
+    with logger_warns(caplog, logger, match="were not found in column"):
+        sdata_blobs.pl.render_points(
+            "blobs_points", color="cat_color", groups=["a", "nonexistent"], 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
     sdata_blobs_local = deepcopy(sdata_blobs)

tests/pl/test_render_shapes.py

@@ -1016,6 +1016,24 @@ def test_groups_na_color_none_no_match_shapes(sdata_blobs: SpatialData):
     sdata_blobs.pl.render_shapes("blobs_polygons", color="cat_color", groups=["nonexistent"], na_color=None).pl.show()
 
 
+def test_groups_warns_when_no_groups_match(sdata_blobs: SpatialData, caplog):
+    """When none of the groups match color categories, a warning should be emitted."""
+    sdata_blobs["blobs_polygons"]["cat_color"] = pd.Series(["a", "b", "a", "b", "a"], dtype="category")
+    with logger_warns(caplog, logger, match="None of the requested groups"):
+        sdata_blobs.pl.render_shapes(
+            "blobs_polygons", color="cat_color", groups=["nonexistent"], na_color=None
+        ).pl.show()
+
+
+def test_groups_warns_when_some_groups_missing(sdata_blobs: SpatialData, caplog):
+    """When some groups match but others don't, a warning should list the missing ones."""
+    sdata_blobs["blobs_polygons"]["cat_color"] = pd.Series(["a", "b", "a", "b", "a"], dtype="category")
+    with logger_warns(caplog, logger, match="were not found in column"):
+        sdata_blobs.pl.render_shapes(
+            "blobs_polygons", color="cat_color", groups=["a", "nonexistent"], 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."""
     sdata_blobs["table"].obs["region"] = pd.Categorical(["blobs_circles"] * sdata_blobs["table"].n_obs)