decoupler

name

decoupler

description

Use for any task involving the decoupler library — inferring biological activity/enrichment scores from omics data (bulk, single-cell, spatial). Triggers on estimating transcription factor (TF) activity, pathway activity, or gene-set enrichment from an AnnData/DataFrame; running ulm, mlm, ora, gsea, gsva, aucell, viper, zscore, waggr, mdt, udt; multi-method consensus; fetching prior knowledge (CollecTRI, DoRothEA, PROGENy, MSigDB hallmarks, OmniPath); pseudobulk and expression filtering; using bundled example datasets (pbmc3k, covid5k, erygast1k, hsctgfb, msvisium, knocktf, toy) and whether they are raw counts or normalized; ranking/plotting activity scores; or benchmarking methods against ground truth. This is a router skill — read the relevant file under references/ before writing decoupler code, because outputs land in different places and several defaults are non-obvious.

decoupler

decoupler estimates biological activities (transcription factors, pathways, gene sets) from omics data. You give it a data matrix (observations × features, e.g. cells × genes) and a prior-knowledge network (which features belong to which biological program), and it returns an enrichment score per observation per program — all methods sharing one unified interface. Part of scverse; works directly on AnnData, pandas.DataFrame, or raw matrices.

This skill is a router. Each topic below has a detailed reference file with exact signatures and footguns. Read the relevant reference before writing code — do not rely on memory of the API, because results are written to different places depending on the input type and several methods have non-obvious defaults.

Two cross-cutting concepts (read these first if unsure)

• The unified method call — every method is called the same way: dc.mt.<method>(data, net, tmin=5, ...). Covers the accepted input types (AnnData / DataFrame / [matrix, obs, var] list), the shared arguments (tmin, raw, layer, empty, bsize), and the big footguns: input must be normalized (e.g. log1p), not raw counts, and net must be a long-format source/target/weight table.

• Where the results go — the return type depends on the input type. AnnData → written in place into .obsm["score_<method>"] (and .obsm["padj_<method>"] if the method tests), returns None. DataFrame / list → returns an (es, pv) tuple (pv is None for non-testing methods). Read scores back out of an AnnData with dc.pp.get_obsm. This is the #1 thing agents get wrong.

Task → reference file

If the task is…	Read
starting from scratch — set up an end-to-end run (load data → get a net → score → rank → plot)	references/getting-started.md
how to call a method, what data/net formats are accepted, tmin/raw/layer semantics	references/calling-convention.md
where scores land and how to read them back (.obsm vs (es, pv) tuple, get_obsm)	references/io-and-outputs.md
choosing and configuring a method — ulm/mlm/ora/gsea/gsva/aucell/viper/zscore/waggr/mdt/udt + their kwargs	references/methods.md
getting prior knowledge — TF regulons (CollecTRI, DoRothEA), pathways (PROGENy), gene sets (MSigDB hallmarks), OmniPath, .gmt, organism translation	references/priors.md
preprocessing — pseudobulk from single cell, expression/sample filtering, layers, spatial kNN	references/preprocessing.md
running many methods at once and combining them into a consensus	references/multi-method.md
ranking activity scores by group/ordering and plotting them (barplot, dotplot, volcano, network) or overlaying them on a UMAP / spatial H&E via scanpy	references/ranking-and-plotting.md
benchmarking methods/nets against a perturbation ground truth

Quick orientation (submodule map)

decoupler exposes everything through namespaced submodules — canonical import is import decoupler as dc:

• dc.mt — methods: the enrichment/activity algorithms (ulm, mlm, ora, gsea, gsva, aucell, viper, zscore, waggr, mdt, udt) plus dc.mt.decouple (run several) and dc.mt.consensus. dc.mt.show() lists them.
• dc.op — prior knowledge (OmniPath): collectri, dorothea, progeny, hallmark, resource, translate.
• dc.pp — preprocessing: pseudobulk, filter_by_expr, filter_by_prop, filter_samples, get_obsm, extract, swap_layer, knn, read_gmt.
• dc.ds — datasets: toy (used in every example: adata, net = dc.ds.toy()), pbmc3k, covid5k, and other real examples. They differ in normalization state (some raw counts, some already log-normalized) — see datasets.md before scoring one.
• dc.tl — tools: rankby_group, rankby_obsm, rankby_order.
• dc.pl — plotting: barplot, dotplot, volcano, network, obsm, etc.
• dc.bm — benchmarking: benchmark, metric, pl.

Conventions used throughout

• Data = observations × features (cells/samples × genes), normalized (log1p), not raw counts. Net = long-format DataFrame: source (program), target (feature), optional signed weight.
• Output score matrices are observations × sources. AnnData results live in .obsm under score_<method> / padj_<method>.
• tmin (default 5) silently drops sources with fewer than tmin targets present in the data — lower it for small/toy nets (examples use tmin=3).
• verbose=True on any method prints the pruning/run log — use it to see how many sources survived tmin.
• Plotting: use dc.pl.* for summary plots and scanpy sc.pl.umap / sc.pl.spatial (on a dc.pp.get_obsm score AnnData) for embedding/tissue overlays. Never reimplement a plot from matplotlib primitives — see ranking-and-plotting.md.