Refactor: extract groups filtering helper, fix deprecated dtype checks

- Extract _filter_groups_transparent_na() to deduplicate shapes/points filtering
- Replace pd.api.types.is_categorical_dtype with isinstance(dtype, pd.CategoricalDtype)
- Add TypeError for unsupported types in _coerce_categorical_source
- Simplify np.ndarray branch and use Categorical.isin() directly

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

Author: timtreis

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(
@@ -106,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] = {}
@@ -212,16 +240,11 @@ def _render_shapes(
     # 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
+        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 = 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:
@@ -352,7 +375,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
 
@@ -845,13 +868,8 @@ def _render_points(
     # 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))
+        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)
@@ -931,11 +949,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 +962,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()