decoupler: Omics Activity Inference Guide

decoupler (and its R/Bioconductor implementation decoupleR) is an open-source computational framework designed to infer biological activities—such as transcription factor (TF) dynamics, signaling pathway states, and kinase activities—from high-throughput omics data. Developed by the Saez-Rodriguez Lab and maintained as part of the scverse and Bioconductor ecosystems, the package provides a unified statistical interface to over a dozen enrichment algorithms coupled with curated prior-knowledge networks. This guide details how to install decoupleR in both R and Python, run footprint-based activity models, interpret numerical outputs, troubleshoot common dataset issues, and evaluate alternative computational methods.

What it is used for in research

High-throughput profiling technologies—including bulk RNA-seq, single-cell RNA-seq (scRNA-seq), spatial transcriptomics, and phosphoproteomics—generate high-dimensional matrices containing expression levels across tens of thousands of molecular features. However, direct mRNA abundance often correlates poorly with functional transcription factor or kinase regulatory activity due to post-transcriptional buffering, translational control, and post-translational modifications. A transcription factor may be abundant at the transcript level yet completely inactive due to lack of phosphorylation or nuclear localization.

Rather than measuring regulator expression directly, footprint-based activity inference estimates a regulator’s functional activity by evaluating the collective expression shifts of its downstream target genes (its regulon or pathway footprint) against curated prior knowledge. decoupleR unifies multiple footprint and enrichment algorithms into a single syntax. Key research applications include:

• Transcription Factor Activity Inference: Characterizing regulatory programs in development and disease using curated gene regulatory networks such as CollecTRI and DoRothEA.
• Signaling Pathway Activity Estimation: Measuring downstream pathway activation (such as MAPK, TGF-β, NF-κB, or p53 signaling pathway regulatory models) using functional footprint resources like PROGENy.
• Kinase Activity Inference: Estimating upstream kinase activities from phosphoproteomic profiles using kinase-substrate interaction databases.
• Single-Cell and Spatial Deconvolution: Extracting cell-type specific regulatory dynamics across single-cell clusters and spatial tissue domains, complementing epigenomic analyses performed in tools like the ArchR single-cell epigenomic framework.

Install or access (official source only)

decoupleR is maintained in two official language environments: as an R package distributed via Bioconductor, and as a high-performance Python package distributed via PyPI and Conda-Forge under the scverse umbrella.

R and Bioconductor Installation

In R (version 4.0 or higher), install decoupleR directly through BiocManager:

if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("decoupleR")

For system dependencies and package management best practices across environments, refer to our guide on installing R packages from Bioconductor and CRAN. Confirm the installation in R with:

packageVersion("decoupleR")

Python and Conda Installation

In Python (version 3.12 or higher), install the decoupler package using pip:

pip install decoupler

Alternatively, install via conda or mamba from the conda-forge channel:

conda install -c conda-forge decoupler-py

Confirm the Python installation by importing the library:

python -c "import decoupler as dc; print(dc.__version__)"

Step-by-step task

The following five-step workflow demonstrates how to infer human transcription factor activities from single-cell RNA-seq data using CollecTRI and the Univariate Linear Model (ULM) method.

Step 1: Load and Normalize the Omics Feature Matrix

decoupleR expects an omics matrix containing molecular feature readouts (such as log-normalized gene expression counts per sample or differential expression statistics). In Python using Scanpy and AnnData:

import scanpy as sc
import decoupler as dc

# Load sample single-cell dataset (e.g., 3k PBMCs)
adata = sc.datasets.pbmc3k_processed()

# Ensure expression data is log-normalized
# sc.pp.normalize_total(adata, target_sum=1e4)
# sc.pp.log1p(adata)

Step 2: Retrieve the Prior Knowledge Regulatory Network

Retrieve the CollecTRI regulatory network, an extensively curated resource compiling transcription factor-target interactions with mode of regulation (+1 for activation, -1 for repression):

# In Python:
net = dc.get_collectri(organism="human", split_complexes=False)

# In R:
# net <- decoupleR::get_collectri(organism = "human", split_complexes = FALSE)

Step 3: Run the Univariate Linear Model (ULM)

The Univariate Linear Model fits a separate linear regression for each sample and regulator:

y_i = β₀ + β₁w_ij + ε_i

where y_i is the observed expression level of target gene i, and w_ij is the regulatory weight / mode of regulation of regulator j on target i. The inferred activity score is the t-value of the estimated slope β₁:

t = β̂₁ / SE(β̂₁)

Execute ULM in Python, storing the results directly in adata.obsm:

dc.run_ulm(
    mat=adata,
    net=net,
    source="source",
    target="target",
    weight="weight",
    min_n=5,
    verbose=True
)

Equivalent command in R:

contrast_acts <- decoupleR::run_ulm(
    mat = mat,
    network = net,
    .source = "source",
    .target = "target",
    .mor = "mor",
    minsize = 5
)

Step 4: Compute Multi-Method Consensus Activities

To maximize predictive power and reduce method-specific bias, compute the consensus score, which calculates the mean z-score across top-performing algorithms:

dc.run_consensus(
    mat=adata,
    net=net,
    source="source",
    target="target",
    weight="weight",
    min_n=5
)

Step 5: Visualize Activities on Single-Cell Embeddings

Extract inferred regulator scores and project them onto dimensionality reduction embeddings (such as UMAP) to identify cluster-specific transcriptional regulators:

# Extract activities into a DataFrame
acts = dc.get_acts(adata, obsm_key="ulm_estimate")

# Assign specific TF activity to AnnData obs for visualization
adata.obs["STAT1_activity"] = acts["STAT1"].values

# Plot UMAP colored by cell cluster and TF activity
sc.pl.umap(adata, color=["louvain", "STAT1_activity"], cmap="coolwarm")

Output and how to read it

decoupleR formats its outputs to match native data structures in both Python and R:

• Python (AnnData): Inferred activities are stored in adata.obsm['<method>_estimate'] (a matrix of samples/cells by regulators), and nominal p-values are stored in adata.obsm['<method>_pvals'].
• R (Tidy Tibble): Results are returned as a long-format data frame containing the columns: statistic (algorithm name), source (regulator symbol), condition (sample or cell ID), score (inferred t-statistic), and p_value.

Interpreting Activity Scores

Understanding the numerical output requires evaluating both the sign and magnitude of the score:

• Score Sign (t > 0 vs t < 0): A positive score indicates that targets activated by the regulator are coordinately upregulated while repressed targets are downregulated—demonstrating active regulatory induction. Conversely, a negative score indicates that activated targets are downregulated and repressed targets are elevated—indicating upstream transcriptional repression.
• Score Magnitude (t-statistic): Because ULM and MLM return standardized t-statistics, the magnitude reflects statistical confidence relative to the background gene expression distribution. In single-cell datasets, scores exceeding |t| > 2 typically align with p < 0.05 significance.

Benchmark Findings and Method Guidance

In the comprehensive benchmark published by Badia-i-Mompel et al. (2022), computational methods were evaluated across transcriptomic and phosphoproteomic perturbation datasets. Key empirical findings include:

• Top Performing Methods: The Consensus score, Multivariate Linear Models (MLM), and Univariate Linear Models (ULM) consistently achieved the highest accuracy in recovering perturbed regulators.
• Value of Interaction Weights: Methods incorporating signed interaction weights (mode of regulation) significantly outperformed unweighted approaches (P < 2.2 × 10^-16, one-sided Wilcoxon signed-rank test).
• Network Completeness: Removing true edges from prior knowledge networks caused significantly greater performance degradation than introducing false edges (P < 2.2 × 10^-16), demonstrating that comprehensive meta-resources like CollecTRI provide resilient activity estimates.
• Execution Speed: The Python implementation achieves a median runtime of 0.44 ms per sample and regulator, compared to 1.44 ms in R (benchmarked on an Intel Core i7-8550U CPU @ 1.80 GHz), making Python the preferred choice for massive single-cell atlases.

Troubleshooting

Below are solutions for the most frequent issues encountered when running decoupleR workflows:

Symptom	Underlying Cause	Resolution
All activity scores return NaN or zero	Gene identifier mismatch between the input matrix (e.g., Ensembl IDs) and the network (HGNC symbols).	Convert gene identifiers in the count matrix to official gene symbols using AnnotationDbi, org.Hs.eg.db (R), or pyensembl / mygene (Python) before running decoupleR.
Key transcription factors absent from output	Regulon size filtered out by min_n (default 5) due to low overlap with measured features.	Inspect feature overlap with dc.filter_by_feature(). For low-depth datasets, lower min_n to 3, or impute dropout using consensus aggregation.
Memory exhaustion on single-cell datasets	Converting sparse expression matrices into dense arrays before passing to linear models.	Ensure input remains as scipy.sparse.csr_matrix in Python; decoupler natively processes sparse formats without dense matrix conversion.
Extreme or skewed t-statistics	Supplying raw sequencing read counts instead of log-normalized expression or differential statistics.	Apply library size normalization and logarithmic transformation (log(1 + CPM) or log(1 + TPM)) before footprint model fitting.

