immunedeconv estimates cell fractions from bulk RNA-seq with one call

One interface over several competing cell fraction estimators

Bulk RNA-seq measures a mixture. A tumour biopsy sample, a tissue section, a sorted population pooled before sequencing: the counts that come back are a weighted sum of the cell types present, and the question every immunologist asks of that matrix is how much of each cell type is in it. Several methods estimate that from the expression profile, each with its own signature matrix, its own assumptions and its own reference. immunedeconv does not add a new estimator. It wraps the existing ones behind a shared calling convention so the choice of method becomes a string argument rather than a rewrite of your analysis.

The wrapper covers human methods such as CIBERSORT, EPIC, quanTIseq, TIMER, xCell, MCPcounter, ABIS and consensus_tme, and it adds a mouse-specific set that the R ecosystem previously lacked in a usable form. The homepage is omnideconv.org/immunedeconv/index.html and the documentation is published through pkgdown, with a getting started page, a detailed example and a separate detailed example for mouse data.

For anyone deciding whether to adopt it, the honest framing is that this is an interface and a maintenance layer, not an algorithmic advance. What you gain is a uniform call, a uniform output shape, and the per-method licence and citation information in one table.

Row names must be HGNC or MGI symbols, and that is the first failure

The input contract is strict and worth reading before anything else. The matrix has genes in rows and samples in columns, the column names are sample names, and the row names must be HGNC symbols for human data or MGI gene symbols for mouse data. A matrix keyed by Ensembl identifiers or by Entrez gene ids will not work as is.

That constraint is what makes the wrapper possible. Each underlying method matches its signature matrix against gene symbols, and the different methods disagree about symbol versions and about which genes they expect, so the package fixes one naming convention at the boundary and handles the rest internally. The cost is the same for every user: an identifier mapping step has to happen upstream, and it has to produce current symbols, since a matrix carrying deprecated symbols is a silent source of dropped genes.

For custom signatures the same rule applies in a looser form, because the package uses your own gene list or signature matrix, which means you decide the identifier space and you are responsible for it.

The human method list, and why ESTIMATE gets its own entry point

For human data the method is passed as a name, and the documented set is quantiseq, timer, cibersort, cibersort_abs, mcp_counter, xcell, epic, abis, consensus_tme and estimate. The typical call is a single line:

immunedeconv::deconvolute(gene_expression_matrix, "quantiseq")

ESTIMATE is the awkward member of that list, and the package gives it a separate function. The other methods return cell type fractions, while the ESTIMATE algorithm computes scores for the tumoral, immune and stromal components together with a tumour purity estimate for the sample. Those are scores and a purity value, not a set of fractions, so folding them into the same result shape would misrepresent what they are:

immunedeconv::deconvolute_estimate(gene_expression_matrix)

The distinction matters in a pipeline. A fraction vector can be compared across samples and plugged into a survival model. A purity score and three component scores have to be interpreted as scores, and treating them as fractions is how analysis papers end up with results nobody can reproduce. Using the dedicated entry point keeps that boundary visible in the code.

The mouse path has its own methods and its own gene conversion

Mouse data has a dedicated entry point, and the method set is smaller and different: mmcp_counter, seqimmucc, dcq and base. A mouse matrix is deconvoluted with:

immunedeconv::deconvolute_mouse(gene_expression_matrix, "mmcp_counter")

There is also a second route for mouse samples, and it is the one that surprises people. Human-based methods can be applied to mouse data by converting the genes to their human orthologues first, then calling the ordinary human function:

gene_expression_matrix <- immunedeconv::mouse_genes_to_human(gene_expression_matrix)
immunedeconv::deconvolute(gene_expression_matrix, "quantiseq")

The trade is obvious once stated. Converting to orthologues lets you reuse a human method you have already validated and cited, at the price of dropping mouse-specific genes and accepting a mapping that is one to many for some gene families. The native mouse methods avoid that translation. The package cites a dedicated paper for mouse transcriptomics deconvolution, which suggests treating the two paths as genuinely different methods rather than one being a fallback of the other.

Custom signatures extend the package beyond human and mouse

The most flexible feature is custom signatures. Some methods can be run with a signature you provide, either a full signature matrix or a plain list of signature genes for the cell types you care about. Because the information used to deconvolute the bulk comes from the user rather than from a bundled reference, these functions work for tissues and organisms the standard methods do not cover.

The available custom entry points are deconvolute_base_custom(), deconvolute_cibersort_custom() for the normalised and absolute CIBERSORT variants, deconvolute_epic_custom() and deconvolute_consensus_tme_custom(). The README notes that the functions may require different input data formats depending on the requirements of each method, and points at the per-function documentation for the details.

That caveat is the practical limit of the feature. You are filling in the reference that the method normally ships with, so the quality of the result depends on the quality of the signature you build, and the package cannot tell you whether your marker set is a good one. It is a route to a new tissue, not a shortcut around choosing markers.

The package is free, but the methods are not uniformly free

Licensing is where this project asks the most attention, and the README is unusually clear about it. The package itself is free, released under BSD, but you may need to obtain a licence to use the individual methods. The table of methods carries a licence column alongside organism and citation, and the entries differ: quanTIseq is listed as free under BSD, while TIMER is listed as free under GPL 2.0.

Those are not the same obligations, and the difference matters if your organisation redistributes software or runs the analysis as part of a commercial product. The general point is that wrapping a method in an R package does not change the terms attached to the method, and the table is where you check.

The citation requirements are as real as the licence ones. The README asks you to cite the package and the methods you use, listing a 2019 Bioinformatics evaluation of transcriptome-based cell type quantification methods, and a 2024 Bioinformatics Advances paper for the mouse and custom-based methods. Each method in the table carries its own reference as well, so a methods section for an analysis using this package has several entries to assemble.

Releases are sparse, and the docs are the maintained surface

The maintenance picture is modest and worth weighing. The current release is v2.1.4, published on 2026-05-14, and the two versions before it are 2.1.3 from 2023-10-18 and 2.1.2 from 2023-03-09, so the tag history is sparse by design or by circumstance. The last push to the repository was on 2026-08-03, and the repository is not archived, which means work continues on the branch even when no tag is cut. The default branch is master.

The repository is a conventional R package: DESCRIPTION, NAMESPACE, an R directory, man pages, tests, vignettes, a data directory, an inst directory, a Makefile and a pre-commit configuration, with a conda recipe directory and continuous integration workflows for tests and for conda builds. A bioconda recipe is linked, and the Makefile provides the usual developer targets such as install, check, docs and a conda build that runs conda build .

Two details in the packaging are worth a note for anyone automating an environment. The Makefile installs development dependencies from CRAN and from remotes, and the package itself is installed from a source checkout with:

R CMD INSTALL .

Documentation is built with pkgdown and published to GitHub pages by a deploy target, so the site and the package version can drift apart when the docs are rebuilt separately from a release.

Where this is the wrong tool

There are clear cases where reaching for immunedeconv is a mistake. If your data is single-cell or single-nucleus RNA-seq, this package is aimed at bulk matrices, and estimating cell fractions by deconvolution is the wrong operation on data that already counts cells. If you need absolute cell counts rather than relative fractions, note what the underlying methods return: a composition, where an increase in one cell type forces a decrease in another by construction, and the ESTIMATE path returns component scores plus a purity estimate rather than fractions of anything.

There is also a real risk in the interface itself. Because every method is one string argument away, it is easy to compare ten methods, pick whichever gives the cleanest separation, and report that as a finding. The README asks you to cite the package and the method you used, which is a reminder that the method is part of the claim, not a detail of the implementation.

The last practical limit is input hygiene. If your matrix is not keyed by current HGNC or MGI symbols, no method choice will save the run, and the fix is upstream of this package entirely.

Editorial conclusion

Use immunedeconv when your bulk RNA-seq matrix needs immune or stromal fractions and you would otherwise wire up one estimation method per analysis, and pick the method whose licence your project can carry. Do not use it as a drop-in for a mouse study without reading the mouse path, since the mouse methods are a smaller set and the orthologue conversion route loses mouse-specific signal. Before you commit, check three things: that your row names are HGNC symbols for human data or MGI symbols for mouse data, that the method you choose accepts your input format, and that the licence of that method, which for TIMER is GPL 2.0 while several others are free, matches your distribution model. The last push was on 2026-08-03 and the current release is v2.1.4.

Frequently asked questions

Official sources

1. Issues
2. omnideconv/immunedeconv on GitHub
3. Project website
4. README
5. Releases