Metadata-Version: 2.5
Name: scdiffeq
Version: 1.1.2
Summary: scDiffEq: modeling single-cell dynamics using neural differential equations.
Project-URL: Homepage, https://github.com/scDiffEq/scDiffEq
Author-email: "Michael E. Vinyard" <mvinyard.ai@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: abcparse>=0.1.4
Requires-Dist: adata-query>=0.1.0
Requires-Dist: anndata>=0.11.3
Requires-Dist: autodevice>=0.0.2
Requires-Dist: cell-neighbors>=0.1.0
Requires-Dist: cell-perturb>=0.0.1rc1
Requires-Dist: cellplots>=0.0.1rc0
Requires-Dist: geomloss>=0.2.6
Requires-Dist: h5py>=3.8
Requires-Dist: lightning>=2.1
Requires-Dist: matplotlib
Requires-Dist: neural-diffeqs>=0.3.2
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: pykeops>=2.1.2
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: scanpy>=1.11.0
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scipy
Requires-Dist: statsmodels
Requires-Dist: torch-adata>=0.1.1
Requires-Dist: torch-nets>=0.1.0
Requires-Dist: torch>=2.5.0
Requires-Dist: torchsde>=0.2.6
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: ipykernel>=7.1.0; extra == 'dev'
Requires-Dist: jupyter; extra == 'dev'
Requires-Dist: jupyterlab; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: autodoc; extra == 'docs'
Requires-Dist: ipython; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: numpy<2.0; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: scikit-learn>=1.5; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-favicon; extra == 'docs'
Requires-Dist: sphinxcontrib-napoleon; extra == 'docs'
Provides-Extra: optional
Requires-Dist: ipython; extra == 'optional'
Requires-Dist: pillow; extra == 'optional'
Requires-Dist: psutil; extra == 'optional'
Requires-Dist: umap-learn; extra == 'optional'
Requires-Dist: wandb; extra == 'optional'
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# <a href=""><img src=/docs/images/scdiffeq_logo.png alt="scdiffeq_logo" width="320" />

[![PyPI pyversions](https://img.shields.io/pypi/pyversions/scdiffeq.svg)](https://pypi.python.org/pypi/scdiffeq/)
[![PyPI version](https://badge.fury.io/py/scdiffeq.svg)](https://badge.fury.io/py/scdiffeq)
<a href="https://doi.org/10.5281/zenodo.17238593"><img src="https://zenodo.org/badge/616276336.svg" alt="DOI"></a>

An analysis framework for modeling dynamical single-cell data with **neural differential equations**, most notably ***stochastic*** differential equations  allow us to build **generative models** of single-cell dynamics.

## Quickstart

Please see the [**scDiffEq website**](https://scdiffeq.com) for a quickstart notebook: [link](https://www.scdiffeq.com/_tutorials/quickstart.html)

## Install the development package

Install generally only takes a few seconds.

### Using uv (recommended)

```BASH
git clone https://github.com/scDiffEq/scDiffEq.git; cd ./scDiffEq;

# Install uv if you haven't already: curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
```

### Using pip

```BASH
git clone https://github.com/scDiffEq/scDiffEq.git; cd ./scDiffEq;

pip install -e .
```

### Optional dependency groups

| Extra | Contents |
| --- | --- |
| `optional` | Lazily-imported integrations: `umap-learn`, `pillow`, `ipython`, `psutil`, `wandb` |
| `docs` | Sphinx and theme packages for building the documentation |
| `test` | `pytest`, for running the test suite |
| `dev` | Jupyter, `ipykernel`, and `pytest` for interactive development |

```BASH
# Using uv
uv sync --extra docs

# Using pip
pip install -e ".[docs]"
```

## Datasets

```python
import scdiffeq as sdq

adata = sdq.datasets.larry()
```

Datasets are downloaded on first use and cached under
`<data_dir>/scdiffeq_data/`. They are hosted on Zenodo
([10.5281/zenodo.21947161](https://doi.org/10.5281/zenodo.21947161)); downloads
need no authentication and are verified against the record's md5 checksums.

The record redistributes data published by other groups — **please cite the
original publications**, listed on the
[data page](https://www.scdiffeq.com/data.html) and in the Zenodo record.

## Main API
  
```python
import scdiffeq as sdq

model = sdq.scDiffEq(adata=adata)

model.fit(train_epochs = 1500)
```

## Built on

<img width="50" hspace="20" alt="pytorch_logo" href="https://pytorch.org/" src="https://user-images.githubusercontent.com/47393421/187940001-61655a05-5393-419a-be96-75d11f233d6e.png"><img width="50" href="https://www.pytorchlightning.ai/" hspace="20" alt="pytorch_lightning_logo" src="https://user-images.githubusercontent.com/47393421/187939281-19139d2c-84fe-47b8-a77c-b87e04feca36.png">
<img width="110" href="https://github.com/mvinyard/neural-diffeqs" alt="neural_diffeqs_logo" src="https://github.com/user-attachments/assets/e9cc2860-bfa4-43a1-bc15-85d074b44fc7" />

## System requirements

- Developed on linux20.04 and MacOS (with Apple Silicon), using Python3.11.
- Software dependencies are listed in [pyproject.toml](./pyproject.toml).
- Tested with NVIDIA GPUs (A100, T4) and Apple Silicon. Most datasets likely only require an NVIDIA Tesla T4 (free in Google Colab).

## Reproducibility

- All results described in the [manuscript](https://rdcu.be/eVhnL) detailing scDiffEq can be reproduced using notebooks in the companion repository: [scdiffeq-analyses](https://github.com/scDiffEq/scdiffeq-analyses)

## Citation

```bibtex
@article{vinyard2025scdiffeq,
  title   = {Learning cell dynamics with neural differential equations},
  author  = {Vinyard, Michael E. and Rasmussen, Anders W. and Li, Ruitong
             and Klein, Allon M. and Getz, Gad and Pinello, Luca},
  journal = {Nature Machine Intelligence},
  volume  = {7},
  number  = {12},
  pages   = {1969--1984},
  year    = {2025},
  doi     = {10.1038/s42256-025-01150-3}
}
```

If you use the packaged datasets, please also cite their original publications
(see the [data page](https://www.scdiffeq.com/data.html)).
