Bio Spatial Transcriptomics Spatial Visualization

Version Compatibility

Reference examples tested with: squidpy 1.4+, scanpy 1.10+, anndata 0.10+, matplotlib 3.8+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Spatial Visualization

"Plot expression / clusters / a score on my tissue section" -> Render per-feature values at their real spatial coordinates, optionally over the histology image, without inventing structure the assay did not measure.

• Spot/capture fork (Visium, Visium HD, Slide-seq): scanpy.pl.spatial or squidpy.pl.spatial_scatter WITH the dataset's scalefactors and a spot_size/size set to the real capture diameter.
• Imaging/FOV fork (Xenium, MERFISH/MERSCOPE, CosMx): squidpy.pl.spatial_scatter with shape=None for the cell/molecule point cloud, or polygon shapes for segmentation overlays, or a platform viewer (Xenium Explorer, napari, Vitessce, TissUUmaps).

Governing Principle

Plotting differs by the platform-class fork, and rendering choices can manufacture pattern that is not in the data.

The first decision is which side of the fork the data sits on, because it selects the plotter and the meaning of marker size. Spot/capture data carries a histology image and a scalefactors block that maps array coordinates to image pixels; the plotted spot stands for a real capture spot (a 55 um Visium spot is a 1-10-cell mixture, not a cell) and the marker size should reflect that capture diameter. Imaging/FOV data is a point cloud of segmented cells or individual transcript molecules with no Visium-style hex lattice; forcing it through a spot plotter or oversizing markers paints continuous tissue coverage over what is actually sparse, discrete detections. Using the wrong plotter or an arbitrary spot size silently misrepresents the tissue.

The deeper trap is that several common rendering choices invent structure. Smoothing, kernel-density, kriging, or contouring a sparse spatial field produces a continuous surface that looks like high-resolution biology but is interpolated -- the apparent gradients and domains can be artifacts of the kernel, and any spatial statistic (Moran's I, domain calls) computed on the smoothed field is partly circular. Oversized markers are rhetorical: in scanpy.pl.spatial size is a scaling factor on the spot diameter, so inflating it merges neighbors and fakes contiguity the assay never resolved. A perceptually non-uniform colormap (jet/rainbow) invents banding and edges in a smooth gradient and is unreadable under color-vision deficiency, and silent vmin/vmax clipping can erase or exaggerate differences. Finally, UMAP/tSNE distances are NOT metric (the same caveat as single-cell/clustering) -- gaps and cluster spacing in an embedding carry no spatial meaning and must not be read as tissue conclusions. Honest spatial visualization shows the raw points, names the transform and any clipping, and never lets a plotting parameter assert biology the measurement did not contain.

Plot genre by platform fork

When competing rendering options exist (point cloud vs polygon overlay, sequential vs diverging colormap), verify the current platform viewer and Squidpy plotting docs before committing -- spatial tooling and platform exports change quickly.

Spot/Capture Plot with Real Scalefactors and Spot Size

Goal: Show expression or cluster labels at true spot positions on a spot/capture section with a marker size that reflects the capture geometry, not a guess.

Approach: Let sc.pl.spatial read the uns['spatial'] scalefactors so spot coordinates align to the histology image; size markers from the recorded spot diameter rather than an arbitrary constant.

import scanpy as sc
import squidpy as sq

# scalefactors live in adata.uns['spatial'][library_id]; sc.pl.spatial reads them automatically.
sc.pl.spatial(adata, color=['leiden', 'total_counts'], img_key='hires', alpha_img=0.6, ncols=2)

# A spot is a 1-10-cell MIXTURE, not a cell -- do not relabel spot clusters as cell types.
# squidpy resolves the scalefactor from library_id; size here is relative to the spot diameter.
sq.pl.spatial_scatter(adata, color='leiden', library_id='V1_Human_Lymph_Node', size=1.0)

Imaging/FOV Overlay (Point Cloud and Segmentation)

Goal: Render imaging-platform cells or molecules in their real micron coordinates without imposing a spot lattice they do not have.

Approach: Use sq.pl.spatial_scatter with shape=None for the segmented-cell point cloud (or polygon shapes when boundaries are stored), and overlay the registered image only when its transform is known.

# Imaging data is a point cloud, not a hex grid: shape=None plots cells as points in micron space.
# With no image, `size` is the ACTUAL dot size, not a scaling factor -- keep it small so sparse
# detections do not visually merge into fake continuous tissue.
sq.pl.spatial_scatter(adata, color='cell_type', shape=None, size=8, img=False)

# Overlay the registered morphology image only when the coordinate frame is trusted.
sq.pl.spatial_scatter(adata, color='EPCAM', shape=None, size=8, img=True, img_alpha=0.5)

Histology Coordinate-Frame Overlay

Goal: Place transcripts/spots on the H&E or DAPI image so each point lands on the histological structure it came from.

Approach: Map array/micron coordinates into image-pixel space with the correct scalefactor (or platform affine); never plot raw micron coordinates onto a pixel image. Inspect the alignment before trusting any structure read off the overlay.

# Spot/capture: hires-image pixel coords = spatial coords * tissue_hires_scalef.
library_id = list(adata.uns['spatial'].keys())[0]
scalef = adata.uns['spatial'][library_id]['scalefactors']['tissue_hires_scalef']
img = adata.uns['spatial'][library_id]['images']['hires']

import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(8, 8))
ax.imshow(img)                                   # image is in pixel space
coords_px = adata.obsm['spatial'] * scalef       # transform microns/array units -> pixels
ax.scatter(coords_px[:, 0], coords_px[:, 1], s=6, c='red')
ax.set_axis_off()                                # a small misalignment puts expression in the wrong structure

