Fix col_for_color mutation during multi-table iteration, add unit tests

Avoid mutating col_for_color inside the auto-detect loop — resolve
gene symbol to var_name only once after the table is selected.
Add non-visual tests for the auto-detect path, missing symbol, and
missing column error cases.

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

Author: timtreis

src/spatialdata_plot/pl/utils.py

@@ -2819,7 +2819,7 @@ def _validate_col_for_column_table(
                 # Try gene_symbols fallback before discarding this table
                 if gene_symbols is not None:
                     try:
-                        col_for_color = _resolve_gene_symbols(sdata[annotates], col_for_color, gene_symbols)
+                        _resolve_gene_symbols(sdata[annotates], col_for_color, gene_symbols)
                     except KeyError:
                         tables.remove(annotates)
                 else:
@@ -2832,6 +2832,13 @@ def _validate_col_for_column_table(
         table_name = next(iter(tables))
         if len(tables) > 1:
             logger.warning(f"Multiple tables contain column '{col_for_color}', using table '{table_name}'.")
+        # Resolve gene symbol to var_name using the selected table
+        if (
+            gene_symbols is not None
+            and col_for_color not in sdata[table_name].obs.columns
+            and col_for_color not in sdata[table_name].var_names
+        ):
+            col_for_color = _resolve_gene_symbols(sdata[table_name], col_for_color, gene_symbols)
     return col_for_color, table_name
 
 

tests/pl/test_render_shapes.py

@@ -1019,6 +1019,35 @@ def test_plot_can_color_shapes_by_gene_symbols(self, sdata_blobs: SpatialData):
         ).pl.show()
 
 
+def test_gene_symbols_auto_detect_table(sdata_blobs: SpatialData):
+    """gene_symbols resolves correctly without explicit table_name (#247)."""
+    sdata_blobs["table"].obs["region"] = pd.Categorical(["blobs_circles"] * sdata_blobs["table"].n_obs)
+    sdata_blobs["table"].uns["spatialdata_attrs"]["region"] = "blobs_circles"
+    sdata_blobs["table"].var["gene_symbol"] = ["GeneA", "GeneB", "GeneC"]
+    # No table_name — auto-detect path
+    sdata_blobs.pl.render_shapes("blobs_circles", color="GeneA", gene_symbols="gene_symbol").pl.show()
+    plt.close("all")
+
+
+def test_gene_symbols_missing_symbol_raises(sdata_blobs: SpatialData):
+    """gene_symbols raises KeyError when the symbol is not found (#247)."""
+    sdata_blobs["table"].obs["region"] = pd.Categorical(["blobs_circles"] * sdata_blobs["table"].n_obs)
+    sdata_blobs["table"].uns["spatialdata_attrs"]["region"] = "blobs_circles"
+    sdata_blobs["table"].var["gene_symbol"] = ["GeneA", "GeneB", "GeneC"]
+    with pytest.raises(KeyError, match="Unable to locate color key 'NoSuchGene'"):
+        sdata_blobs.pl.render_shapes("blobs_circles", color="NoSuchGene", gene_symbols="gene_symbol").pl.show()
+
+
+def test_gene_symbols_missing_column_raises(sdata_blobs: SpatialData):
+    """gene_symbols raises KeyError when the var column doesn't exist (#247)."""
+    sdata_blobs["table"].obs["region"] = pd.Categorical(["blobs_circles"] * sdata_blobs["table"].n_obs)
+    sdata_blobs["table"].uns["spatialdata_attrs"]["region"] = "blobs_circles"
+    with pytest.raises(KeyError, match="not found in `adata.var`"):
+        sdata_blobs.pl.render_shapes(
+            "blobs_circles", color="GeneA", table_name="table", gene_symbols="nonexistent_col"
+        ).pl.show()
+
+
 def test_groups_na_color_none_no_match_shapes(sdata_blobs: SpatialData):
     """When no elements match the groups, the plot should render without error."""
     sdata_blobs["blobs_polygons"]["cat_color"] = pd.Series(["a", "b", "a", "b", "a"], dtype="category")