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.