Split out groups filtering, fix deprecated dtype checks

Move groups filtering with na_color=None to a follow-up PR (#549).
Replace deprecated pd.api.types.is_categorical_dtype with
isinstance(dtype, pd.CategoricalDtype). Add TypeError for unsupported
types in _coerce_categorical_source.

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

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -213,9 +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. 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).
+            them. Other values are set to NA. 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

@@ -70,20 +70,32 @@
 
 
 def _coerce_categorical_source(cat_source: Any) -> pd.Categorical:
-    """Return a pandas Categorical from known, concrete sources only."""
+    """Return a pandas Categorical from known, concrete sources only.
+
+    Raises
+    ------
+    TypeError
+        If *cat_source* is not a ``dd.Series``, ``pd.Series``,
+        ``pd.Categorical``, or ``np.ndarray``.
+    """
     if isinstance(cat_source, dd.Series):
-        if pd.api.types.is_categorical_dtype(cat_source.dtype) and getattr(cat_source.cat, "known", True) is False:
+        if isinstance(cat_source.dtype, pd.CategoricalDtype) and getattr(cat_source.cat, "known", True) is False:
             cat_source = cat_source.cat.as_known()
         cat_source = cat_source.compute()
 
     if isinstance(cat_source, pd.Series):
-        if pd.api.types.is_categorical_dtype(cat_source.dtype):
+        if isinstance(cat_source.dtype, pd.CategoricalDtype):
             return cat_source.array
         return pd.Categorical(cat_source)
     if isinstance(cat_source, pd.Categorical):
         return cat_source
+    if isinstance(cat_source, np.ndarray):
+        return pd.Categorical(cat_source)
 
-    return pd.Categorical(pd.Series(cat_source))
+    raise TypeError(
+        f"Cannot coerce {type(cat_source).__name__} to pd.Categorical. "
+        "Expected dd.Series, pd.Series, pd.Categorical, or np.ndarray."
+    )
 
 
 def _build_datashader_color_key(
@@ -209,20 +221,6 @@ 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":
-        csv_series = pd.Series(color_source_vector)
-        keep = csv_series.isin(groups).values
-        shapes = shapes[keep].reset_index(drop=True)
-        sdata_filt[element] = shapes
-        color_source_vector = pd.Categorical(csv_series[keep].reset_index(drop=True))
-        color_vector = (
-            np.asarray(color_vector)[keep]
-            if not hasattr(color_vector, "reset_index")
-            else (color_vector[keep].reset_index(drop=True))
-        )
-
     # 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)
@@ -352,7 +350,7 @@ def _render_shapes(
         color_by_categorical = col_for_color is not None and color_source_vector is not None
         if color_by_categorical:
             cat_series = transformed_element[col_for_color]
-            if not pd.api.types.is_categorical_dtype(cat_series):
+            if not isinstance(cat_series.dtype, pd.CategoricalDtype):
                 cat_series = cat_series.astype("category")
             transformed_element[col_for_color] = cat_series
 
@@ -842,29 +840,6 @@ 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":
-        csv_series = pd.Series(color_source_vector)
-        keep = csv_series.isin(groups).values
-        color_source_vector = pd.Categorical(csv_series[keep].reset_index(drop=True))
-        color_vector = (
-            np.asarray(color_vector)[keep]
-            if not hasattr(color_vector, "reset_index")
-            else (color_vector[keep].reset_index(drop=True))
-        )
-        # 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)
@@ -931,11 +906,11 @@ def _render_points(
         color_dtype = transformed_element[col_for_color].dtype if col_for_color is not None else None
         color_by_categorical = col_for_color is not None and (
             color_source_vector is not None
-            or pd.api.types.is_categorical_dtype(color_dtype)
+            or isinstance(color_dtype, pd.CategoricalDtype)
             or pd.api.types.is_object_dtype(color_dtype)
             or pd.api.types.is_string_dtype(color_dtype)
         )
-        if color_by_categorical and not pd.api.types.is_categorical_dtype(color_dtype):
+        if color_by_categorical and not isinstance(color_dtype, pd.CategoricalDtype):
             transformed_element[col_for_color] = transformed_element[col_for_color].astype("category")
 
         aggregate_with_reduction = None
@@ -944,7 +919,7 @@ def _render_points(
             if color_by_categorical:
                 # add nan as category so that nan points are shown in the nan color
                 cat_series = transformed_element[col_for_color]
-                if not pd.api.types.is_categorical_dtype(cat_series):
+                if not isinstance(cat_series.dtype, pd.CategoricalDtype):
                     cat_series = cat_series.astype("category")
                 if hasattr(cat_series.cat, "as_known"):
                     cat_series = cat_series.cat.as_known()

tests/_images/Points_groups_na_color_none_filters_points.png

@@ -576,11 +576,6 @@ 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/_images/Shapes_groups_na_color_none_filters_shapes.png

@@ -983,11 +983,6 @@ 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."""