Bio Spatial Transcriptomics Spatial Multiomics

Version Compatibility

Reference examples tested with: muon 0.1+, mudata 0.2+, scanpy 1.10+, anndata 0.10+, mofapy2 0.7+, paste-bio 1.4+

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 Multi-omics Integration

"Integrate my spatial RNA with protein / ATAC / a histone mark" -> Decide whether the modalities are co-measured on the SAME pixels or come from DIFFERENT sections, then either build one joint representation or register two distinct cell populations.

• Same pixel (vertical): muon/mudata container -> muon.tl.mofa joint factors, or WNN-style per-modality weighting.
• Different sections (diagonal): paste/paste2 (optimal-transport alignment), STalign (diffeomorphic registration), GPSA (common coordinate).

Governing Principle

Serial-section modalities are DIFFERENT cells -- integration across them is registration, not coupling. A z-step of even 5-10 um lands on a different cell population, so RNA on section N and ATAC on section N+1 share NO cell. Aligning them (PASTE/STalign/GPSA) produces an approximate coordinate correspondence between distinct populations, never a cell-to-cell correspondence. Any cross-modality "coupling" read off a registered pair is a statistical imputation across non-identical cells, not a measurement. The single most-abused move in this subfield is presenting diagonal, registration-based integration with the confident language of same-cell co-measurement (Vandereyken 2023 Nat Rev Genet).

Vertical (same-pixel co-profiling) versus diagonal (different cells, must register or anchor) is therefore THE decision, and it is categorical, not a tuning choice. Same-pixel platforms (the Fan-lab DBiT family, spatial-CITE-seq, Visium CytAssist Gene+Protein) justify joint same-cell methods -- WNN, MOFA, totalVI-style models -- because pairing is real. Applying WNN/MOFA diagonally, across serial sections, silently violates the matching assumption: the math runs and returns factors and weights that look meaningful but encode registration artifacts as if they were joint biology.

Two further traps ride on top of the fork. First, every spatial multi-omics platform measures PIXELS or spots (10-55 um) or sub-micron DNBs that must be binned -- "single-cell multi-omics in space" is almost always a downstream binning/segmentation CLAIM, not a property of the measurement, and a multi-cell pixel mixing a sender and a receiver can manufacture apparent within-cell cross-modal coupling. Second, the protein (or ATAC, or histone-mark) side is a TARGETED panel: the antibody set is chosen a priori, so a protein "absent" was likely never in the panel, exactly as a targeted RNA panel bounds what RNA can be detected -- absence is uninformative on either side.

The Integration Regime Fork

When the regime is ambiguous (a vendor markets "co-profiling" but the modalities were run on adjacent sections), default to diagonal: assume different cells until same-pixel co-capture is documented.

Spatial Multi-omics Platform Table

Methods and platforms move fast here; verify the current co-capture claim and the recommended joint method against the vendor and tool docs before committing, especially whether a "multiomics" product co-captures on one pixel or runs adjacent sections.

Vertical: Build a Same-Pixel MuData (RNA + Protein)

Goal: Assemble one MuData whose RNA and protein modalities are indexed on the SAME pixels, the precondition for any same-cell joint method.

Approach: Wrap each modality as an AnnData, share one pixel index and the spatial coordinates, then intersect observations so every pixel carries both modalities before joint modeling.

import muon as mu
import mudata as md
import scanpy as sc

rna = sc.read_h5ad('spatial_cite_rna.h5ad')        # pixels x genes, whole transcriptome
prot = sc.read_h5ad('spatial_cite_adt.h5ad')       # SAME pixels x bounded ADT panel

# both modalities MUST be indexed on identical pixel barcodes -- this is what makes pairing real
mdata = md.MuData({'rna': rna, 'prot': prot})
mdata.obsm['spatial'] = rna.obsm['spatial']        # one shared coordinate frame for both modalities

sc.pp.normalize_total(mdata['rna']); sc.pp.log1p(mdata['rna'])
sc.pp.highly_variable_genes(mdata['rna'])
# ADT is a targeted panel: CLR across pixels, not log1p-of-counts; absence of a marker is uninformative
mu.prot.pp.clr(mdata['prot'])

mu.pp.intersect_obs(mdata)                          # keep only pixels present in BOTH modalities

Vertical: Joint MOFA Factors Across Modalities

Goal: Learn interpretable latent factors shared across RNA and protein, with per-modality variance explained, on co-measured pixels.

