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
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 |
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.
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
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 |
| ... | ... | ... |
expr = "tpm") except seqimmucc, which takes
counts. A wrong scale is refused with a message that says so.| 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.
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")
res$metadata$output_class says what the numbers are: fractions, abundance
scores, enrichment scores or marker modules. Only fractions sum to a
composition; scores compare one cell type across samples, not cell types
with each other.xcell,
xcell2, consensus_tme, imsig, timer, charoentong, bindea,
mysort, immucellai_mouse, ssmd, base) warn when there are fewer than 10 samples. Use samples from one
cohort for relative comparisons.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/).
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.
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.