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

Commencez dans utils.py autour de _validate_col_for_column_table (lignes 2838–2872) et examinez _locate_value ainsi que les chemins de résolution des couleurs de render_shapes, render_labels et render_points. Utilisez l’exemple minimal pour vérifier qu’une valeur de DataFrame .obsm peut être sélectionnée sans la copier dans obs, et ajoutez ou mettez à jour la couverture pour la syntaxe de clé choisie et les couleurs obtenues.

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