Spatial Transcriptomics Technologies

Evolution of Spatial Transcriptomics (2015–2025)

Two kinds of milestones are mixed in most timelines and are kept apart here: a Paper marks the first peer-reviewed description of a method; a Product marks when a commercial platform became available to labs, which is often years later and under a different name. The coloured tag gives the measurement route: Sequencing array Imaging in situ Region selection Multi-modal / analysis.

1. 2015
   • PaperImaging MERFISH — error-robust combinatorial FISH (Chen et al., Science)
2. 2016–2017
   • PaperSequencing Spatial Transcriptomics (ST) — 100 µm barcoded spots (Ståhl et al., Science 2016)
   • PaperRegion Geo-seq — laser-capture microdissection + low-input RNA-seq on cryosections (Peng et al., Dev Cell 2016; protocol Chen et al., Nat Protoc 2017); LCM-seq (Nichterwitz et al., Nat Commun 2016)
3. 2018
   • PaperImaging STARmap — hydrogel-embedded 3D in situ sequencing (Wang et al., Science)
4. 2019
   • PaperSequencing Slide-seq (10 µm beads, Science) and HDST (2 µm beads, Nat Methods)
   • PaperImaging seqFISH+ — 10,000 genes (Eng et al., Nature)
   • ProductSequencing 10x Visium — commercial successor of ST, 55 µm spots
   • ProductRegion NanoString GeoMx DSP — ROI-based profiling (method paper Merritt et al., Nat Biotechnol 2020)
5. 2021
   • PaperSequencing Slide-seqV2 (Nat Biotechnol) and Seq-Scope (sub-micron, Cell)
   • ProductImaging Vizgen MERSCOPE — commercial MERFISH
6. 2022
   • PaperSequencing Stereo-seq — DNB arrays, 0.5 µm pitch, cm-scale chips (Chen et al., Cell)
   • PaperProductImaging CosMx SMI — paper (He et al., Nat Biotechnol) and commercial launch in the same year
   • ProductImaging 10x Xenium — commercial in situ platform
   • ProductSequencing Visium CytAssist — probe-based FFPE workflow
7. 2023
   • PaperMulti-modal SPOTS (protein + RNA, Nat Biotechnol) and STARmap PLUS (transcript + protein in situ, Nat Neurosci)
8. 2024
   • ProductSequencing 10x Visium HD — continuous 2 µm grid (announced 2023, shipped 2024)
   • ProductImaging Xenium Prime 5K — 5,000-gene panels
   • PaperAnalysis BANKSY — joint cell typing + domain segmentation (Nat Genet)
9. 2025
   • PaperImaging Deep-STARmap / Deep-RIBOmap — 60–200 µm thick tissue (Nat Methods)
   • PaperMulti-modal ESPRESSO — spatiotemporal live-cell omics (Nat Methods)
   • ProductImaging MERSCOPE Ultra — throughput / sensitivity upgrade

Product years are first commercial availability as announced by vendors and can differ by region and early-access programme. Resolution is deliberately not plotted on this timeline — see what “resolution” means for each platform.

What is Spatial Transcriptomics?

Spatial transcriptomics refers to a collection of methods that measure gene expression while preserving the spatial location of transcripts within tissues. Unlike traditional RNA-seq that requires tissue homogenization (losing spatial information) or single-cell RNA-seq that requires cell dissociation (losing tissue context), spatial transcriptomics maintains the native tissue architecture while profiling the transcriptome.

Why Spatial Context Matters

• Tissue Architecture Understanding: Cells behave differently based on their location - a cancer cell at the tumor edge behaves differently than one in the center
• Cell-Cell Interactions: Understanding signaling between neighboring cells requires knowing their spatial relationships (ligand-receptor pairs)
• Microenvironment Mapping: Immune cells, stromal cells, and parenchymal cells form functional niches that can only be studied in spatial context
• Disease Heterogeneity: Tumors, inflammatory lesions, and developmental abnormalities show spatial patterns that inform diagnosis and treatment
• 3D Organization: Tissues are three-dimensional; understanding cell clustering and connectivity patterns requires volumetric analysis

Four Measurement Routes

