Immune Deconvolution

Immune Deconvolution

Estimate immune and stromal cell composition from bulk RNA-seq using multiple algorithms. Wraps CIBERSORT, quanTIseq, EPIC, xCell, MCP-counter, TIMER, and ESTIMATE through the immunedeconv unified interface.

When to Use This Skill

Activate when the user requests:

• Immune cell type estimation from bulk RNA-seq or microarray
• Tumor microenvironment characterization
• Immune subtype classification across a cancer cohort
• Tumor purity estimation from expression data
• Comparison of immune infiltration between conditions or subtypes
• Multi-method deconvolution benchmarking

Inputs

| Data Type | Format | Source | |-----------|--------|--------| | Expression | TPM matrix (genes x samples), not log-transformed | TCGA via TCGAbiolinks, GEO | | Clinical | Tabular (subtype, stage, outcome) | TCGA GDC, cBioPortal | | Signature matrix | LM22.txt (for CIBERSORT only) | cibersortx.stanford.edu (registration required) |

All methods except TIMER and ESTIMATE need TPM with HGNC gene symbols as rownames. Raw counts and Ensembl IDs will produce wrong results silently.

---

Preparing Input from TCGA

library(TCGAbiolinks)
library(SummarizedExperiment)

query  quanTIseq: 10 immune types + "Other". Validated against flow cytometry and IHC.
  -> EPIC: 6 immune types + cancer cells. Built for solid tumors.
  -> CIBERSORT absolute mode: 22 immune subtypes. Requires registration.

Relative proportions (which immune cells dominate, not how much)?
  -> CIBERSORT relative: 22 types. Gold standard, widely published.
  -> quanTIseq also works (ignore "Other", compare immune fractions).

Enrichment scores (rank samples by infiltration, not quantify)?
  -> xCell: 64 cell types. Broadest coverage, good for discovery.
  -> MCP-counter: 8 immune + 2 stromal. Fewest assumptions, works well with noisy data.

Immune vs stromal vs tumor purity?
  -> ESTIMATE: immune score, stromal score, purity estimate.
  -> Or use "Other" fraction from quanTIseq/EPIC as purity proxy.

Cancer-type-specific correction?
  -> TIMER: 6 immune types, pre-built models per TCGA cancer type.
  -> ConsensusTME: cancer-specific gene sets, uses ssGSEA.

Don't know which to pick?
  -> Run quanTIseq + MCP-counter + EPIC. If all three agree on a trend,
     the signal is real. Disagreement means the effect is method-dependent.

Score Interpretation

This matters more than method choice. Getting it wrong leads to wrong biological conclusions.

| Comparison | Valid methods | Invalid methods | |------------|-------------|-----------------| | Between samples (sample A has more CD8 T cells than B) | All methods | - | | Between cell types (more B cells than T cells in sample A) | quanTIseq, EPIC, CIBERSORT | xCell, MCP-counter, TIMER | | Absolute quantification (15% of cells are CD8 T cells) | quanTIseq, EPIC, CIBERSORT-abs | Everything else |

xCell and MCP-counter scores are arbitrary units. A CD8 score of 0.4 from xCell and 3.7 from MCP-counter cannot be compared to each other, and neither means "40% CD8 T cells."

---

immunedeconv Setup

# Install: wraps 9 methods in one API
# remotes::install_github("omnideconv/immunedeconv")
library(immunedeconv)  # v2.1.0+

# For CIBERSORT (optional, requires registration at cibersortx.stanford.edu):
# Download CIBERSORT.R and LM22.txt, then:
# set_cibersort_binary("/path/to/CIBERSORT.R")
# set_cibersort_mat("/path/to/LM22.txt")

quanTIseq

qt  0.05 means the deconvolution fit is unreliable — flag or exclude.
# Access via running CIBERSORT directly (not through immunedeconv wrapper).

xCell

xc  Include ESTIMATE purity as covariate in linear model
  Correlating deconvolution scores with mutations or expression
    -> Partial correlation controlling for purity
  Filtering bad samples
    -> Remove samples with ESTIMATE purity  These already account for non-immune content via "Other"/"otherCells"
  Comparing within the same tumor type with similar purity distributions
    -> Correction adds noise without removing bias

# Purity as covariate
est_scores  0.5 between most pairs for CD8+ T cells
# rho  M1 in most solid tumors
  If all CD8 fractions are 0: gene symbols may not match quanTIseq signature

ESTIMATE sanity:
  TCGA-BRCA median purity: ~0.75
  Basal: lower purity (0.55-0.70), Luminal A: higher purity (0.80-0.90)
  If all purities cluster near 1.0 or near 0: wrong platform setting or wrong input scale

Cross-method concordance:
  CD8+ T cell Spearman rho > 0.5 between quanTIseq, EPIC, MCP-counter
  rho  0.05 for > 30% of samples: signature doesn't fit this cohort
  xCell returns all zeros for many cell types: gene overlap too low
  TIMER returns NA: cancer type not in the pre-built model set
  quanTIseq crashes: duplicate gene symbols in rownames (must deduplicate)
  Only 1 sample: TIMER and ConsensusTME need >= 2 samples per cancer type

Common Pitfalls

Input

1. Raw counts instead of TPM: quanTIseq, EPIC, xCell, MCP-counter, and CIBERSORT expect TPM. Feeding raw counts compresses low-expression signatures and inflates high-expression ones. Convert first: `tpm 0.05 have unreliable estimates. Excluding these is standard practice but often forgotten.
2. TIMER on unsupported cancer types: TIMER's regression models are pre-built for specific TCGA indications. Running it on a cancer type not in the training set gives uninterpretable results.
3. Single-sample runs with TIMER or ConsensusTME: These methods need at least 2 samples of the same cancer type. A single sample will either error or return NAs.
4. Mixing microarray and RNA-seq without batch correction: Deconvolution signatures are sensitive to platform effects. Don't pool microarray and RNA-seq samples without explicit normalization.

Advanced: Single-Cell Reference-Based Deconvolution

When matched scRNA-seq data is available for the same tissue type, second-generation methods outperform signature-based approaches.

# BayesPrism: top performer in 2024-2025 benchmarks
# install.packages("BayesPrism")  # or InstaPrism for faster runtime
library(BayesPrism)

# Requires: scRNA-seq reference (genes x cells) + cell type labels
# bulk: genes x samples matrix (counts, not TPM)
bp  BayesPrism or DWLS. Better accuracy than fixed signatures.
  No scRNA-seq reference, just bulk RNA-seq?
    -> quanTIseq + EPIC + MCP-counter (signature-based).
  Public scRNA-seq atlas exists for the tissue?
    -> Consider BayesPrism with the atlas as reference, but be aware
       of batch effects between your bulk data and the atlas.

Related Skills

• [cancer-multiomics](../cancer-multiomics/SKILL.md): TCGA data retrieval and expression matrix preparation (input for deconvolution)
• [survival-analysis](../survival-analysis/SKILL.md): Use deconvolution scores as covariates in Cox models or KM stratification

Public Datasets for Testing

| Dataset | Samples | Use Case | |---------|---------|----------| | TCGA-BRCA | 1098 | Breast cancer, strong immune subtype differences (Basal vs Luminal) | | TCGA-SKCM | 472 | Melanoma, high immune infiltration, immunotherapy response data | | TCGA-LUAD | 585 | Lung adenocarcinoma, mixed immune landscape | | TCGA-COAD | 521 | Colorectal, MSI-H tumors are immune-hot vs MSS cold |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zamushwani2
• Source: zamushwani2/biomedical-ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.