decoupler

The library is organized into namespaced submodules. The standard way to use the library is to import it as dc.

• dc.mt: Methods. Contains enrichment/activity algorithms like ulm, mlm, ora, gsea, gsva, aucell, viper, zscore, waggr, mdt, and udt. Also includes dc.mt.decouple (multi-method) and dc.mt.consensus.
• dc.op: Prior knowledge (OmniPath). Functions for fetching/handling collectri, dorothea, progeny, hallmark, etc.
• dc.pp: Preprocessing. Tools for pseudobulk, filtering (filter_by_expr, filter_by_prop), and data manipulation (get_obsm, extract, swap_layer, read_gmt).
• dc.ds: Datasets. Bundled example datasets like toy, pbmc3k, and covid5k. Note: Check if the dataset is raw or normalized before use.
• dc.tl: Tools. Functions for ranking scores: rankby_group, rankby_obsm, rankby_order.
• dc.pl: Plotting. Visualization tools: barplot, dotplot, volcano, network, obsm.
• dc.bm: Benchmarking. Tools for evaluating methods: benchmark, metric, pl.

import decoupler as dc

Every enrichment method in decoupler requires a net: a long-format pandas.DataFrame that describes the relationship between biological programs and features (genes).

Net Structure

Usage Rules

• Weighted methods (ulm, mlm, viper, zscore, waggr, mdt, udt) use the weight column. The sign of the weight encodes activation or repression.
• Gene-set methods (ora, gsea, aucell, gsva) ignore the weight column.
• One row per edge: Each row represents a single connection between a source and a target.

import decoupler as dc
# Example of a net with source, target, and weight columns
net = dc.op.collectri(organism="human")
net.head()      # columns: source, target, weight

Decoupler provides several methods to infer enrichment scores, which can be categorized based on the type of network (prior) you are using:

1. Weighted Networks

Use these if your network contains signed weights (e.g., CollecTRI, DoRothEA, or PROGENy). Recommended methods include:

• ulm (Univariate Linear Model): The recommended default for TF/pathway activity. It is fast and robust.
• mlm (Multivariate Linear Model): Accounts for correlated regulons. Note that it can be unstable if the network is rank-deficient (highly collinear regulons).
• viper (VIPER regulon analysis): Corrects for pleiotropy and target overlap.
• waggr (Weighted Aggregate): Uses weighted mean, sum, or median with permutation p-values.
• zscore: A simple standardized weighted mean.

2. Unweighted Gene Sets

Use these if you are using gene sets without weights (e.g., MSigDB hallmarks or .gmt files). Recommended methods include:

• ora (Over-Representation Analysis): Fisher test on top/bottom features.
• gsea (Gene Set Enrichment Analysis): Ranked enrichment of gene sets.
• aucell (AUCell): Rank-based gene-set activity per cell.
• gsva (Gene Set Variation Analysis): Sample-relative gene-set variation.

3. Decision Trees

• mdt (Multivariate Decision Tree): Uses random-forest feature importance.
• udt (Univariate Decision Tree): Uses single-tree importance.

Tip: If you are unsure, you can run several methods and take a consensus using the multi-method approach.

The location of your results depends entirely on the type of data you pass to the method. This is a critical distinction for retrieving scores.

1. Using AnnData (In-place modification)

If you pass an AnnData object, the method returns None and writes the results directly into the object's .obsm attribute.

• Scores: Stored in .obsm["score_<method>"].
• P-values: If the method performs statistical testing, p-values are stored in .obsm["padj_<method>"].
• Retrieval: Use dc.pp.get_obsm(adata, "score_<method>") to safely access these scores.

2. Using pandas.DataFrame or a list (Return values)

If you pass a DataFrame or a list [matrix, obs, var], the method returns an (es, pv) tuple.

• es: The enrichment score matrix (observations × sources).
• pv: The p-values (this will be None for methods that do not perform statistical testing).

# If using AnnData
dc.mt.ulm(adata, net)
# Scores are NOT returned; they are inside adata
scores = dc.pp.get_obsm(adata, "score_ulm")

# If using DataFrame
es, pv = dc.mt.ulm(df, net)

All enrichment/activity methods in decoupler follow a unified calling convention: dc.mt.<method>(data, net, ...).

Accepted Input Types for data:

• AnnData object
• pandas.DataFrame
• A list containing [matrix, obs, var]

Required Input Formats:

• Data Matrix: Must be normalized (e.g., log1p transformed), not raw counts. Use the layer argument to specify which layer to use if using AnnData.
• Prior-knowledge Network (net): Must be a long-format pandas.DataFrame containing the columns source (the biological program/TF), target (the feature/gene), and an optional signed weight.

Shared Arguments:

• tmin (default: 5): The minimum number of targets a source must have in the data to be included. Sources with fewer than tmin targets are silently dropped. For small or toy networks, you may need to set tmin=3.
• raw: Boolean indicating if the input is raw (use with caution as normalization is expected).
• layer: String specifying the layer in AnnData to use.
• empty: Behavior for handling empty intersections.
• bsize: Batch size for processing.

import decoupler as dc
# Example of the unified call pattern
dc.mt.ulm(data=adata, net=net, tmin=3, layer='log1p_counts')

The decoupler.pl module provides a suite of plotting functions for visualizing enrichment scores and their relationships within single-cell datasets. Available visualization methods include:

• Bar plots: pl.barplot for displaying scores.
• Dot plots: pl.dotplot for visualizing scores across different groups or samples.
• Network plots: pl.network to visualize connections between targets and sources.
• Volcano plots: pl.volcano for visualizing statistical significance and effect size.
• Obs/Obsm plots: pl.obsbar and pl.obsm for visualizing scores relative to sample metadata or low-dimensional embeddings.
• Leading edge analysis: pl.leading_edge to identify contributing genes.

Other utility functions in this module include filtering tools (pl.filter_by_expr, pl.filter_by_prop, pl.filter_samples) and ordering functions (pl.order, pl.order_targets, pl.source_targets).