Metadata-Version: 2.3
Name: celldisect
Version: 0.1.1
Summary: Cell DISentangled Experts for Covariate counTerfactuals (CellDISECT). Causal generative model designed to disentangle known covariate variations from unknown ones at test time while simultaneously learning to make counterfactual predictions.
License: MIT
Author: Arian Amani
Author-email: aa34@sanger.ac.uk> Stathis Megas <sm58@sanger.ac.uk
Requires-Python: >=3.9,<3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Provides-Extra: docs
Requires-Dist: adjustText
Requires-Dist: anndata (>=0.10.8,<0.10.9)
Requires-Dist: black
Requires-Dist: flake8
Requires-Dist: gdown
Requires-Dist: importlib-metadata
Requires-Dist: ipykernel
Requires-Dist: ipython ; extra == "docs"
Requires-Dist: jax (>=0.4.16,<0.4.24)
Requires-Dist: jaxlib (>=0.4.16,<0.4.24)
Requires-Dist: jupyter
Requires-Dist: lightning (>=2.2.0,<2.3.0)
Requires-Dist: llvmlite (>=0.42,<0.43)
Requires-Dist: nbconvert
Requires-Dist: nbformat
Requires-Dist: nbsphinx ; extra == "docs"
Requires-Dist: nbsphinx-link ; extra == "docs"
Requires-Dist: numpy (>=1.26.3,<1.27.0)
Requires-Dist: pydata-sphinx-theme ; extra == "docs"
Requires-Dist: pytest
Requires-Dist: pytest-cov
Requires-Dist: ray[data,serve,train,tune] (>=2.9.0,<2.10.0)
Requires-Dist: scanpy ; extra == "docs"
Requires-Dist: scanpydoc ; extra == "docs"
Requires-Dist: scib (>=1.1.5,<1.2.0)
Requires-Dist: scib-metrics (>=0.5.1,<0.6.0)
Requires-Dist: scipy (>=1.12.0,<1.13.0)
Requires-Dist: scvi-tools (>=0.20.3,<1.0.0)
Requires-Dist: seaborn
Requires-Dist: sphinx ; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints ; extra == "docs"
Requires-Dist: sphinx-rtd-theme ; extra == "docs"
Requires-Dist: sphinx_gallery ; extra == "docs"
Requires-Dist: toml ; extra == "docs"
Requires-Dist: torch (>=2.1.0,<2.3.0)
Requires-Dist: typing_extensions (>=4.5,<4.6)
Requires-Dist: wandb
Project-URL: Homepage, https://github.com/Lotfollahi-lab/CellDISECT
Description-Content-Type: text/markdown

<img src="https://github.com/Lotfollahi-lab/celldisect/blob/main/media/CellDISECT_Logo_whitebg.png" width="1000" alt="celldisect-logo">

[![PyPI version](https://badge.fury.io/py/celldisect.svg)](https://badge.fury.io/py/celldisect)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/Lotfollahi-lab/celldisect/blob/main/LICENSE)
[![Stars](https://img.shields.io/github/stars/Lotfollahi-lab/celldisect?logo=GitHub&color=yellow)](https://github.com/Lotfollahi-lab/celldisect/stargazers)

[comment]: [![PyPIDownloads](https://static.pepy.tech/badge/celldisect)](https://pepy.tech/project/celldisect)

[comment]: [![Docs](https://readthedocs.org/projects/celldisect/badge/?version=latest)](https://celldisect.readthedocs.io/en/stable/?badge=stable)

# Cell DISentangled Experts for Covariate counTerfactuals (CellDISECT)
CellDISECT is a causal generative model designed to disentangle known covariate variations from unknown ones at test time while simultaneously learning to make counterfactual predictions. CellDISECT finds multiple latent representations for each cell, one unsupervised, and the rest weakly supervised by the provided covariates. 

Its latent space captures not only covariate-specific information but also new biology, thereby offering users a multifaceted view of the data and enhancing the ability for cell type discovery. 

Moreover, by using different "expert" models to learn each latent it achieves flexible fairness in single-cell analysis. This flexibility allows choosing which covariates to use as biological and which as batch, at test time, as opposed to at train time like with most methods.

Finally, it can model the effect of perturbations on one or many covariates by calculating the counterfactual gene expression under the perturbations.


<p align="center">
  <img src="https://github.com/Lotfollahi-lab/celldisect/blob/main/media/celldisect_illustration.png" width="750">
</p>


Installation
============

Prerequisites
--
Conda Environment
--
We recommend using [Anaconda](https://www.anaconda.com/)/[Miniconda](https://docs.conda.io/projects/miniconda/en/latest/) to create a conda environment for using CellDISECT. You can create a python environment using the following command:

    conda create -n CellDISECT python=3.9

Then, you can activate the environment using:

    conda activate CellDISECT


- Install pytorch (This version of CellDISECT is tested with pytorch 2.1.2 and cuda 12, install the appropriate version of pytorch for your system.)
```
conda install pytorch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 pytorch-cuda=12.1 -c pytorch -c nvidia
```

- (Optional) if you plan to use RAPIDS/rapids-singlecell:
```
pip install \
    --extra-index-url=https://pypi.nvidia.com \
    cudf-cu12==24.4.* dask-cudf-cu12==24.4.* cuml-cu12==24.4.* \
    cugraph-cu12==24.4.* cuspatial-cu12==24.4.* cuproj-cu12==24.4.* \
    cuxfilter-cu12==24.4.* cucim-cu12==24.4.* pylibraft-cu12==24.4.* \
    raft-dask-cu12==24.4.* cuvs-cu12==24.4.*

pip install rapids-singlecell
```

- Install CellDISECT
You can either install the stable version published on pypi using pip:
```
pip install celldisect
```
Or you can install the latest developed version directly from our github:
```
pip install git+https://github.com/Lotfollahi-lab/CellDISECT
```

- (Optional) to install cuda enabled jax:
```
pip install -U "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
```


How to use CellDISEC
===

|Description | Link |
| --- | --- |
| Counterfactual prediction and DEG analysis | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Lotfollahi-Lab/CellDISECT/blob/main/tutorials/CellDISECT_Counterfactual.ipynb) - [![Open In Github](https://img.shields.io/badge/docs-blue)](https://github.com/Lotfollahi-Lab/CellDISECT/blob/main/tutorials/CellDISECT_Counterfactual.ipynb) |

