Raise on color name collision with column in render_* (#619)

When `color=<str>` was both a valid matplotlib color and a column name
in the element or an annotating table, the literal color silently won
and the column was ignored (only a default-hidden `logger.info` was
emitted). Now raise `ValueError` with disambiguation guidance: pass hex
(e.g. `"#ffa500"`), an RGB(A) tuple, or rename the column.

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -293,7 +293,9 @@ def render_shapes(
         -----
         - Empty geometries will be removed at the time of plotting.
         - An `outline_width` of 0.0 leads to no border being plotted.
-        - When passing a color-like to 'color', this has precedence over the potential existence as a column name.
+        - If ``color`` is a string that is both a matplotlib color name and a column name in the
+          element or an annotating table, a ``ValueError`` is raised. Disambiguate by passing
+          a hex string (e.g. ``"#ffa500"``) or an RGB(A) tuple, or by renaming the column.
 
         Returns
         -------

src/spatialdata_plot/pl/utils.py

@@ -2280,6 +2280,41 @@ def _validate_show_parameters(
             )
 
 
+def _check_color_column_collision(
+    sdata: SpatialData,
+    elements: list[str],
+    color: str,
+    element_type: str,
+) -> None:
+    """Raise if ``color`` is a color-like string that also names a column in the element or its tables."""
+    matches: list[str] = []
+    for el in elements:
+        if element_type in {"shapes", "points"}:
+            try:
+                el_cols = sdata[el].columns
+            except (KeyError, AttributeError):
+                el_cols = ()
+            if color in el_cols:
+                matches.append(f"element '{el}'")
+                continue
+        try:
+            tables = get_element_annotators(sdata, el)
+        except (KeyError, ValueError):
+            tables = set()
+        for t in tables:
+            adata = sdata[t]
+            if color in adata.obs.columns or color in adata.var_names:
+                matches.append(f"table '{t}' (annotating '{el}')")
+                break
+    if matches:
+        locations = ", ".join(sorted(set(matches)))
+        raise ValueError(
+            f"`color={color!r}` is ambiguous: it is a valid matplotlib color name AND a column "
+            f"name in {locations}. Disambiguate by either passing an unambiguous color form "
+            f"(hex string like '#ffa500' or an RGB(A) tuple), or by renaming the column."
+        )
+
+
 def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[str, Any]:
     colorbar = param_dict.get("colorbar", "auto")
     if colorbar not in {True, False, None, "auto"}:
@@ -2330,7 +2365,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         if not isinstance(color, str | tuple | list):
             raise TypeError("Parameter 'color' must be a string or a tuple/list of floats.")
         if _is_color_like(color):
-            logger.info("Value for parameter 'color' appears to be a color, using it as such.")
+            if isinstance(color, str):
+                _check_color_column_collision(param_dict["sdata"], param_dict["element"], color, element_type)
             param_dict["col_for_color"] = None
             param_dict["color"] = Color(color)
             if param_dict["color"].alpha_is_user_defined():

tests/pl/test_render_labels.py

@@ -550,3 +550,29 @@ def test_render_labels_disjoint_instance_ids_clear_error():
             sdata.pl.render_labels("lbl", color="cat", table_name="t").pl.show(ax=ax)
     finally:
         plt.close(fig)
+
+
+def test_render_labels_color_column_name_collision_raises():
+    # regression test for #619: color="orange" + obs column "orange" must raise.
+    arr = np.zeros((10, 10), dtype=np.int32)
+    arr[2:5, 2:5] = 1
+    arr[6:9, 6:9] = 2
+    obs = pd.DataFrame(
+        {
+            "region": pd.Categorical(["lbl"] * 2),
+            "instance_id": [1, 2],
+            "orange": pd.Categorical(["A", "B"]),
+        }
+    )
+    table = TableModel.parse(
+        AnnData(X=np.zeros((2, 1)), obs=obs),
+        region="lbl",
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(labels={"lbl": Labels2DModel.parse(arr, dims=["y", "x"])}, tables={"t": table})
+
+    with pytest.raises(ValueError, match=r"color='orange'.*ambiguous.*column"):
+        sdata.pl.render_labels("lbl", color="orange", table_name="t")
+
+    sdata.pl.render_labels("lbl", color="#ffa500", table_name="t")

tests/pl/test_render_points.py

@@ -1031,3 +1031,16 @@ def test_render_points_disjoint_instance_ids_clear_error():
             sdata.pl.render_points("pts", color="cat", table_name="t").pl.show(ax=ax)
     finally:
         plt.close(fig)
+
+
+def test_render_points_color_column_name_collision_raises():
+    # regression test for #619: color="orange" + element column "orange" must raise.
+    points = PointsModel.parse(
+        pd.DataFrame({"x": [1.0, 2.0, 3.0, 4.0], "y": [1.0, 2.0, 3.0, 4.0], "orange": [0.1, 0.2, 0.3, 0.4]})
+    )
+    sdata = SpatialData(points={"pts": points})
+
+    with pytest.raises(ValueError, match=r"color='orange'.*ambiguous.*column"):
+        sdata.pl.render_points("pts", color="orange")
+
+    sdata.pl.render_points("pts", color="#ffa500")

tests/pl/test_render_shapes.py

@@ -1378,6 +1378,33 @@ def test_render_shapes_disjoint_instance_ids_clear_error():
         plt.close(fig)
 
 
+def test_render_shapes_color_column_name_collision_raises():
+    # regression test for #619: color="orange" + column "orange" must raise rather than silently
+    # treat the value as a literal color and shadow the column.
+    n = 4
+    shapes = ShapesModel.parse(gpd.GeoDataFrame({"geometry": [Point(i, 0) for i in range(n)], "radius": [0.5] * n}))
+    obs = pd.DataFrame(
+        {
+            "region": pd.Categorical(["s"] * n),
+            "instance_id": list(range(n)),
+            "orange": pd.Categorical(["A", "B", "A", "B"]),
+        }
+    )
+    table = TableModel.parse(
+        AnnData(X=np.zeros((n, 1)), obs=obs),
+        region="s",
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(shapes={"s": shapes}, tables={"t": table})
+
+    with pytest.raises(ValueError, match=r"color='orange'.*ambiguous.*column"):
+        sdata.pl.render_shapes("s", color="orange")
+
+    sdata.pl.render_shapes("s", color="#ffa500")
+    sdata.pl.render_shapes("s", color=(1.0, 0.65, 0.0))
+
+
 def test_datashader_colorbar_range_matches_data(sdata_blobs: SpatialData):
     """Datashader colorbar range must not exceed the actual data range for shapes.