Approach: Run MOFA on the MuData, then read the joint embedding and inspect which factors are RNA-driven versus protein-driven before clustering or spatial mapping.

# MOFA assumes the modalities are matched on the same pixels -- valid ONLY because this is same-pixel data
mu.tl.mofa(mdata, n_factors=10, use_var='highly_variable', outfile=None)   # writes mdata.obsm['X_mofa']

sc.pp.neighbors(mdata, use_rep='X_mofa')
sc.tl.leiden(mdata)

# mu.tl.mofa trains in place (returns None); write the model with outfile= and
# read per-modality variance explained back with mofax. A factor that is ~100%
# one modality is not "multi-omic" structure -- it is that modality's own signal.
# import mofax; m = mofax.mofa_model('mofa_model.hdf5'); m.get_variance_explained()

WNN is the alternative joint method when interpretable factors are not needed: build a per-modality reduction, then learn per-pixel modality weights. A single modality dominating the weights is the same red flag as in single-cell CITE-seq (see single-cell/multimodal-integration). The protein panel is bounded, so a pixel scoring "negative" for a marker may simply lack that antibody, not the protein.

Diagonal: Register Serial Sections (Different Cells)

Goal: Place two adjacent-section datasets in a common coordinate frame so that NEARBY does not require SAME-CELL.

Approach: Compute an optimal-transport alignment between the two slices over expression plus physical distance, then stack them on shared coordinates -- the output is a coordinate map between DISTINCT cell populations, never a cell correspondence.

import paste as pst

# sliceA and sliceB are AnnData from ADJACENT sections -- DIFFERENT cells, not the same tissue plane
pi = pst.pairwise_align(sliceA, sliceB)            # transport plan between spots, NOT a cell-to-cell map

# stack onto a shared frame for joint visualization / neighborhood comparison only
new_slices = pst.stack_slices_pairwise([sliceA, sliceB], [pi])
# any cross-modality "coupling" inferred here is imputed across non-identical cells -- label it as such

PASTE2 handles partial overlap between sections; STalign performs diffeomorphic (LDDMM) registration; GPSA learns a Gaussian-process common coordinate. All produce a coordinate correspondence, not a cell correspondence -- do not feed the registered pair into WNN/MOFA as though the pixels were paired.

Common Errors

Related Skills

• spatial-transcriptomics/spatial-proteomics - protein-intensity (not count) handling, arcsinh, segmentation-dominated panels for the protein side
• spatial-transcriptomics/spatial-data-io - load each modality with the correct reader before assembling a MuData
• single-cell/multimodal-integration - WNN/totalVI/MOFA+ mechanics, ADT denoising, and the anchor-structure fork in non-spatial data
• multi-omics-integration/mofa-integration - MOFA factor interpretation and likelihood choice across modalities

References

Liu Y, DiStasio M, Su G, et al. High-plex protein and whole transcriptome co-mapping at cellular resolution with spatial CITE-seq. Nat Biotechnol 41(10):1405-1409 (2023). Liu Y, Yang M, Deng Y, et al. High-Spatial-Resolution Multi-Omics Sequencing via Deterministic Barcoding in Tissue (DBiT-seq). Cell 183(6):1665-1681 (2020). Deng Y, Bartosovic M, Kukanja P, et al. Spatial profiling of chromatin accessibility in mouse and human tissues. Nature 609(7926):375-383 (2022). Zhang D, Deng Y, Kukanja P, et al. Spatial epigenome-transcriptome co-profiling of mammalian tissues. Nature 616(7955):113-122 (2023). Zeira R, Land M, Strzalkowski A, Raphael BJ. Alignment and integration of spatial transcriptomics data (PASTE). Nat Methods 19(5):567-575 (2022). Argelaguet R, Arnol D, Bredikhin D, et al. MOFA+: a statistical framework for comprehensive integration of multi-modal single-cell data. Genome Biol 21:111 (2020). Hao Y, Hao S, Andersen-Nissen E, et al. Integrated analysis of multimodal single-cell data (WNN). Cell 184(13):3573-3587 (2021). Vandereyken K, Sifrim A, Thienpont B, Voet T. Methods and applications for single-cell and spatial multi-omics. Nat Rev Genet 24(8):494-515 (2023). Marconato L, Palla G, Yamauchi KA, et al. SpatialData: an open and universal data framework for spatial omics. Nat Methods 22(1):58-62 (2025).