bulkdeconv

Cell-type deconvolution of human and mouse tumor bulk RNA-seq: 24 published methods through one function.

res <- bulkdeconv(tpm, expr = "tpm", species = "human", method = "quantiseq")
res$score   # samples x cell types

Documentation: https://daikikumakura.github.io/bulkdeconv/ · Releases

Workflow

  gene symbol × sample table (TPM; counts for seq-ImmuCC)
                 │
   bulkdeconv_methods()      which methods fit the species and the data?
                 │
   bulkdeconv(data, expr, species, method, ...)
                 │
   res$score      samples × cell types
   res$metadata   what the numbers are and what may be compared
   res$qc         input checks and signature coverage
Function What it does
bulkdeconv() Runs one method and returns score, metadata and qc
bulkdeconv_methods() Lists the methods with species, input scale, minimum samples, output kind, licence and whether they are ready to run
bulkdeconv_install() Installs the packages of EPIC, DCQ or SSMD into a private library

Installation

install.packages(c("remotes", "BiocManager"))
remotes::install_github("DaikiKumakura/bulkdeconv", repos = BiocManager::repositories())

This is all for the 19 built-in methods. For the three that run from their original packages, whose licences do not allow shipping them here, install once:

bulkdeconv::bulkdeconv_install(c("epic", "dcq", "ssmd"))

They go into a private library (tools::R_user_dir("bulkdeconv", "data"), changeable with options(bulkdeconv.lib = "path")) at the versions recorded in the registry, and each method runs in its own R process, so your normal library is not touched and methods cannot conflict.

Quick start

With RSEM output, rsemverse reads the table in the right layout:

tpm <- rsemverse::rsem_read("data", "metadata.csv", species = "human", expr = "tpm")

res <- bulkdeconv::bulkdeconv(tpm, "tpm", "human", "mcp_counter")
res$score                    # samples x MCP-counter abundance scores
res$metadata$output_class    # what the numbers are
res$metadata$comparability   # what may be compared
res$qc                       # input and signature-coverage checks

Input

One gene symbol per row and one sample per column, with the symbols either in the first column or as row names (the table rsemverse::rsem_read() returns); a numeric matrix with row names also works.

gene S1 S2
TP53 12.4 10.9
... ... ...

Methods

Method Species Built in Output Min. samples
quantiseq human yes fraction 1
mcp_counter human yes abundance score 1
xcell human yes enrichment score 2
xcell2 human, mouse yes (9 reference presets) enrichment score 1
estimate human yes enrichment score 1
consensus_tme human yes enrichment score 1
immucellai2 human yes fraction 1
imsig human yes abundance score 2
spatialdecon_safetme human yes abundance estimate 1
abis human yes (blood-derived signatures) abundance estimate 1
timer human yes abundance score 2
gedit human yes (2 reference presets) fraction 1
danaher human yes abundance score 1
charoentong human yes enrichment score 1
bindea human yes enrichment score 1
puree human no: bulkdeconv_install("puree") (downloads the model) fraction (tumor purity) 1
mysort human no: bulkdeconv_install("mysort") fraction (percent) 1
epic human no: bulkdeconv_install("epic") fraction 1
mmcp_counter mouse yes abundance score 1
immucellai_mouse mouse yes fraction 2
seqimmucc mouse yes (LLSR; counts) fraction 1
base mouse yes enrichment score 2
dcq mouse no: bulkdeconv_install("dcq") relative quantity 1
ssmd mouse no: bulkdeconv_install("ssmd") marker modules 6

bulkdeconv_methods() gives the full table. EPIC and PUREE are free for non-commercial use only, and SSMD and mySORT declare no licence; this is reported when run. PUREE's model is not bundled: bulkdeconv_install("puree") downloads it from a recorded commit and checks it.

Method options

Options are passed by name through ...:

Option Methods
preset xcell2 (reference set, for example "ImmGenData" for mouse); gedit ("HPCA", default, or "ImmunoStates")
cancer_type consensus_tme; required for timer
tissue immucellai2, ssmd
n_permutations, seed base
bulkdeconv(tpm, "tpm", "mouse", "xcell2", preset = "ImmGenData")

Reading the result

Validation

The 15 built-in methods of the first release are checked in the tests against output recorded from the original implementations; on a clean installation from GitHub, all 15 ran without any extra step, and EPIC, DCQ and SSMD ran after bulkdeconv_install(). GEDIT is checked by recovering the proportions of noise-free mixtures of its reference profiles, and the Danaher and Charoentong scores against their published definitions (mean log2 expression of marker genes; ssGSEA). PUREE reproduces the purities of its original test data exactly; mySORT matches the authors' example output for 21 of 24 samples (the others differ where two of its model settings fit almost equally well). R CMD check passes on Linux, macOS and Windows in CI. Sources, licences and the few deliberate differences from the originals are listed in inst/COPYRIGHTS and the registry (inst/registry/).

Related tools

Citation

Cite the archived version: https://doi.org/10.5281/zenodo.24210481 (all versions; Zenodo lists the DOI of each), and the method you used: its source is listed in bulkdeconv_methods() and inst/COPYRIGHTS.

Licence

GPL-3. The built-in methods are ports of published code (GPL-2 or later, GPL-3, MIT); sources are in inst/COPYRIGHTS. The three separately installed methods keep their own licences, which the registry lists and which are reported when a method runs.