rctd-py

Spatial transcriptomics deconvolution, 10–57x faster than R spacexr on a GPU (doublet mode)

New in v0.4.0: rctd-py now gives the same results as R spacexr wherever both use the same sigma. Getting there aligned a few details of the fit with R (bulk platform-effect fit, sigma sampling, singlet labels, cell-type order, QP solver), so results can differ from 0.3.9, mostly on sequencing-based data such as Visium. On imaging data (Xenium, CosMx, Atera) spot classes are almost unchanged. Numbers are in the changelog; rctd-py==0.3.9 stays available to reproduce earlier results.

A Python reimplementation of the spacexr RCTD algorithm (Cable et al., Nature Biotechnology 2022) with GPU acceleration via PyTorch.

Deconvolve spatial transcriptomics spots (Visium, Xenium, MERFISH, Slide-seq, …) into cell type proportions using a scRNA-seq reference — in minutes instead of hours.

Documentation: rctd-py.readthedocs.io (installation, tutorials, CLI, API reference, coming from R spacexr)

✨ Highlights

Installation

uv pip install rctd-py   # or: pip install rctd-py

GPU builds of PyTorch, older NVIDIA drivers and offline / HPC installs (the 404 MB Q-matrices file) are covered in the installation guide.

Quick Start

from rctd import Reference, run_rctd
import anndata

reference = Reference(anndata.read_h5ad("reference.h5ad"), cell_type_col="cell_type")
spatial = anndata.read_h5ad("spatial.h5ad")

# normalisation, sigma estimation and deconvolution in one call
result = run_rctd(spatial, reference, mode="doublet")

📓 Tutorial (marimo notebook) · 🤖 Claude Code skill (copy the .claude/skills/rctd-py/ folder into ~/.claude/skills/ for assisted coding with rctd-py)

Command Line

rctd info                                                # versions, GPU availability
rctd validate spatial.h5ad reference.h5ad                # fast input checks
rctd run spatial.h5ad reference.h5ad --mode doublet -o results.h5ad
rctd run experiment.zarr reference.h5ad --table cell_table   # SpatialData stores work too

All options and the output layout: command line reference.

Benchmarks

rctd-py on one NVIDIA L40S or 8 CPU threads, R spacexr 2.2.1 on 8 cores; rctd-py points are the median of 3 runs. Full and multi mode, per-dataset tables and memory: benchmarks.

Citation

If you use rctd-py, please cite the original RCTD paper:

@article{cable2022robust,
  title={Robust decomposition of cell type mixtures in spatial transcriptomics},
  author={Cable, Dylan M and Murray, Evan and Zou, Luli S and Goeva, Aleksandrina and Macosko, Evan Z and Chen, Fei and Irizarry, Rafael A},
  journal={Nature Biotechnology},
  volume={40},
  number={4},
  pages={517--526},
  year={2022},
  doi={10.1038/s41587-021-00830-w}
}

Contributing

Contributions welcome! See CONTRIBUTING.md for setup instructions, or open an issue.

License

GNU General Public License v3.0