SPAMO: Spatial Multi-Omics Integration via Dual-Graph Encoding and Neighborhood-Constrained Cross-Modal Fusion

SPAMO is a command-line tool for spatial multi-omics integration and spatial domain identification. It supports paired spatial modalities such as RNA+ADT and RNA+ATAC, plus a three-modality RNA+ADT+ATAC mode used by the simulation benchmark.

This repository is organized as a lightweight software release: source code, a tiny runnable demo, and benchmark reproduction scripts are included; large .h5ad datasets and generated results are excluded from git.

Overview

SPAMO constructs modality-specific coordinate-neighbor and feature-neighbor graphs, learns graph-based latent representations through adaptive dual-graph encoding, and integrates modalities using neighborhood-constrained cross-modal attention with gated residual fusion. The fused embedding is clustered with mclust by default. The final training objective combines modality-specific reconstruction with Frobenius feature-graph regularization.

Installation

The experiments were run in a conda environment named ST on Python 3.12. Use the provided environment.yml to recreate the environment:

conda env create -f environment.yml
conda activate ST

If your shell cannot find conda, initialize conda using the initialization script from your own conda installation, then activate the environment.

Quick Start Without Large Data

Run the tiny synthetic RNA+ADT demo:

bash demos/run_tiny_demo.sh

This creates small demo .h5ad files under demo_data/tiny_rna_adt/ and writes outputs to results/tiny_demo/.

Expected outputs:

results/tiny_demo/
├── labels.txt
├── embedding.csv
└── metrics.txt

Run On Your Own Data

Input files should be AnnData .h5ad files with:

• expression/count matrix in .X
• spatial coordinates in .obsm["spatial"]
• matching obs_names across modalities

RNA+ADT example:

python main.py \
  --rna_h5ad path/to/adata_RNA.h5ad \
  --mod2_h5ad path/to/adata_ADT.h5ad \
  --mod2_type ADT \
  --n_clusters 10 \
  --output_dir results/my_rna_adt_run \
  --RNA_weight 5 --ADT_weight 1 \
  --epochs_override 200 \
  --optimizer_type adam --lr_scheduler_type cosine

RNA+ATAC example:

python main.py \
  --rna_h5ad path/to/adata_RNA.h5ad \
  --mod2_h5ad path/to/adata_ATAC.h5ad \
  --mod2_type ATAC \
  --n_clusters 14 \
  --output_dir results/my_rna_atac_run \
  --RNA_weight 1 --ADT_weight 10 \
  --epochs_override 400 \
  --optimizer_type adamw --lr_scheduler_type cosine

Three-modality RNA+ADT+ATAC example:

python main.py \
  --rna_h5ad path/to/adata_RNA.h5ad \
  --mod2_h5ad path/to/adata_ADT.h5ad \
  --mod3_h5ad path/to/adata_ATAC.h5ad \
  --mod2_type ADT --mod3_type ATAC \
  --n_clusters 5 \
  --output_dir results/my_three_modality_run

If ground-truth labels are available, add:

--gt_labels path/to/GT_labels.txt

Outputs

When --output_dir is provided, SPAMO writes:

• labels.txt: predicted cluster labels
• embedding.csv: fused latent embedding (emb_combined)
• metrics.txt: clustering metrics, only when --gt_labels is provided
• spamo.png: UMAP and spatial plot, unless --skip_plot is used

Benchmark Reproduction

Download the benchmark data and place it under Data/ as described in Data/README.md, then run:

bash demos/run_benchmarks.sh

Repository Structure

SpaMO/
├── main.py
├── cal_matrics.py
├── environment.yml
├── demos/
│   ├── make_tiny_demo.py
│   ├── run_tiny_demo.sh
│   └── run_benchmarks.sh
├── spamo/
│   ├── model.py
│   ├── model_3m.py
│   ├── trainer.py
│   ├── trainer_3m.py
│   ├── preprocess.py
│   ├── preprocess_3m.py
│   └── utils.py
├── Data/
│   └── README.md
└── model/
    └── overview.png

Data Availability

Benchmark datasets can be obtained from Google Drive or Zenodo record 20160187.

Large data files and generated results are intentionally excluded from git.

Citation

If you use this code or data, please cite the corresponding paper and data resources.

@misc{spamo,
  title = {SPAMO: Spatial Multi-Omics Integration via Dual-Graph Encoding and Neighborhood-Constrained Cross-Modal Fusion},
  note = {Data and scripts available at https://zenodo.org/records/20160187}
}

License

Please follow the license terms of the original codebase, datasets, and third-party dependencies.