groups now hides NAs unless na_color is specified (#549)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -213,8 +213,9 @@ 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. If element is None, broadcasting behaviour is attempted (use the same
-            values for all elements).
+            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
             match the number of groups. If element is None, broadcasting behaviour is attempted (use the same values for
@@ -398,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
@@ -671,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

@@ -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(
@@ -1119,7 +1105,9 @@ def _set_color_source_vec(
             table_to_use = None
         else:
             table_keys = list(sdata.tables.keys())
-            if table_keys:
+            if len(table_keys) == 1:
+                table_to_use = table_keys[0]
+            elif len(table_keys) > 1:
                 table_to_use = table_keys[0]
                 logger.warning(f"No table name provided, using '{table_to_use}' as fallback for color mapping.")
             else: