Compositional Perturbation Autoencoder (CPA)

CPA is a framework designed to learn the effects of perturbations at the single-cell level. It encodes and learns phenotypic drug responses across various cell types, doses, and drug combinations.

Key capabilities include:

• Out-of-distribution predictions: Predict effects of unseen drug and gene combinations at various doses and across different cell types.
• Interpretable latent spaces: Learn distinct latent spaces for drugs and cell types.
• Dose-response estimation: Estimate the dose-response curve for individual perturbations and their combinations.
• Perturbation transfer: Transfer perturbation effects from a known cell type to an unseen cell type.
• Batch effect removal: Enable batch effect removal in both the latent space and the gene expression space.

CPA (Compositional Perturbation Autoencoder) is a framework designed to learn the effects of perturbations at the single-cell level. It encodes and learns phenotypic drug responses across different cell types, doses, and combinations.

Key capabilities include:

• Out-of-distribution predictions: Predict responses for unseen drug and gene combinations at various doses and across different cell types.
• Interpretable latent spaces: Learn latent spaces for drugs and cell types.
• Dose-response estimation: Estimate dose-response curves for individual perturbations and their combinations.
• Context transfer: Transfer perturbation effects from one cell type to an unseen cell type.
• Batch effect removal: Enable batch effect removal in both the latent space and the gene expression space.

It is recommended to use Anaconda or Miniconda to manage the CPA environment. Create a new environment with Python 3.9 to ensure compatibility.

conda create -n cpa python=3.9
conda activate cpa

You can install CPA using pip. To access the latest development version, you can install it directly from the GitHub repository. For detailed installation instructions, refer to the official documentation.

pip install cpa-tools

CPA requires PyTorch version >= 1.13.1. Installation commands vary based on your operating system and hardware acceleration (CUDA, ROCM, or CPU).

# OSX
pip install torch==1.13.1

# ROCM 5.2 (Linux only)
pip install torch==1.13.1+rocm5.2 --extra-index-url https://download.pytorch.org/whl/rocm5.2

# CUDA 11.6
pip install torch==1.13.1+cu116 --extra-index-url https://download.pytorch.org/whl/cu116

# CUDA 11.7
pip install torch==1.13.1+cu117 --extra-index-url https://download.pytorch.org/whl/cu117

# CPU only
pip install torch==1.13.1+cpu --extra-index-url https://download.pytorch.org/whl/cpu

If you are using Google Colab, use the following logic to install either the stable PyPI package or the latest source version from GitHub, along with scanpy and jsonschema requirements.

import sys
#if branch is stable, will install via pypi, else will install from source
branch = "latest"
IN_COLAB = "google.colab" in sys.modules

if IN_COLAB and branch == "stable":
    !pip install cpa-tools
    !pip install scanpy
elif IN_COLAB and branch != "stable":
    !pip install --quiet --upgrade jsonschema
    !pip install git+https://github.com/theislab/cpa
    !pip install scanpy

To predict the effects of gene perturbations (CRISPRi or CRISPRa) and their combinations, use the tutorial based on the Norman et al. (2019) dataset.

combosciplex_Rdkit_embeddings

If your goal is to predict the effects of drugs and their combinations, CPA provides tutorials based on the ComboSciPlex dataset. You can follow the standard demo or a version utilizing RDKit embeddings for molecular representations.

Available tutorials:

• combosciplex: Standard demo with hyper-parameters for the ComboSciPlex dataset.
• combosciplex_Rdkit_embeddings: Demo using RDKit embeddings.

CPA provides built-in hyperparameter optimization based on scvi-tools and Ray Tune.

1. Run Optimization: Use the provided example scripts:

   • examples/tune_script.py for standard optimization.
   • examples/tune_script_wandb.py to log results to Weights & Biases (set use_wandb=True).

2. Analyze Results: The optimization process saves a result_grid.pkl file. You can load this file to analyze the run and select the best hyperparameters following the Ray Documentation.

import pickle
with open('result_grid.pkl', 'rb') as f:
    result_grid = pickle.load(f)

After setting up PyTorch, install the latest version of CPA directly from GitHub and install scanpy as a dependency.

pip install git+https://github.com/theislab/cpa
pip install scanpy