GPTomics/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

| Plot genre | Spot/capture fork (Visium, Slide-seq) | Imaging/FOV fork (Xenium, MERFISH, CosMx) | Honesty pitfall to avoid | |------------|----------------------------------------|--------------------------------------------|--------------------------| | Expression / cluster on tissue | sc.pl.spatial (uses scalefactors) or sq.pl.spatial_scatter | sq.pl.spatial_scatter(shape=None) point cloud | Oversized spot_size/size faking coverage | | Histology overlay | sc.pl.spatial(img_key='hires'); scalefactor maps coords->pixels | sq.pl.spatial_scatter(img=True, img_res_key=...) with the registered image | Wrong coordinate frame (micron vs pixel) -> points off image | | Single-molecule / transcript map | not applicable (no molecule table) | scatter the transcript x,y table, or Xenium Explorer / napari | Treating segmented matrix as raw molecules | | Segmentation / boundary overlay | not applicable | sq.pl.spatial_scatter polygon shapes, or napari/TissUUmaps | Hiding segmentation error behind tidy cell polygons | | Continuous field / heatmap | per-spot color, NO interpolation | per-cell color, NO interpolation | KDE/kriging/contour manufacturing gradients | | Embedding (UMAP/tSNE) | sc.pl.umap for QC only | sc.pl.umap for QC only | Reading non-metric embedding distance as spatial |

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

| Symptom | Cause | Fix | |---------|-------|-----| | Spots overlap into a solid sheet; sparse signal looks continuous | spot_size/size set far above the real capture diameter | Size markers from the spot diameter; for imaging keep size small (it is the actual dot size when no image) | | Points land off the image or in the wrong tissue region | Plotting micron/array coordinates onto a pixel image without the scalefactor/affine | Transform coords -> pixels (* tissue_hires_scalef, or the platform affine) before overlay | | Smooth gradients/domains that vanish on the raw points | Field was KDE/kriged/contoured/imputed; pattern is the kernel, not the tissue | Plot measured points only; show raw alongside any smoothed view and disclose the kernel | | Banding/edges appear in a smooth field; figure unreadable in grayscale | jet/rainbow or other perceptually non-uniform colormap | Use a perceptually uniform map (viridis, or Crameri scientific colour maps via cmcrameri) | | Two conditions look very different for the same expression | Inconsistent or silent vmin/vmax between panels | Fix and disclose the color scale across panels (shared vmin/vmax) | | Imaging cells plotted on a hex/grid lattice or with empty image background | Spot plotter (sc.pl.spatial) or default shape used on imaging point-cloud data | Use sq.pl.spatial_scatter(shape=None); pass the registered image only with a known transform | | Conclusions drawn from gaps between UMAP clusters | Treating non-metric embedding distance as spatial/quantitative | Restrict spatial claims to the spatial plot; use UMAP for QC only | | Spot clusters labeled as cell types | A capture spot is a 1-10-cell mixture, not a cell | Label spot clusters as regions/niches; deconvolve for composition (spatial-deconvolution) | | Per-spot proportion/scatterpie map read as measured composition | Deconvolution output is a model estimate carrying reference and fit uncertainty | Present proportion maps as estimates; rare-type fractions are least reliable, so corroborate before reading them off the map (spatial-deconvolution) |

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