dicepro

# dicepro

<!-- badges -->

<!-- badges -->

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)

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

------------------------------------------------------------------------

## Quick Start

### Simulated Data

``` r
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)

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

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

``` r
out <- dicepro(
  reference        = BlueCode,
  bulk             = CellMixtures,
  methodDeconv     = "CSx",
  cibersortx_email = "your@email.com",
  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:

| Element | Description |
|----|----|
| `$hyperparameters` | Best $\lambda$ and $\gamma$ found by the search |
| `$metrics` | Loss and constraint value at the optimum |
| `$trials` | data.frame of all evaluated hyper-parameter configurations |
| `$W` | Optimized reference matrix (including unknown cell types) |
| `$H` | Estimated cell-type proportions (samples x cell types) |
| `$plot` | Pareto frontier |
| `$plot_hyperopt` | Hyper-parameter scatter matrix (ggplot2) |

------------------------------------------------------------------------

## 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)

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

``` r
data(CellMixtures)
dim(CellMixtures)
colnames(CellMixtures)
```

See `?BlueCode` and `?CellMixtures` for full documentation.

------------------------------------------------------------------------

## Vignettes

Two vignettes provide step-by-step:

``` r
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>

------------------------------------------------------------------------