Simplify overengineered functions from PRs #427/#547

- _coerce_categorical_source: remove unreachable dd.Series, np.ndarray,
  and pd.Categorical branches (callers always pass pd.Series). 27→4 lines.
- _build_datashader_color_key: replace O(n*k) flatnonzero scans with a
  single pass over codes. Also handles NaN sentinel via the same fallback.
- _build_alignment_dtype_hint: remove overly broad exception catching
  (TypeError, AttributeError), redundant hasattr checks, and the
  color-index comparison that duplicates the element-index check. 32→12 lines.

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

Author: timtreis

src/spatialdata_plot/pl/render.py

@@ -69,33 +69,11 @@
 _DS_NAN_CATEGORY = "ds_nan"
 
 
-def _coerce_categorical_source(cat_source: Any) -> pd.Categorical:
-    """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 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 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)
-
-    raise TypeError(
-        f"Cannot coerce {type(cat_source).__name__} to pd.Categorical. "
-        "Expected dd.Series, pd.Series, pd.Categorical, or np.ndarray."
-    )
+def _coerce_categorical_source(series: pd.Series) -> pd.Categorical:
+    """Return a ``pd.Categorical`` from a pandas Series."""
+    if isinstance(series.dtype, pd.CategoricalDtype):
+        return series.array
+    return pd.Categorical(series)
 
 
 def _build_datashader_color_key(
@@ -104,18 +82,17 @@ def _build_datashader_color_key(
     na_color_hex: str,
 ) -> dict[str, str]:
     """Build a datashader ``color_key`` dict from a categorical series and its color vector."""
+    na_hex = _hex_no_alpha(na_color_hex) if na_color_hex.startswith("#") else na_color_hex
+    # Map each category to its first-occurrence color via codes
     colors_arr = np.asarray(color_vector, dtype=object)
-    color_key: dict[str, str] = {}
-    for cat in cat_series.categories:
-        if cat == _DS_NAN_CATEGORY:
-            key_color = na_color_hex
-        else:
-            idx = np.flatnonzero(cat_series == cat)
-            key_color = colors_arr[idx[0]] if idx.size else na_color_hex
-        if isinstance(key_color, str) and key_color.startswith("#"):
-            key_color = _hex_no_alpha(key_color)
-        color_key[str(cat)] = key_color
-    return color_key
+    first_color: dict[str, str] = {}
+    for code, color in zip(cat_series.codes, colors_arr, strict=False):
+        if code < 0:
+            continue
+        cat_name = str(cat_series.categories[code])
+        if cat_name not in first_color:
+            first_color[cat_name] = _hex_no_alpha(color) if isinstance(color, str) and color.startswith("#") else color
+    return {str(c): first_color.get(str(c), na_hex) for c in cat_series.categories}
 
 
 def _inject_ds_nan_sentinel(series: pd.Series, sentinel: str = _DS_NAN_CATEGORY) -> pd.Series:

src/spatialdata_plot/pl/utils.py

@@ -990,31 +990,17 @@ def _build_alignment_dtype_hint(
     table_name: str | None,
 ) -> str:
     """Build a diagnostic hint string for dtype mismatches between element and table indices."""
-    hints: list[str] = []
-    color_index_dtype = getattr(color_series.index, "dtype", None)
-    element_index_dtype = getattr(getattr(element, "index", None), "dtype", None) if element is not None else None
-
-    table_instance_dtype = None
-    instance_key = None
-    if table_name is not None and sdata is not None and table_name in sdata.tables:
-        table = sdata.tables[table_name]
-        try:
-            _, _, instance_key = get_table_keys(table)
-        except (KeyError, ValueError, TypeError, AttributeError):
-            instance_key = None
-        if instance_key is not None and hasattr(table, "obs") and instance_key in table.obs:
-            table_instance_dtype = table.obs[instance_key].dtype
-
-    if (
-        element_index_dtype is not None
-        and table_instance_dtype is not None
-        and element_index_dtype != table_instance_dtype
-    ):
-        hints.append(f"element index dtype is {element_index_dtype}, '{instance_key}' dtype is {table_instance_dtype}")
-    if color_index_dtype is not None and element_index_dtype is not None and color_index_dtype != element_index_dtype:
-        hints.append(f"color index dtype is {color_index_dtype}, element index dtype is {element_index_dtype}")
-
-    return f" (hint: {'; '.join(hints)})" if hints else ""
+    el_dtype = getattr(getattr(element, "index", None), "dtype", None)
+    if el_dtype is None or table_name is None or sdata is None or table_name not in sdata.tables:
+        return ""
+    try:
+        _, _, instance_key = get_table_keys(sdata.tables[table_name])
+    except (KeyError, ValueError):
+        return ""
+    tbl_dtype = sdata.tables[table_name].obs[instance_key].dtype
+    if el_dtype != tbl_dtype:
+        return f" (hint: element index dtype is {el_dtype}, '{instance_key}' dtype is {tbl_dtype})"
+    return ""
 
 
 def _set_color_source_vec(