Decoupler

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

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.