Free alternatives

The following table compares decoupleR with other free, open-source computational tools used for biological activity inference from omics data:

Tool	Primary Languages	Regulatory Model / Inputs	Interaction Weights	Consensus Mode	Primary Strengths
decoupleR / decoupler	R & Python	Prior knowledge networks (CollecTRI, DoRothEA, PROGENy)	Yes (+1/-1 MoR and continuous weights)	Yes (mean z-score across algorithms)	Unified API across 11+ methods; native AnnData & Seurat integration; high speed (~0.44 ms/sample-regulator).
VIPER	R (Bioconductor)	ARACNe-inferred interactomes and regulons	Yes (mode of regulation and pleiotropy)	No	Rigorous master regulator analysis in cancer systems biology; non-commercial license for certain subcomponents.
AUCell	R & Python (SCENIC)	Rank-based gene expression recovery curves	No (binary unweighted gene sets)	No	Non-parametric scoring robust to zero-inflation and single-cell dropouts; independent of gene scaling.
GSVA	R (Bioconductor)	Non-parametric kernel estimation across samples	No (binary gene sets)	No	Standard for unsupervised pathway variation in bulk cohort studies; computationally heavy on large cell numbers.
PROGENy	R & Python	Empirically derived pathway footprint weights	Yes (continuous regression weights)	No	Exceptional specificity for 14 canonical signaling pathways; available directly via decoupleR wrappers.

FAQ

What is decoupleR used for in research?

decoupleR is used to estimate biological activities—such as transcription factor activation, signaling pathway status, and kinase activity—from transcriptomic and proteomic data. By coupling molecular readouts with prior knowledge networks, it translates high-dimensional gene expression into interpretable regulatory mechanisms.

How does decoupleR differ from traditional GSEA?

Traditional Gene Set Enrichment Analysis (GSEA) treats gene sets as unordered, unweighted lists of genes. decoupleR footprint methods (such as ULM and MLM) explicitly model the sign (activation vs repression) and magnitude of interaction weights, resulting in significantly higher sensitivity and regulatory resolution.

Should I run decoupleR on raw counts or normalized counts?

Never run decoupleR on raw sequencing counts. For single-cell and cohort expression matrices, provide log-normalized counts (log(1 + CPM) or log(1 + TPM)). For group-level comparisons, provide differential expression summary statistics (t-values or log2 fold changes).

Which algorithm in decoupleR yields the most accurate results?

Empirical benchmarking by Badia-i-Mompel et al. (2022) established that the multi-method Consensus score, the Multivariate Linear Model (MLM), and the Univariate Linear Model (ULM) achieve the highest accuracy in predicting true perturbed regulators.

Can decoupleR analyze phosphoproteomics data?

Yes. decoupleR interfaces with kinase-substrate interaction databases through OmniPath, allowing researchers to input phosphosite abundance matrices and infer upstream kinase activities using the same footprint modeling framework.

How should decoupleR be cited in academic literature?

Cite the original methods paper by Badia-i-Mompel et al. (2022), published in Bioinformatics Advances (DOI: 10.1093/bioadv/vbac016). For general standards on software citation, consult our guide to citing scientific software and R packages.

Sources (official docs)

• Badia-i-Mompel, P., Vélez Santiago, J., Braunger, J., Geiss, C., Dimitrov, D., Müller-Dott, S., Taus, P., Dugourd, A., Holland, C. H., Ramirez Flores, R. O., & Saez-Rodriguez, J. (2022). decoupleR: ensemble of computational methods to infer biological activities from omics data. Bioinformatics Advances, 2(1): vbac016. https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9710656/ (Checked 2026-11-09).
• Bioconductor Project. (2026). decoupleR: Ensemble of computational methods to infer biological activities from omics data (Bioconductor Release 3.20, Package Version 2.17.0). https://bioconductor.org/packages/release/bioc/html/decoupleR.html (Checked 2026-11-09).
• Python Package Index (PyPI) & scverse Project. (2026). decoupler: Python package to perform enrichment analysis from omics data (Version 2.3.1). https://pypi.org/project/decoupler/ and https://decoupler.scverse.org/ (Checked 2026-11-09).
• Saez Lab. (2026). decoupleR Documentation, OmniPath Integration, and Vignettes. Heidelberg University. https://saezlab.github.io/decoupleR/ (Checked 2026-11-09).