single-cell-multi-omics-integration

Single-Cell Multi-Omics Integration

This skill covers OmicVerse's multi-omics integration tools for combining scRNA-seq, scATAC-seq, and other modalities. Each method addresses a different scenario—choose based on your data structure and analysis goal.

Method Selection Guide

Pick the right tool before writing any code:

Instructions

1. MOFA on paired multi-omics

Use MOFA when you have paired measurements (RNA + ATAC from the same cells). MOFA learns shared and modality-specific factors that explain variance across omics layers.

1. Load each modality as a separate AnnData object
2. Initialise pyMOFA with matching omics and omics_name lists
3. Run mofa_preprocess() to select HVGs, then mofa_run(outfile=...) to train
4. Inspect factors with pyMOFAART(model_path=...) for correlation, weights, and variance plots
5. Dependencies: mofapy2; CPU-only

2. GLUE pairing then MOFA

Use GLUE when RNA and ATAC come from different experiments (unpaired). GLUE aligns cells across modalities by learning a shared embedding, then MOFA identifies joint factors.

1. Start from GLUE-derived embeddings (.h5ad files with embeddings in .obsm)
2. Build GLUE_pair and call correlation() to match unpaired cells
3. Subset to HVGs and run MOFA as in the paired workflow
4. Dependencies: mofapy2, scglue, scvi-tools; GPU optional for MDE embedding

3. SIMBA batch integration

Use SIMBA for multi-batch single-modality data (e.g., multiple pancreas studies). SIMBA builds a graph from binned features and learns batch-corrected embeddings via PyTorch-BigGraph.

1. Load concatenated AnnData with a batch column in .obs
2. Initialise pySIMBA(adata, workdir) and run the preprocessing pipeline
3. Call gen_graph() then train(num_workers=...) to learn embeddings
4. Apply batch_correction() to get harmonised AnnData with X_simba
5. Dependencies: simba, simba_pbg; GPU optional, needs adequate CPU threads

4. TOSICA reference transfer

Use TOSICA to transfer cell-type labels from a well-annotated reference to a query dataset. TOSICA uses a pathway-masked transformer that also provides attention-based interpretability.

1. Download gene-set GMT files with ov.utils.download_tosica_gmt()
2. Initialise pyTOSICA with reference AnnData, GMT path, label key, and project path
3. Train with train(epochs=...), save, then predict on query data
4. Dependencies: TOSICA (PyTorch transformer); depth=1 recommended (depth=2 doubles memory)

5. StaVIA trajectory cartography

Use StaVIA/VIA for trajectory inference on preprocessed data with velocity information. VIA computes pseudotime, cluster graphs, and stream plots.

1. Preprocess with OmicVerse (HVGs, scale, PCA, neighbors, UMAP)
2. Configure VIA with root selection, components, neighbors, and resolution
3. Run v0.run_VIA() and extract pseudotime from single_cell_pt_markov
4. Dependencies: scvelo, pyVIA; CPU-bound

Critical API Reference

MOFA: omics must be a list of separate AnnData objects

# CORRECT — each modality is a separate AnnData
mofa = ov.single.pyMOFA(omics=[rna_adata, atac_adata], omics_name=['RNA', 'ATAC'])

# WRONG — do NOT pass a single concatenated AnnData
# mofa = ov.single.pyMOFA(omics=combined_adata, omics_name=['RNA', 'ATAC'])  # TypeError!

The omics list and omics_name list must have the same length. Each AnnData should contain cells from the same experiment (paired measurements).

SIMBA: preprocess() must run before gen_graph()

# CORRECT — preprocess first, then build graph
simba = ov.single.pySIMBA(adata, workdir)
simba.preprocess(batch_key='batch', min_n_cells=3, method='lib_size', n_top_genes=3000, n_bins=5)
simba.gen_graph()
simba.train(num_workers=6)

