SpaDOT

Software for the manuscript "Optimal Transport Modeling Uncovers Spatial Domain Dynamics in Spatiotemporal Transcriptomics". First trial in wrapping a code pipeline using GitHub Copilot, inspired by Robert Langefeld from the Xiang Zhou Lab.

SpaDOT is an open-source computational method for identifying spatial domains and inferring their temporal dynamics across time points for spatiotemporal transcriptomics studies. Detailed documentation and tutorials are available at: https://marvinquiet.github.io/SpaDOT/.

Examples

Install this GitHub checkout (python -m pip install -e .) before running the notebooks so they use the preprocessing and training code shown here.

The Chicken Heart, Axolotl Telencephalon, and Mouse Embryo notebooks follow five steps: load the raw data, run SpaDOT preprocess, run SpaDOT train, run SpaDOT analyze, and view the results. They use these gene counts:

Use one gene count per timepoint with SpaDOT preprocess --n_features, for example --n_features 500,500,1000. The notebooks let SpaDOT derive the genes from each user's input and display the results generated by that run. Different inputs may select different genes and produce different results.

When obs["annotation"] is available, SpaDOT analyze colors each predicted domain by its most overlapping annotation for visual comparison. It also plots the transition score used by _analyze_utils.py: the minimum of the row- and column-conditional probabilities from the transition H5AD matrix. The same analyzed score is shown as a numbered matrix. Original H5AD values remain available in the transition tables and raw-mass CSVs for audit. The analysis writes a separate ID-to-name mapping. Corresponding regions are placed along a rising diagonal where possible. Annotation matching changes only the display; it does not change training, clustering, or transport values.

The included SpaDOT/config.yaml illustrates a training run from epoch 1 through 99 with a 30-epoch SVGP KL cycle and seed 2026. Adjust these values in a copied configuration for other studies. epoch_stop_exclusive is the first epoch that does not run; the saved model and latent.h5ad come from the last executed epoch. The trainer uses Python/NumPy OT and does not require libot.so or R. For reproducible GPU runs, set CUBLAS_WORKSPACE_CONFIG=:4096:8, PYTHONHASHSEED=2026, and numerical thread limits to 1 before starting Python.

Table of Contents

• System Requirements
• Installation
• License
• Citing Our Work

System Requirements

Hardware requirements

It is recommended to run SpaDOT on a GPU to achieve faster execution times.

Dependencies

SpaDOT requires the following:

• python (version 3.9 recommended)
• torch (v2.5.0)
• anndata (v0.9.1)
• scanpy (v1.9.8)
• numpy
• pandas
• wot
• cuda toolkit and nvidia cudnn when using GPU resources, more information can be found here
• torch_geometric, this package is dependent on torch version and cuda version.

Note: If using GPU resources, you might also need to install the CUDA Toolkit and NVIDIA cuDNN libraries. Detailed setup instructions can be found here. Please make sure to install a compatible version for PyTorch.

R is not required at runtime. SpaDOT preprocess --n_features performs feature selection in Python.

Installation

For a collaborator using uv, clone this repository and create a Python 3.9 environment in the checkout:

git clone https://github.com/marvinquiet/SpaDOT.git
cd SpaDOT
uv venv --python 3.9
uv pip install -e .
./.venv/bin/SpaDOT --help

The environment stays in .venv and is not committed. On Windows, use .venv\Scripts\SpaDOT.exe --help for the last command. The three notebooks in examples/ use this same checkout and environment.

The most convenient way is to install with pip.

pip install SpaDOT

To upgrade to a newer release use the --upgrade flag.

pip install --upgrade SpaDOT

For more information, a detailed documentation on installation is provided here.

License

This project is covered under the MIT license.

Citing Our Work