Feature request: support color=["gene1","gene2"] for multi-panel and multi-channel spatial plots

[timtreis]

Feature request: support color=["gene1","gene2"] for multi-panel and multi-channel spatial plots

Summary

All render_* functions accept only a single color= value. There is no way to generate multi-panel plots automatically from a list of columns (like sc.pl.umap(color=["gene1","gene2"]) in scanpy), and no way to create multi-gene composite overlays (like Xenium Explorer's multi-stain panel). This is consistently the most-requested missing feature across the issue tracker.

Environment

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

Evidence from Issues

• Plotting multiple genes  #321: "It would be nice for the parameter color to support gene list" — users expect scanpy-style color=['gene1','gene2'] to produce one panel per gene.
• Failing to recreate Xenium Exlorer-style multi-stain segmentation panel plot #534: Users need per-marker spatial panels (Xenium Explorer-style) but must write extensive boilerplate.
• Feature: PCA aggregation for n >= 4 channels in render_images #450: Requests per-channel-norm plots as separate panels when compositing is not possible (N≥4 channels).
• Custom title when multiple coordinate system present and no coordinate system specified #269: Consequence of no multi-panel support: ncols parameter in show() has no documented use case.

Current Workaround

Verbose boilerplate required for just 3 genes:

import matplotlib.pyplot as plt
import spatialdata as sd
import spatialdata_plot

sdata = sd.datasets.blobs()
genes = ["feature_0", "feature_1", "feature_2"]

fig, axes = plt.subplots(1, len(genes), figsize=(15, 5))
for ax, gene in zip(axes, genes):
    sdata.pl.render_shapes("blobs_circles", color=gene).pl.show(ax=ax)
    ax.set_title(gene)
plt.tight_layout()

Desired API

Consistent with scanpy's color= list convention:

import spatialdata as sd
import spatialdata_plot

sdata = sd.datasets.blobs()

# Multi-panel: one subplot per gene
sdata.pl.render_shapes("blobs_circles", color=["feature_0", "feature_1", "feature_2"]).pl.show(ncols=3)

# Multi-channel composite: overlay two annotation columns
sdata.pl.render_labels("blobs_labels", color=["cat1", "cat2"]).pl.show()

Proposed Behavior

• color=["gene1","gene2"] auto-creates a subplot grid (respecting ncols=) with one panel per gene, matching sc.pl.umap(color=[...]) behavior.
• ncols in show() controls how many panels fit per row.
• Each panel shares the same spatial extent and coordinate system.
• The existing ncols parameter in show() — currently undocumented as functional — becomes the natural row-width control for this feature.

Related

Issues #321, #450, #534. The ncols parameter in show() is currently undocumented as functional.

Labels: enhancement, priority: high

---

Triage tier: Tier 2