Metadata-Version: 2.4
Name: DECONVersation
Version: 0.0.1
Summary: DECONVersation is a tool designed for the deconvolution of bulk RNA-seq data using embeddings derived from large-scale, LLM-based foundation models. DECONVersation produces robust  cell type proportions by leveraging these high-dimensional embeddings to mitigate batch effects typically present in single-cell reference signature matrices.
Author-email: Ali Oku <aoku@nygenome.org>, Rui Fu <rfu@nygenome.org>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Eastmanmd/DECONVersation
Project-URL: Issues, https://github.com/Eastmanmd/DECONVersation/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: anndata
Requires-Dist: scanpy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: torch
Requires-Dist: datasets
Requires-Dist: transformers
Requires-Dist: peft
Requires-Dist: tqdm
Dynamic: license-file

<h1 align="left">
  <img src="docs/deconversation.png" width="500">
</h1>

DECONVersation leverages embedding representations from large-scale, LLM-based foundation models to perform deconvolution of bulk RNA-seq data. Currently, embeddings from Geneformer, Cell2Sentence, CellHermes, and scGPT are supported.

```mermaid
---
config:
  theme: 'neutral'
---
flowchart
    subgraph ide1 [standard]
    direction TB 
    A[scRNA: cell x gene] --> B(full profile: type x gene)
    A[scRNA: cell x gene] --> C(markers)
    D[bulkRNA: sample x gene]
    B --> F(signature: type x marker)
    C --> F
    F bb@==> E
    D db@==> E{{deconv res:
    sample x type%}}
    end
    subgraph ide2 [foundation model]
    direction TB
    A1[scRNA: cell x gene] --> B1(full profile: type x gene)
    A1[scRNA: cell x gene] --> C1([fa:fa-robot finetuned model])
    B1 --> F1(type x embeddings)
    C1 --> F1
    D1[bulkRNA: sample x gene] --> G1(sample x embeddings)
    C1 --> G1
    F1 f1b@==> E1{{deconv res:
    sample x type%}}
    G1 g1b@==> E1
    end

bb@{ curve: linear }
db@{ curve: linear }
f1b@{ curve: linear }
g1b@{ curve: linear }
style A fill:green,color:#fff
style A1 fill:green,color:#fff
style D fill:blue,color:#fff
style D1 fill:blue,color:#fff
style C1 fill:red,color:#fff
style E stroke-width:4px
style E1 stroke-width:4px
```

---

## Overview

This project provides:

- Installation guide for DECONVersation
- Step-by-step tutorials for embedding extraction and downstream deconvolution analysis
- Sample pseudobulk dataset for deconvolution testing 
- Perfomance evaluation comparing estimates from DECONVersation and other deconvolution tools
- Guide to finetuning foundational models using DECONVersation (Geneformer and Cell2Sentence)

---

## DECONVersation Features

DECONVersation supports end-to-end deconvolution through a set of easy-to-use functions. [Geneformer](https://huggingface.co/ctheodoris/Geneformer), [Cell2Sentence](https://github.com/vandijklab/cell2sentence), [CellHermes](https://github.com/theislab/CellHermes), and [scGPT](https://github.com/bowang-lab/scGPT) embeddings can be extracted from both bulk and single-cell datasets, with single-cell embeddings used to construct robust signature matrices from .h5ad references. Cell type proportions are then estimated via NNLS directly in embedding space. Built-in benchmarking tools evaluate predictions against ground truth using RMSE and Pearson correlation, complemented by visualization utilities for assessing method performance. DECONVersation also supports testing and validation with in-built pseudobulk functions. 

---

## Tutorials

- [DECONVersation on bulk RNA-seq using Geneformer](tutorials/extracting_embeddings_from_bulk.ipynb): How to extract embeddings (using geneformer)and run DECONVersation on bulk using a single cell reference.
- [DECONVersation on pseudobulk using Geneformer](tutorials/extracting_embeddings_from_pseudobulk.ipynb): Validate deconvolution using pseudobulk data 

---

## Benchmarking 

DECONVersation was benchmarked across 6 real bulk RNA-seq datasets with ground truths, spanning diverse tissue types and experimental conditions, to evaluate deconvolution performance and generalizability.

<h1 align="left">
  <img src="docs/full_bench_more_all_6.png" width="800">
</h1>

<b> Summary </b> <br>
Across 6 benchmarked datasets, we show overall RMSE and correlation coefficient alongside mean RMSE and correlation averaged across cell types. Finetuned Cell2Sentence and Geneformer-based embeddings both demonstrate consistent deconvolution performance across all 6 datasets, with finetuned models outperforming their zero-shot counterparts in each case. This highlights the importance of finetuning. Finetuning was achieved by training models to predict cell type annotations from a single-cell reference. Among the compared methods, only DWLS achieves comparable performance to the finetuned embedding-based approaches available on DECONVersation.

| # | Dataset | Source | Ground Truth | Cell Type # | 
| -------- | -------- | --------  | --------  | --------  |
| 1 | [PMBC (Hoek)](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0118528)| PBMC | FACS | 5 |
| 2 | [PMBC (Finotello)](https://pubmed.ncbi.nlm.nih.gov/31126321/)| PBMC | FACS | 5 |
| 3 | [PMBC (Morandini)](https://pmc.ncbi.nlm.nih.gov/articles/PMC10828344/)| PBMC | FACS | 5 |
| 4 | [Cell Line Mixture (Cobos)](https://europepmc.org/article/med/37528411)| Cell Line Mixture| Mixture Count | 6 |
| 5 | [Pre-Frontal Cortex (Huuki-Myers)](https://pubmed.ncbi.nlm.nih.gov/38781370/)| DLPFC | RNAScope/IF | 6 |
| 6 | [Retina (Guo)](https://pmc.ncbi.nlm.nih.gov/articles/PMC11789644/)| Retina | snRNA | 6 |

---

## Suggested Reading
- [Geneformer](https://www.nature.com/articles/s41586-023-06139-9) Transfer learning enables predictions in network biology
- [Cell2Sentence](https://pmc.ncbi.nlm.nih.gov/articles/PMC11565894/) Cell2Sentence: Teaching Large Language Models the Language of Biology
- [CellHermes](https://www.biorxiv.org/content/10.1101/2025.11.07.687322v1) Language may be all omics needs: Harmonizing multimodal data for omics understanding with CellHermes
- [scGPT](https://www.nature.com/articles/s41592-024-02201-0) scGPT: toward building a foundation model for single-cell multi-omics using generative AI
---
