pertpy: Perturbation Analysis in the scverse ecosystem

pertpy is a framework within the scverse ecosystem designed for analyzing large-scale single-cell perturbation experiments. It provides tools for:

• Harmonizing perturbation datasets.
• Automating metadata annotation.
• Calculating perturbation distances.
• Analyzing cellular responses to stimuli such as genetic modifications, drug treatments, and environmental changes.

pertpy provides a suite of tools for analyzing single-cell perturbation data, categorized by analytical task. You can find specialized tutorials and implementations for:

• Differential gene expression: Identifying gene changes following perturbation.
• Pooled CRISPR screens: Analyzing perturbation efficacy in pooled screens.
• Compositional analysis: Using methods like sccoda, sccoda_extended, tasccoda, and milo to study changes in cell type proportions.
• Multicellular and gene programs: Tools for dialogue and enrichment analysis.
• Distances and permutation tests: Measuring distances between states and performing statistical tests.
• Response prediction: Predicting cellular responses using augur, cinemaot, or scgen_perturbation_prediction.
• Perturbation space: Analyzing the landscape of perturbations.

Pertpy is an end-to-end framework for analyzing large-scale single-cell perturbation experiments (e.g., genetic knockouts, drug screens, disease states). A typical workflow in Pertpy follows these modular steps:

1. Data transformation: Initial processing, such as guide RNA assignment for CRISPR screens.
2. Quality control: Addressing confounding factors and technical variation.
3. Metadata annotation: Annotating against ontologies and enriching from databases.
4. Perturbation space analysis: Learning biologically interpretable embeddings.
5. Downstream analysis: Performing differential expression, compositional analysis, and distance calculations.

These steps are designed to be composable, allowing you to chain individual modules into custom analysis pipelines.

Pertpy is designed to work with unimodal scRNA-seq or multimodal perturbation readouts. The primary input formats are:

• AnnData objects
• MuData objects

The framework can handle various assay types, data sizes (from thousands to millions of cells), and perturbation settings including genetic modifications, drug treatments, pathogen exposure, and environmental conditions or disease states.

Pertpy uses sparse and memory-efficient implementations to handle large datasets. It leverages several libraries for parallelization and GPU acceleration to improve performance over original implementations:

• JAX: Used for GPU acceleration and high-performance computing.
• Numba: Used for speeding up Python code.
• PyNNDescent: Used in the Mixscape implementation for optimized nearest neighbor search during perturbation signature calculation.
• NumPyro: Used to accelerate scCODA and tascCODA by replacing TensorFlow's Hamiltonian Monte Carlo with the no-U-turn sampler.
• ott-jax: Used to optimize CINEMA-OT, making it portable across hardware and enabling GPU acceleration.

Pertpy uses the following tools and standards for its documentation:

• Sphinx: The core documentation engine.
• MyST: Allows writing documentation in Markdown or Markedly Structured Text.
• Numpy-style docstrings: Handled via the napoleon extension.
• myst-nb: Renders Jupyter notebooks as tutorials.
• sphinx-autodoc-typehints: Automatically references annotated input and output types.
• sphinxcontrib-bibtex: Used for including citations (e.g., {cite:p}Virshup_2023`).

To use tascCODA, install pertpy with the [tcoda] extra.

pip install 'pertpy[tcoda]'

tascCODA requires ete4, pyqt6, and toytree. You can install these by using the [tcoda] extra:

pip install pertpy[tcoda]

To use pertpy, import the package as pt. Most functionality is organized into submodules, such as pt.tl for tools.

import pertpy as pt

# Access tools via the tl submodule
pt.tl.cool_fancy_tool()

The project uses pre-commit to enforce code styles and run type-checks (via mypy) on every commit.

To install and enable pre-commit locally, run:

pre-commit install

If you are working on a branch where pre-commit.ci has automatically committed fixes, integrate them using:

git pull --rebase

Type Checking: mypy is used for type checking. To silence a specific line in your code, use the comment # type: ignore[<error-code>].