No support for .obsm keys as color source in render functions

Start in utils.py around _validate_col_for_column_table (lines 2838–2872) and inspect _locate_value plus the render_shapes, render_labels, and render_points color-resolution paths. Use the minimal example to verify an .obsm DataFrame value can be selected without copying it into obs, and add or update coverage for the chosen key syntax and resulting colors.

No support for .obsm keys as color source in render functions

Environment: spatialdata-plot 0.3.4.dev (main, commit 5cfedc7), Python 3.13

---

Problem

render_shapes, render_labels, and render_points resolve color= from table.obs columns and table.var_names (gene expression), but they do not check table.obsm. Any per-cell metric stored in .obsm — spatial QC scores, embedding coordinates, tiling statistics, cell neighborhood features — cannot be used for coloring.

Users must work around this by manually copying the .obsm column into .obs, which pollutes the AnnData object and requires extra bookkeeping.

This is tracked in GitHub issue #587.

---

Minimal reproducible example

import matplotlib; matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np, pandas as pd, geopandas as gpd, anndata as ad
import dask; dask.config.set({"dataframe.query-planning": False})
from shapely.geometry import box
import spatialdata as sd
from spatialdata.models import ShapesModel, TableModel
import spatialdata_plot

shapes = ShapesModel.parse(gpd.GeoDataFrame(
    {"geometry": [box(i, 0, i+1, 1) for i in range(3)], "radius": [0.5]*3},
    geometry="geometry"
))
obs = pd.DataFrame({
    "region": pd.Categorical(["s"]*3),
    "instance_id": [0, 1, 2],
})
adata = ad.AnnData(X=np.zeros((3, 1)), obs=obs)
# Per-cell QC metrics stored in obsm — cannot currently use for coloring
adata.obsm["spatial_qc"] = pd.DataFrame(
    {"n_counts": [100.0, 250.0, 50.0], "density": [0.8, 0.6, 0.9]},
    index=adata.obs_names
)
table = TableModel.parse(adata, region="s", region_key="region", instance_key="instance_id")
sdata = sd.SpatialData(shapes={"s": shapes}, tables={"t": table})

fig, ax = plt.subplots()
# Desired: sdata.pl.render_shapes("s", color="spatial_qc:n_counts").pl.show(ax=ax)
# Actual workaround needed:
adata.obs["n_counts"] = adata.obsm["spatial_qc"]["n_counts"].values
sdata.pl.render_shapes("s", color="n_counts").pl.show(ax=ax)

---

Expected behaviour

A syntax like color="spatial_qc:n_counts" (or equivalent) that lets users specify an obsm key and column directly, without manually copying into obs.

Actual behaviour

KeyError: "Unable to locate color key 'spatial_qc:n_counts' for element 's'."

.obsm is never checked in _validate_col_for_column_table (utils.py:2838–2872).

---

Feature request

Extend the color key resolution in _validate_col_for_column_table (and/or _locate_value) to support .obsm DataFrames. Possible syntaxes:

• color="obsm_key:column" — explicit separator
• color="column" with fallback to obsm keys when obs lookup fails
• A dedicated obsm_key= parameter

This would unlock a common workflow where spatial QC, embeddings, or multi-modal per-cell metrics are stored in .obsm and need to be visualized spatially.

---

Triage tier: Tier 3