Platforms differ less in brand than in how they decide where an RNA came from: a barcode printed on a surface (sequencing arrays), the position of a fluorescent spot in a microscope image (imaging in situ), or a region a person chose and physically or optically isolated before sequencing (region selection). Multi-modal methods extend any of these with protein, translation, 3D, or time.

Technology Comparison Guide

Figure 4. Technical workflows across three approaches. Left (Array-based Capture): tissue permeabilization → mRNA capture on barcoded spots → reverse transcription → library prep → demultiplexing; output: Spot × Gene matrix. Center (high-density arrays whose barcode positions are decoded before the tissue is placed): spatial barcode sequencing → tissue overlay → mRNA capture → sequencing → mapping; output: a very fine pixel × gene matrix that is normally binned or cell-segmented before analysis. The ★ in the image marks the whole-transcriptome + sub-micron capture combination; it is a design feature, not a ranking. Right (Imaging-based): probe hybridization → platform-specific detection (combinatorial/RCA/ISS) → cyclic imaging → barcode decoding → single-molecule localization; output: (x, y, gene) coordinates. Numbers in the image are approximate; the current panel sizes are given in Figure 2 and the table below. Region-selection methods (GeoMx, LCM-seq, Geo-seq) are not drawn here — their workflow is “image → choose regions → collect RNA → sequence each region as a library”.

Resolution vs Coverage Trade-off

Platform Fit: What Actually Decides the Choice

Resolution and gene number are only two of the constraints. In practice the sample type, how much tissue you need to cover, how many biological samples you can afford, whether the section must stay intact for histology, and which instruments your core facility runs often decide first. The table keeps native feature (a platform specification) separate from the analysis unit (what you will actually model).

Indicative values as of 2026; vendors revise panel sizes, chip formats, and sample-type support frequently, so check current datasheets before ordering. Cost is described relatively because list prices vary by institution and region.

Choosing the Right Technology

Work through the questions below with your own study in mind. They replace the old resolution-first flowchart: in real projects the number of biological samples, the sample type, and whether you already know the genes usually narrow the field before resolution does.

1. How many biological samples do you need?

   • Group comparisons need several donors / animals per group (see Experimental design). Multiply per-sample cost by that n first.
   • Many samples → lower-cost-per-sample formats (Visium, GeoMx, imaging on tissue microarrays or multiple sections per slide).
   • One or two reference specimens (atlas, method development) → you can afford large-area or high-plex runs.

2. What is the sample, and how good is its RNA?

   • FFPE archives → probe-based: Visium / Visium HD (CytAssist), Xenium, CosMx, MERSCOPE, GeoMx. Check DV200.
   • Fresh frozen → all of the above plus poly-A capture (Slide-seq, Stereo-seq, Visium 3′) and LCM-seq / Geo-seq.
   • Thick or 3D tissue → Deep-STARmap, or serial sections registered afterwards.

3. Do you already know which genes matter?

   • No (discovery) → whole transcriptome: sequencing arrays, GeoMx WTA, LCM-seq / Geo-seq.
   • Yes (validation, cell mapping from an existing scRNA-seq atlas) → targeted imaging panel — but confirm the panel contains markers for every cell type present, not only the ones you care about.

4. At what spatial scale does the biology happen?

   • Tissue domains, gradients, layers (>50 µm) → Visium, GeoMx, Stereo-seq bins.
   • Cell neighbourhoods and contacts → imaging platforms, or Visium HD / Stereo-seq with cell segmentation.
   • Subcellular RNA localization → imaging platforms.

5. How much tissue, and do you know where to look?

   • Whole section or unknown location → tiling platforms; compare capture area (6.5 mm Visium frames vs cm-scale Stereo-seq chips vs ~1–2 cm² imaging areas) with your specimen.
   • A few predefined compartments (glomeruli, tumour margin, germ-layer position) → GeoMx or LCM-seq / Geo-seq give deeper profiles per region.

6. Do you need protein, morphology, or other modalities?

   • Protein on the same section → CosMx, GeoMx, Xenium protein, SPOTS, STARmap PLUS.
   • H&E or IF on the very same cells afterwards → non-destructive imaging platforms.
   • Translation or time → Deep-RIBOmap, ESPRESSO (academic protocols).

