██████╗  ██╗   ██╗  ██████╗  ███████╗  ██████╗  ██████╗  ███╗   ██╗ ██╗   ██╗
           ██╔══██╗ ╚██╗ ██╔╝  ██╔══██╗ ██╔════╝ ██╔════╝ ██╔═══██╗ ████╗  ██║ ██║   ██║
           ██████╔╝  ╚████╔╝   ██║  ██║ █████╗   ██║      ██║   ██║ ██╔██╗ ██║ ██║   ██║
           ██╔═══╝    ╚██╔╝    ██║  ██║ ██╔══╝   ██║      ██║   ██║ ██║╚██╗██║ ╚██╗ ██╔╝
           ██║         ██║     ██████╔╝ ███████╗ ╚██████╗ ╚██████╔╝ ██║ ╚████║  ╚████╔╝
           ╚═╝         ╚═╝     ╚═════╝  ╚══════╝  ╚═════╝  ╚═════╝  ╚═╝  ╚═══╝   ╚═══╝  

Python implementation of bulk RNAseq deconvolution algorithms

How to install

package

pip install "pydeconv"

dev

uv sync --all-groups

How to use: overview

from pydeconv import SignatureMatrix
from pydeconv.model import OLS, NNLS, DWLS, Tape, Scaden, MixupVI, NuSVR, RLR, WNNLS
from adata import AnnData

signature_matrix = SignatureMatrix.load("path/to/signature_matrix.csv") # index: gene names, column: cell types
solver = NNLS(signature_matrix)

adata = AnnData("path/to/adata.h5ad") # index: sample_id, columns: gene_names
adata.layers["raw_counts"] = ... # apply your preprocessing step or not

cell_prop = solver.transform(adata, layer="raw_counts", ratio=True)

How to use: detailed

1. Load an already registered signature matrix

from pydeconv.signature_matrix.registry import sig_matrix_laughney_lung_cancer
signature_matrix = sig_matrix_laughney_lung_cancer()

Note

Checkout here for more description of other registered signature matrix.

2. Load a custom signature matrix

from pydeconv import SignatureMatrix
signature_matrix = SignatureMatrix.load("path/to/signature_matrix.csv") #index: gene names, column: cell types

Note

For the moment only .csv format is supported. You can add any kwargs arguments from pd.read_csv after the path.

3. Predict

from pydeconv.model import Tape, Scaden

adata = AnnData("path/to/adata.h5ad") # index: sample_id, columns: gene_names
adata.layers["counts_sum"] = ...

solver = Scaden(weights_version="cti_2nd_level_granularity")
cell_prop = solver.transform(adata, layer="counts_sum", ratio=True)

Note

The model will check that you have the corresponding gene names in your input data.

4. Predict (signature based method)

from pydeconv.model import OLS, NNLS, DWLS

signature_matrix = ...
adata = AnnData("path/to/adata.h5ad")
adata.layers["relative_counts"] = ...

solver = DWLS(signature_matrix)
cell_prop = solver.transform(adata, layer="relative_counts", ratio=True)

Benchmark

We benchmarked the performance of several deconvolution algorithms on the CTI dataset, including our developed method MixUpVI. This repository and the proposed methods are part of the following paper: Joint probabilistic modeling of pseudobulk and single-cell transcriptomics enables accurate estimation of cell type composition, published in the Generative AI & Biology workshop of ICML, 2025.

The results are shown below.

To run the benchmark, you can use the following command:

python benchmark/run_benchmark.py

Note

The repository only provides inference capabilities. It does not provide capabilities to train MixUpVI and other deep learning methods, or create signature matrices. Therefore, we provide the weights from the trained models presented in the publication, and pre-computed signature matrices. To use these models on other datasets, one must provide their own weights and/or pre-computed signature matrices.

Results 1st granularity

Results 2nd granularity

Note

These results are computed and guaranteed using the adata.raw.X layer of the CTI dataset available on cellxgene. It will be automatically downloaded when running the benchmark.

Cite

If you found our work useful in your research, please consider citing it at:

@inproceedings{
grouard2025joint,
title={Joint Probabilistic Modeling of Pseudobulk and Single-Cell Transcriptomics Enables Accurate Estimation of Cell Composition},
author={Simon Grouard and Khalil Ouardini and Yann Rodriguez and Jean-Philippe Vert and Almudena Espin-Perez},
booktitle={ICML 2025 Generative AI and Biology (GenBio) Workshop},
year={2025},
url={https://openreview.net/forum?id=JhDJ0MGo2z}
}