# WRONG — skipping preprocess causes gen_graph to fail
# simba.gen_graph()  # KeyError: missing binned features

TOSICA: gmt_path must be an actual file path

# CORRECT — download GMT files first, then pass the file path
ov.utils.download_tosica_gmt()
tosica = ov.single.pyTOSICA(adata=ref, gmt_path='genesets/GO_bp.gmt', ...)

# WRONG — passing a database name string instead of file path
# tosica = ov.single.pyTOSICA(adata=ref, gmt_path='GO_Biological_Process', ...)  # FileNotFoundError!

MOFA HDF5: outfile directory must exist

import os
os.makedirs('models', exist_ok=True)  # Create output directory first
mofa.mofa_run(outfile='models/rna_atac.hdf5')

Defensive Validation Patterns

Always validate inputs before running integration methods:

# Before MOFA: verify inputs are compatible
assert isinstance(omics, list), "omics must be a list of AnnData objects"
assert len(omics) == len(omics_name), f"omics ({len(omics)}) and omics_name ({len(omics_name)}) must match in length"
for i, a in enumerate(omics):
    assert a.n_obs > 0, f"AnnData '{omics_name[i]}' has 0 cells"
    assert a.n_vars > 0, f"AnnData '{omics_name[i]}' has 0 genes/features"

# Before SIMBA: verify batch column exists
assert 'batch' in adata.obs.columns, "adata.obs must contain a 'batch' column for SIMBA"
assert adata.obs['batch'].nunique() > 1, "Need >1 batch for batch integration"

# Before TOSICA: verify GMT file exists and reference has labels
import os
assert os.path.isfile(gmt_path), f"GMT file not found: {gmt_path}. Run ov.utils.download_tosica_gmt() first."
assert label_name in ref_adata.obs.columns, f"Label column '{label_name}' not found in reference AnnData"

# Before StaVIA: verify PCA and neighbors are computed
assert 'X_pca' in adata.obsm, "PCA required. Run ov.pp.pca(adata) first."
assert 'neighbors' in adata.uns, "Neighbor graph required. Run ov.pp.neighbors(adata) first."

Troubleshooting

• PermissionError or OSError writing MOFA HDF5: The output directory for mofa_run(outfile=...) must exist and be writable. Create it with os.makedirs() before training.
• GLUE correlation() returns empty DataFrame: The RNA and ATAC embeddings have no overlapping features. Verify both AnnData objects have been through GLUE preprocessing and contain embeddings in .obsm.
• SIMBA gen_graph() runs out of memory: Reduce n_top_genes (try 2000) or increase n_bins to compress the feature space. SIMBA graph construction scales with gene count.
• TOSICA FileNotFoundError after download_tosica_gmt(): The download writes to genesets/ in the current working directory. Verify the file exists at the expected path, or pass an absolute path.
• StaVIA root_user mismatch: The root must be a value that exists in the true_label array. Check adata.obs['clusters'].unique() to find valid root names.
• ImportError: No module named 'mofapy2': Install with pip install mofapy2. Similarly, SIMBA needs pip install simba simba_pbg.
• MOFA factors all zero or NaN: Input AnnData may have constant or all-zero features. Filter genes with sc.pp.filter_genes(adata, min_cells=10) before MOFA.

Examples

• "I have paired scRNA and scATAC h5ad files—run MOFA to find shared factors and plot variance explained per factor."
• "Integrate three pancreas batches using SIMBA and visualise the corrected embedding coloured by batch and cell type."
• "Transfer cell type labels from my annotated reference to a new query dataset using TOSICA with GO biological process pathways."

References

• MOFA tutorial: t_mofa.ipynb
• GLUE+MOFA tutorial: t_mofa_glue.ipynb
• SIMBA tutorial: t_simba.ipynb
• TOSICA tutorial: t_tosica.ipynb
• StaVIA tutorial: t_stavia.ipynb
• Quick copy/paste commands: reference.md