Honest Continuous Field (Colormap and No Interpolation)

Goal: Show a continuous score across the section truthfully -- visible raw points, a perceptually uniform colormap, and disclosed clipping.

Approach: Color each measured spot/cell directly (never interpolate between them), pick a perceptually uniform map, and state any vmin/vmax clip rather than letting it silently reshape the gradient.

# Color the MEASURED points only. Do NOT KDE/kriging/contour a sparse field -- that manufactures
# gradients and any Moran's I / domain call computed on the smoothed surface is partly circular.
sc.pl.spatial(adata, color='CD3D', cmap='viridis', vmin=0, vmax='p99')   # 'p99' clip is disclosed, not hidden

# Avoid jet/rainbow: perceptually non-uniform maps invent banding and fail color-vision-deficiency
# readers. Scientific colour maps (Crameri) are perceptually uniform; install cmcrameri to use them.
# import cmcrameri.cm as cmc; sc.pl.spatial(adata, color='CD3D', cmap=cmc.batlow)

Interactive Exploration

Large imaging sections and multi-resolution images are better explored interactively than in static panels. napari (image + points + shapes layers), Vitessce (web, multimodal), TissUUmaps (large image-plus-marker viewing), and the vendor Xenium Explorer / Xenium Panel viewer all pan-and-zoom over the full-resolution data. The same coordinate-frame discipline applies: points must be transformed into the viewer's pixel space (for spot/capture, multiply spatial coordinates by the relevant tissue_*_scalef).

import napari
library_id = list(adata.uns['spatial'].keys())[0]
img = adata.uns['spatial'][library_id]['images']['hires']
scalef = adata.uns['spatial'][library_id]['scalefactors']['tissue_hires_scalef']
viewer = napari.Viewer()
viewer.add_image(img, name='tissue')
viewer.add_points(adata.obsm['spatial'] * scalef, size=10, name='spots')   # transform into pixel space
napari.run()

Embedding Caveat

sc.pl.umap/sc.pl.tsne are legitimate for QC and cluster sanity-checks, but UMAP/tSNE distances are not metric: the size of gaps between clusters and the apparent spacing of points carry no quantitative meaning, and nothing spatial can be concluded from them. Read tissue structure off the spatial plot, never off the embedding (see single-cell/clustering for the full caveat).

Common Errors

Related Skills

• spatial-data-io - load the platform data and the histology image plus scalefactors that plotting depends on
• spatial-domains - produce the region labels rendered on the section
• spatial-statistics - compute Moran's I / neighborhood enrichment whose results are plotted here
• data-visualization/heatmaps-clustering - general perceptually-uniform colormap and figure conventions
• single-cell/clustering - the non-metric UMAP/tSNE distance caveat that applies to embeddings

References

• Palla G, Spitzer H, Klein M, et al. (2022) Squidpy: a scalable framework for spatial omics analysis. Nature Methods 19(2):171-178. DOI 10.1038/s41592-021-01358-2
• Wolf FA, Angerer P, Theis FJ (2018) SCANPY: large-scale single-cell gene expression data analysis. Genome Biology 19:15. DOI 10.1186/s13059-017-1382-0
• Marconato L, Palla G, Yamauchi KA, et al. (2025) SpatialData: an open and universal data framework for spatial omics. Nature Methods 22(1):58-62. DOI 10.1038/s41592-024-02212-x
• Crameri F, Shephard GE, Heron PJ (2020) The misuse of colour in science communication. Nature Communications 11:5444. DOI 10.1038/s41467-020-19160-7
• Chari T, Pachter L (2023) The specious art of single-cell genomics. PLoS Computational Biology 19(8):e1011288. DOI 10.1371/journal.pcbi.1011288