pertpy - Perturbation Analysis in Python

Pertpy is a scverse ecosystem framework for analyzing large-scale single-cell perturbation experiments. It provides tools for harmonizing perturbation datasets, automating metadata annotation, calculating perturbation distances, and efficiently analyzing how cells respond to various stimuli like genetic modifications, drug treatments, and environmental changes.

Please read our associated manuscript "Pertpy: an end-to-end framework for perturbation analysis".

Documentation

Please read the documentation for installation instructions, tutorials, use cases, and more.

Installation

We recommend installing and running pertpy on a recent version of Linux (e.g. Ubuntu 24.04 LTS). No particular hardware beyond a standard laptop is required.

You can install pertpy in less than a minute via pip from PyPI:

pip install pertpy

or conda-forge:

conda install -c conda-forge pertpy

JAX backed tools

pip install 'pertpy[jax]'

Required by scCODA, CINEMA-OT, scGen, MLPClassifierSpace, the "wasserstein" distance metric and the mixture model of GuideAssignment. tascCODA pulls it in via pertpy[tcoda]. Everything else works without it.

Differential gene expression

If you want to use the differential gene expression interface, please install pertpy by running:

pip install 'pertpy[de]'

tascCODA

if you want to use tascCODA, please install pertpy as follows:

pip install 'pertpy[tcoda]'

milo

milo requires either the "de" extra for the "pydeseq2" solver:

pip install 'pertpy[de]'

or, edger, statmod, and rpy2 for the "edger" solver:

BiocManager::install("edgeR")
BiocManager::install("statmod")

pip install rpy2

Citation

@article{Heumos2025,
  author    = {Heumos, Lukas and Ji, Yuge and May, Lilly and Green, Tessa D. and Peidli, Stefan and Zhang, Xinyue and Wu, Xichen and Ostner, Johannes and Schumacher, Antonia and Hrovatin, Karin and Müller, Michaela and Chong, Faye and Sturm, Gregor and Tejada, Alejandro and Dann, Emma and Dong, Mingze and Pinto, Gonçalo and Bahrami, Mojtaba and Gold, Ilan and Rybakov, Sergei and Namsaraeva, Altana and Moinfar, Amir Ali and Zheng, Zihe and Roellin, Eljas and Mekki, Isra and Sander, Chris and Lotfollahi, Mohammad and Schiller, Herbert B. and Theis, Fabian J.},
  title     = {Pertpy: an end-to-end framework for perturbation analysis},
  journal   = {Nature Methods},
  year      = {2025},
  publisher = {Springer Nature},
  doi       = {10.1038/s41592-025-02909-7},
  url       = {https://doi.org/10.1038/s41592-025-02909-7},
  issn      = {1548-7105}
}

pertpy is part of the scverse® project (website, governance) and is fiscally sponsored by NumFOCUS. If you like scverse® and want to support our mission, please consider making a tax-deductible donation to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.