SPOmiAlign: a modality-agnostic framework for multimodal spatial omics alignment

Pipeline

SPOmiAlign aligns spatial omics datasets across modalities, samples, and reference images by converting molecular measurements into spatial structural images (SSIs) and registering them with image-matching based transformations. The framework supports omic-to-image, omic-to-omic, and image-to-image workflows, including global alignment and non-rigid refinement, and can propagate the resulting transforms back to spatial coordinates for downstream analysis and reassignment.

Directory structure

SPOmiAlign-main/
|- SPOmiAlign/                 Core alignment and reassignment modules
|  `- software/                Bundled local dependencies
|     |- Roma/
|     `- fused-local-corr-master/
|- Tutorial/                   Tutorial notebooks and scripts
|  |- Tutorial 1 omic-to-image (spatial transcriptomics to CCF)/
|  |- Tutorial 2 omic-to-omic (spatial multi-omics alignment without paired images)/
|  `- Tutorial 3 image-to-image (spatial multi-omics alignment with paired images)/
|- docs/
|  `- _static/pipeline.png     Pipeline figure
|- env/
|  `- SPOmiAlign.yml           Conda environment file
|- Data/                       Downloaded tutorial data, not tracked by git
|- output/                     Generated tutorial results, not tracked by git
`- README.md

Installation

1. Create and activate the conda environment:

conda env create -f env/SPOmiAlign.yml
conda activate SPOmiAlign

We run SPOmiAlign with A100 and torch2.6.0+cu124. If using GPU acceleration, install the PyTorch build that matches your GPU driver and CUDA version.

2. Install the bundled local dependencies:

cd SPOmiAlign/software/fused-local-corr-master/fused-local-corr-master
pip install -e .

cd ../../Roma
pip install -e .

cd ../../..

Tutorial

Tutorial files are organized by application scenario. Each case keeps its notebook and Python script together.

Tutorial 1: omic-to-image (spatial transcriptomics to CCF)

• spatial transcriptomic section (Slide-seq_29) to Allen Brain Atlas: notebook / script

Tutorial 2: omic-to-omic (spatial multi-omics alignment without paired images)

• Spatial multi-omics alignment for kidney sections: notebook / script
• Spatial multi-omics alignment for mouse brain sections: notebook / script

Tutorial 3: image-to-image (spatial multi-omics alignment with paired images)

• Spatial multi-omics alignment with paired images: notebook / script

Data

The prepared tutorial data are available from Google Drive. Download the archive from the link below and use it as the input data in Data/. Users can put your data in Data/ when using SPOmiAlign for your task.

https://drive.google.com/file/d/17j39rTAISwuH-kL3H0hnvzTG15Zo_xSK/view?usp=sharing