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/.

Example training configuration

The bundled SpaDOT/config.yaml starts at epoch 1 and executes while epoch < 100, for exactly 99 optimizer updates (epochs 1 through 99). The SVGP KL coefficient follows a 30-epoch linear cycle, controlled by kl_cycle_epochs: 30; its period is independent of the training length. The packaged trainer does not use reconstruction-loss patience or restore an earlier checkpoint. The saved model and latent.h5ad are from executed epoch 99. Set epoch_start and epoch_stop_exclusive in custom configs; their difference is the number of optimizer updates. maxiter is no longer a training setting. A custom config without kl_cycle_epochs retains the historical ten cycles over its training length.

The evaluated workflow used seed 2026, NumPy OT, and final KMeans with random_state=2026, n_init=10, init='k-means++', and algorithm='lloyd'. The bundled OT solver is Python/NumPy only. It does not load or ship libot.so, and no backend flag is needed. Older configurations with use_Py: true and use_C: false still work; requesting the removed C backend raises an explicit error. Set CUBLAS_WORKSPACE_CONFIG=:4096:8, PYTHONHASHSEED=2026, and numerical thread limits to 1 before launching GPU training for reproducibility. The evaluated input panels were:

The counts above are dataset-specific exploratory presets. The spot count alone did not determine gene quota across these datasets. See docs/example_workflow.md in the source repository for the selection and preprocessing recipe. SpaDOT preprocess --n_features 500,500,1000 uses Python SPARK-X and pseudoregion selection, with one quota per timepoint. The optional --selection_plan supplies numeric candidate-pool and selection-stage settings for reproducible examples directly from raw counts. It contains no saved gene lists or rankings. The executable notebooks are ChickenHeart.ipynb, AxolotlTelencephalon.ipynb, and MouseEmbryo.ipynb. Their small numeric selection plans are beside the notebooks. The R-free selection procedure is integrated into SpaDOT/utils/_preprocess_utils.py.

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 selects spatially variable genes using Python SPARK-X and pseudoregion ranking. The three examples pass --selection_plan to reproduce their selected genes from raw counts with fixed numeric settings.

Installation

The most convenient way is to install with pip.

To test a supplied SpaDOT 1.0.5 wheel before publication, install that file and run one of the three notebooks in examples/ from the examples/ directory. Each notebook checks the installed version and writes into its own new run directory. The raw H5AD files are not bundled. Place them at examples/ChickenHeart_data/ChickenHeart.h5ad, examples/AxolotlTelencephalon_data/Axolotl.h5ad, and examples/MouseEmbryo_data/MouseEmbryo.h5ad before running the notebooks.

python -m pip install /path/to/spadot-1.0.5-py3-none-any.whl

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