Metadata-Version: 2.4
Name: SpaDOT
Version: 1.0.4
Summary: Package for paper: Optimal transport modeling uncovers spatial domain dynamics in spatiotemporal transcriptomics
Author-email: Wenjing Ma <mawenjing1993@gmail.com>
License-Expression: MIT
Project-URL: homepage, https://marvinquiet.github.io/SpaDOT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.5.0
Requires-Dist: torchvision
Requires-Dist: torchaudio
Requires-Dist: anndata==0.9.1
Requires-Dist: scanpy==1.9.8
Requires-Dist: numpy<2.0.0
Requires-Dist: chi2comb==0.1.0
Requires-Dist: KDEpy==1.1.12
Requires-Dist: wot
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: pyyaml
Requires-Dist: louvain
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# SpaDOT

[![PyPI version](https://badge.fury.io/py/SpaDOT.svg?icon=si%3Apython)](https://pypi.org/project/SpaDOT/) [![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-390/) 


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](https://rlangefe.github.io/) from the [Xiang Zhou Lab](https://xiangzhou.github.io/).

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](examples/ChickenHeart.ipynb),
[Axolotl Telencephalon](examples/AxolotlTelencephalon.ipynb), and
[Mouse Embryo](examples/MouseEmbryo.ipynb) 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:

| Dataset | Spots by timepoint | Genes requested by timepoint |
|---|---|---|
| Chicken Heart | 747 / 1,966 / 1,916 / 1,967 | 500 / 500 / 1,000 / 1,000 |
| Axolotl Telencephalon | 1,477 / 2,929 / 4,410 | 500 / 500 / 1,000 |
| Mouse Embryo | 2,397 / 2,312 / 3,546 | 3,000 / 3,000 / 3,000 |

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](#system-requirements)
- [Installation](#installation)
- [License](#license)
- [Citing Our Work](#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](https://www.python.org/) (version 3.9 recommended)
- [torch](https://pytorch.org/) (v2.5.0)
- [anndata](https://anndata.readthedocs.io/en/latest/) (v0.9.1)
- [scanpy](https://scanpy.readthedocs.io/en/stable/) (v1.9.8)
- [numpy](https://numpy.org/) 
- [pandas](https://pandas.pydata.org/)
- [wot](https://github.com/broadinstitute/wot)
- `cuda toolkit` and `nvidia cudnn` when using GPU resources, more information can be found [here](https://towardsdatascience.com/setting-up-tensorflow-gpu-with-cuda-and-anaconda-onwindows-2ee9c39b5c44)
- [torch_geometric](https://pytorch-geometric.readthedocs.io/en/latest/), 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](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/). 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](https://docs.astral.sh/uv/), clone this
repository and create a Python 3.9 environment in the checkout:

```shell
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`.

```shell
pip install SpaDOT
```

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

```shell
pip install --upgrade SpaDOT
```

For more information, a detailed documentation on installation is provided [here](https://marvinquiet.github.io/SpaDOT/).


## License

This project is covered under the **MIT license**.


## Citing Our Work

<!-- For usage of the package and associated manuscript, please cite: 
```BibTex
@article{ma23cellcano,
  title   = {Cellcano: supervised cell type identification for single cell ATAC-seq data},
  author  = {Ma, Wenjing and Lu, Jiaying and Wu, Hao},
  journal = {Nature Communications},
  year    = {2023},
  month   = {Apr.},
  day     = {03},
  volume={14},
  number={1},
  pages={1864},
  issn={2041-1723},
  doi={10.1038/s41467-023-37439-3},
  url={https://doi.org/10.1038/s41467-023-37439-3}
}
``` -->
