Metadata-Version: 2.4
Name: buddi
Version: 0.1.0
Summary: BuDDI: Bulk Deconvolution with Domain Invariance to predict cell-type-specific perturbations from bulk
Author-email: "Natalie R. Davidson" <NATALIE.DAVIDSON@cuanschutz.edu>, Weishan Li <WEISHAN.2.LI@CUANSCHUTZ.EDU>
Maintainer-email: David Bunten <DAVE.BUNTEN@cuanschutz.edu>, Faisal Alquaddoomi <FAISAL.ALQUADDOOMI@cuanschutz.edu>
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: <3.11,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10.9
Requires-Dist: ipython>=8.18.1
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.3.3
Requires-Dist: poethepoet>=0.37
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tensorflow<2.19,>=2.16; platform_system == "Darwin"
Requires-Dist: tensorflow<3,>=2.16; platform_system != "Darwin"
Requires-Dist: tqdm>=4.67.1
Requires-Dist: umap-learn>=0.5.11
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29; extra == "notebooks"
Requires-Dist: ipywidgets>=8.1.8; extra == "notebooks"
Requires-Dist: joblib>=1; extra == "notebooks"
Requires-Dist: jupyterlab>=3; extra == "notebooks"
Requires-Dist: jupyterlab-widgets>=3.0.16; extra == "notebooks"
Requires-Dist: matplotlib-venn>=0.11; extra == "notebooks"
Requires-Dist: scanpy>=1.9; extra == "notebooks"
Requires-Dist: scipy>=1.5; extra == "notebooks"
Provides-Extra: with-gpu
Requires-Dist: tensorflow[and-cuda]<3,>=2.16; platform_system == "Linux" and extra == "with-gpu"
Requires-Dist: tensorflow-metal>=1.2; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "with-gpu"
Dynamic: license-file

# BuDDI

This repository contains all the model code used in [**BuDDI: Bulk Deconvolution with Domain Invariance to predict cell-type-specific perturbations from bulk**](https://www.biorxiv.org/content/10.1101/2023.07.20.549951v1)

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:
![BuDDI schematic](https://www.biorxiv.org/content/biorxiv/early/2023/07/22/2023.07.20.549951/F1.large.jpg?width=800&height=600&carousel=1)

### Installation

First, you need to install dependencies using your package manager. Below is an example for OS X using [brew](https://brew.sh/).

```bash
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.

```bash
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.

```bash
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](https://poethepoet.natn.io/index.html), to start it.

```bash
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:

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

### Usage

See the [tutorial](https://github.com/greenelab/buddi_analysis) for detailed instructions on how to use BuDDI.

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

```python
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`.
