buddi 0.1.0

BuDDI: Bulk Deconvolution with Domain Invariance to predict cell-type-specific perturbations from bulk

BuDDI

This repository contains all the model code used in BuDDI: Bulk Deconvolution with Domain Invariance to predict cell-type-specific perturbations from bulk

You can find notebooks that exemplify how to use the library under examples.

Overview

While single-cell experiments provide deep cellular resolution within a single sample, some are inherently more challenging than bulk experiments due to dissociation difficulties, cost, or limited tissue availability. This creates a situation where we have deep cellular profiles of one sample or condition, and bulk profiles across multiple samples and conditions.

A schematic of what BuDDi's methodological goal is shown below:

To bridge this gap, we propose BuDDI (BUlk Deconvolution with Domain Invariance).

BuDDI utilizes domain adaptation techniques to effectively integrate available corpora of case-control bulk and reference scRNA-seq observations to infer cell-type-specific perturbation effects. BuDDI achieves this by learning independent latent spaces within a single variational autoencoder (VAE) encompassing at least four sources of variability: 1) cell-type proportion, 2) perturbation effect, 3) structured experimental variability, and 4) remaining variability. Since each latent space is encouraged to be independent, we simulate perturbation responses by independently composing each latent space to simulate cell-type-specific perturbation responses.

Below is a schematic of the VAE structure of BuDDI:

Installation

First, you need to install dependencies using your package manager. Below is an example for OS X using brew.

brew install hdf5 c-blosc cython
export HDF5_DIR=/opt/homebrew/opt/hdf5
export BLOSC_DIR=/opt/homebrew/opt/c-blosc

Below is an example for Ubuntu using apt-get.

apt-get install libhdf5-serial-dev
apt-get install libblosc-dev
apt-get install pip install typing-extensions --upgrade

Second, you will install BuDDI from github using pip. It is recommended that you install this into a virtual env that you can activate before running the provided analysis scripts or your own BuDDI experiments.

pip install git+https://github.com/NDavidsonLab/buddi.git#egg=buddi[notebooks]

Using the Example Notebooks

Once you've installed BuDDI with the [notebooks] extra, you can run the example notebooks provided in the examples/ directory.

You can use the helper task buddi-lab, added via Poe the Poet, to start it.

poe buddi-lab

Alternatively, in the virtualenv in which you've installed BuDDI, you can create a kernel for the current venv and then start Jupyter Lab with the following command:

python -m ipykernel install --user --name buddi --display-name "Python (buddi)"
python -m jupyter lab examples/

Usage

See the tutorial for detailed instructions on how to use BuDDI.

To import BuDDI and its helper methods within your Python code, simply add the following

import buddi
from buddi.preprocessing import sc_preprocess
from buddi.plotting import validation_plotting as vp

Package Naming

The package is published as buddi, and the source tree now lives under src/buddi.