Steamboat

Steamboat is an interpretable machine learning framework leveraging a self-supervised, multi-head attention model that uniquely decomposes the gene expression of a cell into multiple key factors:

• intrinsic cell programs,
• neighboring cell communication, and
• long-range interactions.

These pieces of information are used to generate cell embedding, cell network, and reconstructed gene expression.

System requirements

Hardware

Steamboat can run on a laptop, desktop, or server. The experiments were done on a desktop computer with an RTX 3080 GPU (10GB VRAM). A GPU can significantly reduce the time needed to train the models (more than 5x on the most demanding examples).

Operating system

Steamboat is python-based and run on all mainsteam operating systems. It has been tested on Windows 10 and Springdale Linux.

Software dependencies

Installation

We recommend using Miniconda to create a virtual environment.

conda create -n steamboat python=3.13
conda activate steamboat
pip install steamboat-bio

Installation usually takes about 2 minutes, but can vary depending on computer and network conditions.

conda create -n steamboat python=3.13
conda activate steamboat
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130 # DO NOT RUN. ADJUST IT FOR YOUR SYSTEM.
pip install steamboat-bio

git clone https://github.com/ma-compbio/Steamboat

import sys
sys.path.append("/path/of/the/cloned/repository")

Basic workflow

import steamboat as sf # "sf" = "Steamboat Factorization"
import steamboat.tools

Data preparation and training

First, make a list (adatas) of one or more AnnData objects, and preprocess them.

adatas = sf.prep_adatas(adatas, log_norm=True)
dataset = sf.make_dataset(adatas)

Create a Steamboat model and fit it to the data. Refer to the tutorial about selecting the optimal n_heads.

model = sf.Steamboat(short_features, n_heads=10, n_scales=3)
model = model.to("cuda") # if GPU acceleration is supported.
model.fit(dataset)

After training, you can check the trained metagenes.

sf.tools.plot_all_transforms(model, top=1)

Tissue architecture definition (clustering and segmentation)

For clustering and segmentation, run the following lines. Change the resolution to your liking.

sf.tools.neighbors(adata)
sf.tools.leiden(adata, resolution=0.1)
sf.tools.segment(adata, resolution=0.5)

Mechanistic discovery (ligand–receptor screening)

lrp_dfs = sf.tools.score_lrs(adata, model, None, gene_names='index')
for i in range(model.spatial_gather.n_heads):
    display(lrp_dfs[i])

For visualization of the results, please refer to the tutorial.

Hypothesis testing (spatial perturbation)

This is a more involved process. Please refer to the relevant demos below.

If you want to try Steamboat with a relatively small dataset, please try human tonsil (Slide-tags).

Demos

A few examples in Jupyter notebook are included in the examples folder:

1. Illustration (simulated)
2. Ovarian cancer data (CosMX)
3. Mouse brain (MERFISH)
   • Training
   • Interpretation of results, such as clustering, segmentation, global attention explanation, and ligand-receptor analysis
   • Spatial perturbation, including cell transplant and environmental knock-out
4. Colorectal cancer data (CODEX)
5. Xenograft melanoma (Perturb-FISH)
6. Human tonsil (Slide-tags)
   • Select number of heads
7. Breast cancer (Visium)

The simulation demo takes about five minutes to run. The mouse brain data takes one hour to train. Other demos take about ten minutes each.

While the demos only cover selected results that are quick to go through, all results can be generated by code in reproducibility directory.

Data used in these examples are available in Google Drive. Trained models are also uploaded.

Documentation

For the full API and real data examples, please visit our documentation.