Metadata-Version: 2.1
Name: topovelo
Version: 0.0.2
Summary: topological velocity inference from single-cell spatial transcriptomic data
Home-page: https://github.com/welch-lab/TopoVelo.git
Author: Yichen Gu
Author-email: gyichen@umich.edu
License: GNU General Public License v3.0
Keywords: spatial transcriptomics,RNA velocity,single-cell RNA,graph neural network
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Description-Content-Type: text/markdown
Provides-Extra: default
License-File: LICENSE

# TopoVelo

TopoVelo stands for **Topo**logical **velo**city inference. It is a tool for jointly modeling temporal gene expression and spatial cellular dynamics from spatial transcriptomic data.
The method applies a graph variational autoencoder to recover spatially-coupled RNA velocity and reveal the spatial migration of cells during tissue growth.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [License](#license)
- [Contact](#contact)

## Installation

To install the TopoVelo package, you can use pip:
Locally:
```
git clone https://github.com/welch-lab/TopoVelo.git
cd TopoVelo
pip install .
```
From PyPI:
```
pip install topovelo
```

## Usage

The package provides function modules for training and evaluating a TopoVelo model and plotting results. The default pipeline with minimal hyperparameter tuning is shown as follows:
```
import scanpy as sc
import scvelo as scv
import topovelo as tpv
import torch

# Load .h5ad to AnnData
adata = sc.read(< path to .h5ad >)

# Preprocessing
spatial_key = 'X_spatial'
tpv.preprocess(adata, n_gene=200, spatial_key=spatial_key)
tpv.build_spatial_graph(adata, spatial_key)

# Create a VAE object 
device = torch.device('cpu') if torch.cuda.is_available() else torch.device('cpu')
vae = tpv.VAE(adata, tmax=20, dim_z=5, device=device)

# Training
vae.train(adata, adata.obsp['spatial_graph'], spatial_key)

# Save results
vae.save_model(< path to model parameters >, 'encoder', 'decoder')
vae.save_anndata(adata, 'gat', < path to output >, file_name="adata_out.h5ad")
```
Examples of advanced usage, model evaluation and plotting can be found in the [tutorial](./notebooks/tutorial/).

## License

GNU General Public License v3.0

## Contact

The package is currently maintained by Yichen Gu. Please contact the maintainer via gyichen@umich.edu.


