Raise on obs/var key collision in table-based coloring

When the same key existed in both `table.obs.columns` and `table.var_names`,
upstream `_get_table_origins` returned only the obs origin (elif chain),
silently masking gene expression with obs values. Catch the collision at
the renderer entry points and raise a descriptive ValueError naming both
locations so the user can disambiguate.

Fixes #621

Author: timtreis

src/spatialdata_plot/pl/render.py

@@ -58,6 +58,7 @@
 )
 from spatialdata_plot.pl.utils import (
     _ax_show_and_transform,
+    _check_obs_var_shadow,
     _convert_shapes,
     _datashader_canvas_from_dataframe,
     _decorate_axs,
@@ -370,6 +371,8 @@ def _render_shapes(
     groups = render_params.groups
     table_layer = render_params.table_layer
 
+    _check_obs_var_shadow(sdata, element, col_for_color, render_params.table_name)
+
     sdata_filt = sdata.filter_by_coordinate_system(
         coordinate_system=coordinate_system,
         filter_tables=bool(render_params.table_name),
@@ -766,6 +769,8 @@ def _render_points(
     groups = render_params.groups
     palette = render_params.palette
 
+    _check_obs_var_shadow(sdata, element, col_for_color, table_name)
+
     if isinstance(groups, str):
         groups = [groups]
 
@@ -1687,6 +1692,8 @@ def _render_labels(
     groups = render_params.groups
     scale = render_params.scale
 
+    _check_obs_var_shadow(sdata, element, col_for_color, table_name)
+
     sdata_filt = sdata.filter_by_coordinate_system(
         coordinate_system=coordinate_system,
         filter_tables=bool(table_name),

src/spatialdata_plot/pl/utils.py

@@ -64,7 +64,7 @@
 )
 from spatialdata._core.query.relational_query import _locate_value
 from spatialdata._types import ArrayLike
-from spatialdata.models import Image2DModel, Labels2DModel, SpatialElement, get_table_keys
+from spatialdata.models import Image2DModel, Labels2DModel, SpatialElement, TableModel, get_table_keys
 from spatialdata.transformations.operations import get_transformation
 from spatialdata.transformations.transformations import Scale, Translation
 from spatialdata.transformations.transformations import Sequence as TransformSequence
@@ -104,6 +104,34 @@
 }
 
 
+def _check_obs_var_shadow(
+    sdata: SpatialData | None,
+    element_name: str | None,
+    value_to_plot: str | None,
+    table_name: str | None,
+) -> None:
+    """Raise if `value_to_plot` exists in both `table.obs.columns` and `table.var_names`.
+
+    Upstream `_get_table_origins` uses an `elif` chain, so a key that lives in both
+    locations is silently resolved to `obs` — masking the user's likely intent of
+    plotting gene expression. Catch this here before any value fetch.
+    """
+    if value_to_plot is None or table_name is None or sdata is None or table_name not in sdata.tables:
+        return
+    table = sdata.tables[table_name]
+    if value_to_plot not in table.obs.columns or value_to_plot not in table.var_names:
+        return
+    region = table.uns[TableModel.ATTRS_KEY][TableModel.REGION_KEY]
+    annotates_element = element_name in region if isinstance(region, list) else element_name == region
+    if not annotates_element:
+        return
+    raise ValueError(
+        f"Color key '{value_to_plot}' is ambiguous: it exists in both "
+        f"`table['{table_name}'].obs.columns` and `table['{table_name}'].var_names`. "
+        "Rename one of them (or drop the obs column) so the intended source is unambiguous."
+    )
+
+
 def _gate_palette_and_groups(
     element_params: dict[str, Any],
     param_dict: dict[str, Any],

tests/pl/test_utils.py

@@ -422,6 +422,56 @@ def test_color_column_collision_on_annotating_table_raises():
     sdata.pl.render_shapes("s", color="#ffa500")
 
 
+def test_color_key_obs_var_shadow_raises():
+    # regression test for #621: when the same key exists in both `table.obs.columns`
+    # and `table.var_names`, upstream `_get_table_origins` silently returns only the
+    # obs origin (elif chain). Surface the ambiguity at the plotting layer instead.
+    pts = PointsModel.parse(pd.DataFrame({"x": [1.0, 2.0, 3.0, 4.0], "y": [1.0, 2.0, 3.0, 4.0]}))
+    obs = pd.DataFrame(
+        {
+            "instance_id": [0, 1, 2, 3],
+            "region": ["pts"] * 4,
+            "GeneA": [0.9, 0.8, 0.7, 0.6],
+        }
+    )
+    obs.index = obs.index.astype(str)
+    X = np.array([[1.0, 0.5], [0.8, 0.2], [0.3, 0.9], [0.1, 0.7]])
+    table = TableModel.parse(
+        AnnData(X=X, obs=obs, var=pd.DataFrame(index=["GeneA", "GeneB"])),
+        region=["pts"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(points={"pts": pts}, tables={"t": table})
+
+    with pytest.raises(ValueError, match=r"'GeneA'.*ambiguous.*obs\.columns.*var_names"):
+        sdata.pl.render_points("pts", color="GeneA", table_name="t").pl.show()
+
+    # Negative control: only in var → no error.
+    obs_var_only = pd.DataFrame(
+        {"instance_id": [0, 1, 2, 3], "region": ["pts"] * 4},
+        index=[str(i) for i in range(4)],
+    )
+    table_var_only = TableModel.parse(
+        AnnData(X=X, obs=obs_var_only, var=pd.DataFrame(index=["GeneA", "GeneB"])),
+        region=["pts"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata_var_only = SpatialData(points={"pts": pts}, tables={"t": table_var_only})
+    sdata_var_only.pl.render_points("pts", color="GeneA", table_name="t").pl.show()
+
+    # Negative control: only in obs → no error.
+    table_obs_only = TableModel.parse(
+        AnnData(X=X, obs=obs, var=pd.DataFrame(index=["G1", "G2"])),
+        region=["pts"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata_obs_only = SpatialData(points={"pts": pts}, tables={"t": table_obs_only})
+    sdata_obs_only.pl.render_points("pts", color="GeneA", table_name="t").pl.show()
+
+
 def test_explicit_table_name_honored_when_element_has_same_column():
     # regression test for #620: explicit table_name= must not be silently
     # discarded when the element has a same-named column with different values.