7. What can you actually run?

   • Instrument access at your core (CytAssist, Xenium, CosMx, MERSCOPE, GeoMx, LCM microscope) and turnaround time.
   • Sequencing budget (arrays) vs consumable / panel cost (imaging), plus storage and compute for 10⁵–10⁶-cell datasets.
   • Pilot one section before committing a full cohort.

Common Starting Points

Experimental Design & the Statistical Unit

A single Visium section yields thousands of spots and an imaging run hundreds of thousands of cells, which makes it tempting to treat every spot or cell as a data point in a group comparison. They are not independent: neighbouring spots share cells, diffusion, and tissue microenvironment (that spatial autocorrelation is exactly what Moran's I detects), and every observation on a section shares the same donor, fixation, section thickness, and slide chemistry. For comparisons between conditions, the replicate is the patient, animal, or independent biological specimen — not the spot or cell. Treating thousands of correlated locations as n is pseudoreplication: standard errors shrink, p-values become tiny, and a difference between two donors gets reported as a difference between two diseases.

1. Donor / patient / animalIndependent biology; the unit that varies between conditions.
   this is n
2. Tissue block / regionDifferent anatomical sites from one donor; nested within donor.
   not independent
3. Section / capture areaSerial sections are technical replicates; slide and run add batch effects.
   technical replicate
4. Spots / bins / cellsSpatially autocorrelated measurements within one section.
   not n

Design rules

• Plan replication at the biological level before generating data. Decide the comparison (condition, region, cell type) and how many donors per group you can afford; more donors with one section each usually beats fewer donors with many sections.
• Balance conditions across slides, capture areas, and run days. A Visium slide holds several capture areas and an imaging run takes several sections — put cases and controls on every slide so condition is not confounded with batch.
• Treat serial sections as technical replicates. Average or model them within donor; they measure reproducibility, not biological variation.
• Predefine region or ROI selection. For GeoMx, LCM-seq, and Geo-seq, write the anatomical criteria for choosing regions before looking at expression, and blind selection when possible.
• Aggregate, then test across donors. Pseudobulk counts per donor × domain (or cell type), then use DESeq2 / edgeR / limma-voom with donor as the replicate; alternatively a mixed model with a random effect for donor (and section).
• Within-section statistics are descriptive. A Moran's I or neighbourhood-enrichment p-value describes one section. To compare conditions, compute the statistic per section, summarize per donor, and test those summaries across donors.
• Report every level. Donors per group, sections per donor, and spots/cells per section, plus which level each test used.

# adata: all sections concatenated; obs has "donor", "condition", "section", "domain"
import scanpy as sc

# 1. Pseudobulk: sum RAW counts per donor x domain (sections of a donor are pooled)
pb = sc.get.aggregate(adata, by=["donor", "condition", "domain"],
                      func="sum", layer="counts")
pb.X = pb.layers["sum"]

# 2. Test one domain across donors (n = donors, not spots)
from pydeseq2.dds import DeseqDataSet
from pydeseq2.ds import DeseqStats
sub = pb[pb.obs["domain"] == "tumor_margin"].copy()
dds = DeseqDataSet(counts=sub.to_df().round().astype(int),
                   metadata=sub.obs, design="~condition")
dds.deseq2()
res = DeseqStats(dds, contrast=["condition", "tumor", "normal"])
res.summary()

# 3. Spatial statistics: one value per section, then compare across donors
#    (e.g. Moran's I of a gene per section -> mean per donor -> t-test / Wilcoxon on donors)

Further reading: Kurogi et al., “Ten quick tips for spatial transcriptomics analysis”, PLOS Comput Biol 2026; Squair et al., “Confronting false discoveries in single-cell differential expression”, Nat Commun 2021; Zimmerman et al., “A practical solution to pseudoreplication bias in single-cell studies”, Nat Commun 2021.

Landmark Papers Organized by Methodological Approach

1. Sequencing-Based Spatial Arrays (Capturing RNA onto surfaces)

Why these are grouped: These methods work by placing a tissue section onto a slide printed with barcoded capture spots (like beads or DNA nanoballs). The RNA is released from the tissue, captured on the surface, and then sequenced off-slide. The resolution is determined by the physical size and density of the capture spots on the array.

2. Imaging-Based In Situ Technologies (Visualizing RNA directly in tissue)

Why these are grouped: Instead of capturing RNA onto a slide, these methods leave the RNA inside the tissue cells. They use fluorescent probes and sophisticated microscopes to capture images of individual RNA molecules over multiple rounds of hybridization. They offer very high (subcellular) resolution but usually target a predefined panel of genes rather than the whole transcriptome.

3. Beyond 2D RNA: Multi-Modal, 3D, and Temporal Expansions

Why these are grouped: These papers represent the "next frontiers" of spatial biology. They push beyond standard 2D transcriptomics by adding new modalities (like proteins or active translation), analyzing thick 3D tissues, or adding the fourth dimension of time (live-cell tracking).

4. Benchmarking, Biological Application, and Future Outlook

Why these are grouped: These papers are less about inventing a new method and more about making sense of the existing ones. They include direct head-to-head comparisons of platforms, deep biological applications demonstrating real-world utility, and high-level perspectives on where the field is headed.

Common Analysis Workflows

← swipe, or tap the figure to open it full size →

Figure 7. Data output formats across platforms. Panel A (Sequencing-based): Spot × Gene count matrix with coordinates; high-res platforms require segmentation (⚠). Formats: MTX, H5AD, Parquet. Panel B (Imaging-based): transcript coordinate table (transcript_id, x, y, gene); requires cell segmentation. Formats: Parquet, CSV, Zarr. Panel C (Unified): all platforms converge to Cell × Gene matrix with spatial coordinates in AnnData/H5AD structure containing X (counts), obs (cell metadata), var (gene metadata), obsm (spatial coordinates), layers, and uns (images).

Figure 8. Platform-specific computational challenges. Low-res Sequencing (Visium): deconvolution, reference integration; tools: cell2location, RCTD; difficulty: medium. High-res Sequencing (Visium HD, Stereo-seq): cell segmentation (⚠), scalability, binning strategy; tools: Cellpose, Baysor; difficulty: high. Imaging-based: cell segmentation, assignment errors (~5-15%), panel limitations; tools: Cellpose, Baysor, StarDist; difficulty: high. ROI-based (GeoMx): low sample size, cell mixtures in AOIs; difficulty: low-medium (computation), high (statistics). Shared challenges (all platforms): batch effects, normalization, spatial statistics, cell-cell interactions.

1. Data Processing & Quality Control

• Image Registration: Align multi-round images using fiducial markers or amplicon positions
• Deconvolution: Enhance resolution using PSF-based methods (Huygens, deconvolution algorithms)
• Spot/Barcode Calling: Detect transcripts using local maxima detection, barcode decoding with error correction
• Cell Segmentation: Watershed, CellPose, or Baysor for single-cell boundaries

2. Cell Type Annotation

• Reference-Based: Transfer labels from scRNA-seq using FuseMap, Harmony, or Cell2location
• Unsupervised: Louvain/Leiden clustering on spatial features followed by marker gene validation
• Deconvolution: SpatialDecon, RCTD (Robust Cell Type Decomposition; Cable et al., Nat Biotechnol 2021), or Cell2location for spot-level cell type mixtures

3. Spatial Analysis

• Neighborhood Analysis: Squidpy for cellular interaction scores, Delaunay triangulation for neighbors
• Spatial Domains: BayesSpace, HMRF, SpaGCN, BANKSY (joint cell-typing + domain segmentation), or GraphST (graph self-supervised clustering) for identifying tissue regions
• Ligand-Receptor: CellChat (v2 has a spatial mode), CellPhoneDB, or spatially constrained tools such as COMMOT to prioritize candidate cell–cell communication — see the caveat below
• 3D Analysis: Distance transform watershed, volumetric clustering, spatial statistics

4. Foundation Model-Informed Spatial Analysis (2025-2026)

• Nicheformer (Nat Methods 2025) — pretrained jointly on 57M dissociated + 53M spatial cells; zero-shot niche and cell-type annotation transfer across tissues without retraining.
• scGPT spatial embedding — map spatial cells into a scGPT latent space learned from atlas-scale scRNA-seq for annotation without a matched local reference.
• Key use case: transfer labels from a well-annotated brain atlas onto a new spatial FFPE tumor section that has no matched scRNA-seq reference of its own.

Key Software Packages

🛠️ Hands-On Practice

The walkthrough below takes a Visium slide from raw spot counts to spatial statistics using Python/Scanpy/Squidpy — QC, normalization, clustering, plotting clusters back onto the tissue image, building a spatial neighbor graph, ranking spatially variable genes with Moran's I, and testing which cluster pairs sit next to each other. The same Squidpy calls apply to imaging-based data (Xenium, MERFISH, CosMx) once transcripts have been segmented into cells; the differences are noted at each step.

Environment & packages

Squidpy sits on top of Scanpy/AnnData and adds the spatial graph, spatial statistics, and image-aware plotting. For Xenium, MERFISH, or any multi-modal experiment (image + transcripts + polygons), spatialdata and its readers (spatialdata-io) are the better container because they keep coordinate transforms, segmentation shapes, and image pyramids aligned rather than flattening everything into adata.obsm["spatial"].

# conda / mamba recommended
conda create -n spatial python=3.10 -y
conda activate spatial

pip install scanpy squidpy leidenalg
# multi-modal / imaging platforms (Xenium, MERFISH, CosMx)
pip install spatialdata spatialdata-io spatialdata-plot
# spot deconvolution (GPU strongly recommended)
# pip install cell2location            # or run RCTD / spacexr in R
# transcript-aware segmentation
# pip install cellpose                 # Baysor is a separate Julia binary

Hardware. A single Visium section (~3–5k spots) runs comfortably on a laptop with 8 GB RAM. Visium HD (2 µm bins), Stereo-seq, and Xenium runs reach 10⁵–10⁶ cells or bins and need 32–128 GB RAM plus backed/Zarr-chunked I/O. Deconvolution with cell2location is a variational-inference fit and effectively needs a GPU; RCTD is CPU-only but slower.

Data structures & formats

• Spot-based (Visium, Visium HD, Slide-seq, Stereo-seq) — the observation is a barcoded area, not a cell. A Visium spot is ~55 µm across (100 µm center-to-center) and typically contains 1–10 cells, so adata.X rows are cell-type mixtures; recovering per-cell-type abundance requires deconvolution (cell2location, RCTD, SPOTlight) against a matched scRNA-seq reference. Slide-seq (10 µm beads), Stereo-seq (0.5 µm DNB, usually binned), and Visium HD (2 µm bins) are finer but still not cell objects until binned or segmented.
• Imaging-based (Xenium, MERFISH, CosMx) — the primary output is a transcript table (transcript_id, x, y, z, gene, qv), and cells only exist after segmentation. Resolution is genuinely single-cell, so segmentation quality is the limiting factor, not spot size. The trade-off is a targeted panel (Xenium 300–480 genes plus add-ons or 5,000 with Xenium Prime; CosMx 1,000–6,000; MERSCOPE up to ~1,000) rather than the whole transcriptome.
• AnnData — the convergence point for both families: adata.X (counts), adata.obs (spot/cell metadata), adata.var (genes), adata.obsm["spatial"] (an n × 2 array of x/y coordinates in the full-resolution image frame), and adata.uns["spatial"] (H&E images, scale factors, spot diameter).
• Scale factors matter. scalefactors_json.json maps full-resolution pixel coordinates to the hires/lowres thumbnails; plotting with the wrong img_key/scale factor silently offsets every spot from the tissue.
• SpatialData / OME-Zarr — for Xenium and multi-sample studies: labels (segmentation masks), shapes (cell/nucleus polygons), points (transcripts), images, and tables held in one store with explicit coordinate transformations, so a re-segmentation does not desynchronize the table from the image.
• Spatial graph — sq.gr.spatial_neighbors() writes adata.obsp["spatial_connectivities"] and adata.obsp["spatial_distances"]. Every downstream spatial statistic (Moran's I, neighborhood enrichment, Ripley) reads from this graph, so its construction is a modeling choice, not boilerplate.

Minimal code walkthrough

Load a Visium H&E dataset, run standard QC and normalization, cluster with Leiden, project clusters back onto the tissue, build a hexagonal-grid neighbor graph, score spatially variable genes with Moran's I, and test which clusters are spatial neighbors more often than chance.

import scanpy as sc
import squidpy as sq
import numpy as np

# 1. Load data. The bundled demo (mouse brain, Visium H&E) ships coordinates,
#    the H&E image, and scale factors already wired into AnnData.
adata = sq.datasets.visium_hne_adata()
#    For your own SpaceRanger output instead:
#    adata = sc.read_visium("outs/")          # expects filtered_feature_bc_matrix.h5
#    adata.var_names_make_unique()
#    For Xenium / MERFISH, read via spatialdata_io and pull out the cell table:
#    import spatialdata_io as sdio
#    sdata = sdio.xenium("xenium_output/")    # keeps transcripts + polygons + image
#    adata = sdata.tables["table"]            # cells x panel genes, post-segmentation

print(adata)                                  # obsm["spatial"], uns["spatial"] present
print(adata.obsm["spatial"][:3])              # full-res pixel coords, NOT microns

# 2. QC. Same metrics as scRNA-seq, but interpret per SPOT, not per cell:
#    a low-count spot is often edge/low-cellularity tissue, not a dead cell.
adata.var["mt"] = adata.var_names.str.startswith(("MT-", "mt-"))
sc.pp.calculate_qc_metrics(adata, qc_vars=["mt"], inplace=True, log1p=True)
sc.pl.violin(adata, ["total_counts", "n_genes_by_counts", "pct_counts_mt"],
             jitter=0.4, multi_panel=True)

#    Filter gently. Aggressive thresholds carve holes in the tissue map and
#    break the neighbor graph. Inspect counts IN SPACE before choosing cutoffs.
sq.pl.spatial_scatter(adata, color="total_counts", img_alpha=0.5)
adata = adata[adata.obs["total_counts"] > 500].copy()
sc.pp.filter_genes(adata, min_cells=10)

# 3. Normalize + log1p. Keep raw counts around: deconvolution (cell2location,
#    RCTD) and most spatially-variable-gene models require raw integers.
adata.layers["counts"] = adata.X.copy()
sc.pp.normalize_total(adata, inplace=True)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
#    NOTE: skip HVG selection for targeted panels (Xenium/MERFISH) — every gene
#    in a 300-plex panel was already chosen to be informative.

# 4. Expression-space clustering (spatially agnostic on purpose — this is the
#    baseline you compare spatial-domain methods like BayesSpace/SpaGCN against).
sc.pp.pca(adata, n_comps=50)
sc.pp.neighbors(adata)                        # EXPRESSION knn, not spatial
sc.tl.umap(adata)
sc.tl.leiden(adata, resolution=1.0, key_added="cluster")

# 5. Put the clusters back on the tissue. This is the plot that tells you
#    whether transcriptomic clusters correspond to real anatomy.
sq.pl.spatial_scatter(adata, color="cluster", size=1.3, img_alpha=0.6)

# 6. Spatial neighbor graph. Visium spots sit on a hex lattice -> 6 neighbors.
sq.gr.spatial_neighbors(adata, coord_type="grid", n_neighs=6)
#    Imaging platforms (irregular cell centroids) use a generic graph instead:
#    sq.gr.spatial_neighbors(adata, coord_type="generic", delaunay=True)
#    or radius-based, which is more interpretable in microns:
#    sq.gr.spatial_neighbors(adata, coord_type="generic", radius=30.0)
print(adata.obsp["spatial_connectivities"].shape)

# 7. Spatially variable genes via Moran's I. Positive I = neighboring spots
#    have similar expression, i.e. the gene forms spatial structure.
#    Run on the normalized layer; permutations give the empirical p-value.
sq.gr.spatial_autocorr(adata, mode="moran", genes=adata.var_names[adata.var.highly_variable],
                       n_perms=100, n_jobs=4)
svg = adata.uns["moranI"].sort_values("I", ascending=False)
print(svg.head(10)[["I", "pval_norm_fdr_bh"]])
sq.pl.spatial_scatter(adata, color=list(svg.index[:4]), img_alpha=0.4)

# 8. Neighborhood enrichment: which cluster pairs are adjacent more (or less)
#    often than expected under label permutation on the SAME graph?
sq.gr.nhood_enrichment(adata, cluster_key="cluster")
sq.pl.nhood_enrichment(adata, cluster_key="cluster", method="ward")
#    Complementary summaries on the same graph:
#    sq.gr.co_occurrence(adata, cluster_key="cluster")   # vs. distance, graph-free
#    sq.gr.ripley(adata, cluster_key="cluster", mode="L")

# 9. Deconvolution — REQUIRED for spot-based platforms before any statement
#    about cell types. A Leiden "cluster" on Visium is a spot NEIGHBORHOOD, not
#    a cell type. Fit cell2location (or RCTD in R) against a matched scRNA-seq
#    reference, then treat the per-spot abundances as the cell-type signal:
#    import cell2location
#    cell2location.models.RegressionModel.setup_anndata(ref_adata, labels_key="cell_type")
#    ... fit reference signatures, then Cell2location(adata_vis, ...).train()
#    -> adata.obsm["q05_cell_abundance_w_sf"]  # spots x cell types
#    Imaging platforms skip this: after segmentation, cells are annotated
#    directly with standard label transfer.

adata.write_h5ad("visium_spatial_processed.h5ad")

Common pitfalls & tips

• Spots and cells are not replicates. The walkthrough above analyses one section, so every p-value in it (Moran's I, neighbourhood enrichment) describes that section only. Comparing conditions needs several donors per group and a test at the donor level — pseudobulk per donor × domain or a mixed model. See Experimental Design ↑
• A ligand–receptor hit is a candidate, not a mechanism. Co-localization plus co-expression supports a hypothesis; validate with protein, pathway readouts, or perturbation before calling it communication. See the evidence ladder ↑
• A Visium spot is not a cell. At ~55 µm each spot averages several cells, so a "cluster" is a tissue neighborhood and a co-expression pattern within a spot is not co-expression within a cell. Any cell-type claim on Visium/Slide-seq/Stereo-seq data needs deconvolution (cell2location, RCTD) or explicit binning/segmentation first — and the deconvolution is only as good as the scRNA-seq reference it is given, which must cover every cell type actually present in the section.
• Segmentation errors drive imaging-platform artifacts. On Xenium/MERFISH/CosMx, transcripts assigned to the wrong cell (bleed-over between touching cells, or nucleus-expansion masks swallowing neighboring cytoplasm) manufacture chimeric profiles — the classic symptom is "T cells expressing tumor markers." Typical assignment error rates are ~5–15%. Compare a nucleus-expansion baseline against a transcript-aware method (Baysor) or a membrane-stain-based Cellpose model before trusting rare hybrid populations.
• Absent ≠ not expressed on targeted panels. A gene missing from a Xenium/MERFISH/CosMx panel is undetected, not unexpressed. Never run whole-transcriptome tools (HVG selection, unfiltered GSEA, marker-based automated annotation trained on full transcriptomes) on panel data without accounting for the restricted gene universe, and never call a marker negative when it was simply never probed.
• Registration and autofluorescence artifacts masquerade as biology. Misaligned image-to-coordinate registration shifts spots off tissue and produces "expression" in empty regions; tissue folds, edges, and autofluorescent structures (elastin, lipofuscin, RBCs) generate hot spots that survive QC. Always overlay counts on the H&E (sq.pl.spatial_scatter with img_alpha) and check that high-signal regions correspond to real tissue before interpreting them.
• Batch effects live across slides, sections, and capture areas. Section thickness, permeabilization time, and slide-to-slide chemistry shift total counts substantially; on multi-sample designs integrate (Harmony/scVI) or model the slide as a covariate, and never build one spatial graph across physically separate sections — library_key in sq.gr.spatial_neighbors() keeps graphs per-section.
• Moran's I is a property of the graph, not just the gene. The same gene can be "significantly spatially variable" or not depending on n_neighs, radius, or Delaunay vs. grid. Fix the graph choice on biological grounds (a radius in microns matching the interaction scale you care about), report it, and sanity-check that the top hits look structured when plotted rather than trusting the ranking alone. The same caveat applies to nhood_enrichment, whose z-scores are permutation-based and scale with cluster size.
• Do not compare absolute counts across platforms. Detection efficiency differs by an order of magnitude between Visium, Slide-seq, Stereo-seq, and imaging platforms, and imaging platforms count individual transcript molecules rather than sequencing reads. Cross-platform comparisons should be made on relative/normalized quantities, rank correlations, or spatial pattern agreement — never on raw counts per unit area.