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

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

从 utils.py 中 _validate_col_for_column_table 附近（第 2838–2872 行）开始，检查 _locate_value 以及 render_shapes、render_labels 和 render_points 的颜色解析路径。使用最小示例验证可以选择 .obsm DataFrame 中的值，而无需将其复制到 obs，并为所选键语法和生成的颜色添加或更新覆盖测试。