Semi-Supervised Deconvolution of Bulk RNA-Seq Data with Hyperparameter Optimization

Performs semi-supervised deconvolution of bulk RNA sequencing (RNA-seq) data. Known cell-type proportions are estimated using supervised methods -- 'CIBERSORTx' (CSx), 'CIBERSORT' (CS), 'FARDEEP' (Fast And Robust DEconvolution of Expression Profiles), and 'DCQ' (Digital Cell Quantifier) -- while unknown components are inferred using non-negative matrix factorization ('NMF') with limited-memory Broyden-Fletcher-Goldfarb-Shanno with bounds ('L-BFGS-B') optimization. Hyperparameters are selected automatically using a Pareto-frontier-based approach with knee-point detection, allowing application when the reference signature matrix is incomplete. More details about 'DICEpro' can be found in Ba et al. (2026) .

dicepro

Deconvolution with Iterative Completion for Estimating Cellular Proportions from RNA-seq Data

Overview

Bulk RNA-seq deconvolution infers the proportions of distinct cell types from a mixed gene expression profile. Most existing methods assume that the reference signature matrix is complete – i.e., that every cell population present in the bulk sample is represented. In practice this assumption rarely holds, leading to biased estimates.

dicepro addresses this limitation through an iterative joint optimization that simultaneously:

• estimates cell-type proportions for known populations (supervised step, via CIBERSORTx (“CSx”), CIBERSORT (“CS”), FARDEEP, DCQ).
• discovers and quantifies unknown populations using Non-Negative Matrix Factorization (NMF) with L-BFGS-B optimization (unsupervised step).

Hyper-parameters $(\lambda, \gamma, p')$ controlling the NMF regularization are selected automatically via a Pareto-frontier + knee-point procedure, so no manual tuning is required.

Key Features

• Incomplete-reference robustness – recovers cell types absent from the reference matrix.
• Method-agnostic supervised step – plug in any supported deconvolution backend.
• Automated hyper-parameter search – random search over a log-uniform grid with Pareto-optimal selection.
• Bundled benchmark data – BlueCode (34-cell-type reference) and CellMixtures (12 experimentally mixed bulk samples) included.
• Rich diagnostics – Pareto plot and hyper-parameter scatter matrix saved automatically to output_path/report/.

Installation

Development version (GitHub)

# install.packages("remotes")
remotes::install_github("kalidouBA/dicepro")

Quick Start

Simulated Data

library(dicepro)
set.seed(2101)

# 1. Simulate reference, proportions, and noisy bulk
sim <- simulation(
  scenario   = "hierarchical",
  nSample    = 30,
  nGenes     = 200,
  nCellsType = 10,
  sigma_bio  = 0.07,
  sigma_tech = 0.07
)

# 2. Run dicepro
out <- dicepro(
  reference             = as.matrix(sim$W)[, -c(1,5,10)],
  bulk                  = as.matrix(sim$B),
  methodDeconv          = "FARDEEP",
  bulkName              = "SimBulk",
  refName               = "SimRef",
  hp_max_evals          = 100L,
  hspaceTechniqueChoose = "all",
  output_path           = tempdir()
)

# 3. Inspect results
class(out)
out$hyperparameters    # best lambda / gamma
head(out$H)            # estimated proportions
out$plot               # interactive Pareto plot
out$plot_hyperopt      # hyper-parameter scatter matrix

Real Data (BlueCode + CellMixtures)

library(dicepro)

data(BlueCode)      # 34-cell-type reference (G x 34)
data(CellMixtures)  # 12 mixed bulk samples  (G x 12)

out <- dicepro(
  reference             = BlueCode,
  bulk                  = CellMixtures,
  methodDeconv          = "FARDEEP",
  bulkName              = "CellMixtures",
  refName               = "BlueCode",
  hp_max_evals          = 100L,
  hspaceTechniqueChoose = "all",
  output_path           = tempdir()
)

head(out$H)

CIBERSORTx Setup (optional)

CIBERSORTx (methodDeconv = "CSx") requires Docker and a personal token.

Step 1 – Install Docker Desktop

Download from https://www.docker.com/products/docker-desktop/, open it, log in, then pull the CIBERSORTx image from a terminal:

docker pull cibersortx/fractions

Step 2 – Obtain a token

Request a token at https://cibersortx.stanford.edu/ (you will first need to register). Tokens are tied to your account and expire periodically; request a new one when the existing token has expired.

Step 3 – Run dicepro with CIBERSORTx

out <- dicepro(
  reference        = BlueCode,
  bulk             = CellMixtures,
  methodDeconv     = "CSx",
  cibersortx_email = "[email protected]",
  cibersortx_token = "your_token_here",
  bulkName         = "CellMixtures",
  refName          = "BlueCode",
  output_path      = tempdir()
)

Other supported deconvolution backends can be listed with ?running_method.

Output Structure

dicepro() returns an S3 object of class "dicepro" with the following elements:

Bundled Datasets

BlueCode

A 13299 genes x 34 cell-type reference signature matrix derived from sorted bulk RNA-seq profiles spanning five major tissue compartments: Immune (9), Stromal (8), Endothelial (3), Epithelial (5), and Muscle (9). Immune cells (e.g., B cells, T cells, monocytes, macrophages, NK cells) Stromal cells (e.g., fibroblasts, MSC-like cells) Endothelial cells Epithelial cells Muscle-related cells (e.g., smooth muscle, myocytes)

data(BlueCode)
dim(BlueCode)
colnames(BlueCode)

CellMixtures

A 31422 genes x 12 bulk RNA-seq matrix of experimentally constructed cell mixtures (samples A–L), paired with BlueCode for benchmarking.

data(CellMixtures)
dim(CellMixtures)
colnames(CellMixtures)

See ?BlueCode and ?CellMixtures for full documentation.

Vignettes

Two vignettes provide step-by-step:

vignette("vignette-simulation", package = "dicepro")
vignette("vignette-real-data",  package = "dicepro")

Citation

If you use dicepro in your research, please cite: When Less Is Not More: dicepro Mitigates the Impact of Incomplete Reference Matrices on Cellular Frequency Deconvolution.
Bioinformatics. doi:10.64898/2026.06.17.732876