decoupler 2.1.6__tar.gz → 2.2.0__tar.gz

{decoupler-2.1.6 → decoupler-2.2.0}/.github/workflows/test.yaml

@@ -87,7 +87,7 @@ jobs:
           uvx hatch run ${{ matrix.env.name }}:cov-report   # report visibly
           uvx hatch run ${{ matrix.env.name }}:coverage xml # create report for upload
       - name: Upload coverage
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           fail_ci_if_error: true
           use_oidc: true

{decoupler-2.1.6 → decoupler-2.2.0}/.pre-commit-config.yaml

@@ -7,16 +7,16 @@ default_stages:
 minimum_pre_commit_version: 2.16.0
 repos:
   - repo: https://github.com/biomejs/pre-commit
-    rev: v2.4.10
+    rev: v2.5.2
     hooks:
       - id: biome-format
         exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.21.0
+    rev: v2.25.1
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.9
+    rev: v0.15.20
     hooks:
       - id: ruff-check
         types_or: [python, pyi, jupyter]

{decoupler-2.1.6 → decoupler-2.2.0}/CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning][].
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
+## 2.2.0
+
+### Added
+- Bundled a Claude Code [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) that teaches coding agents to use decoupler correctly (method selection, calling conventions, output locations, priors, datasets, and benchmarking)
+- Added the `decoupler-install-skills` console script to install the skill into `~/.claude/skills/decoupler/` (use `--force` to refresh after upgrading, or `--print-path` to point `CLAUDE_SKILLS_PATH` at the bundled copy in place)
+
 ## 2.1.6
 
 ### Bugfixes

{decoupler-2.1.6 → decoupler-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decoupler
-Version: 2.1.6
+Version: 2.2.0
 Summary: Python package to perform enrichment analysis from omics data.
 Project-URL: Documentation, https://decoupler.readthedocs.io/
 Project-URL: Homepage, https://github.com/scverse/decoupler
@@ -83,10 +83,8 @@ Description-Content-Type: text/markdown
 [badge-adown]: https://static.pepy.tech/badge/decoupler
 [badge-stars]: https://img.shields.io/github/stars/scverse/decoupler?style=flat&logo=github&color=yellow
 
-`decoupler` is a python package containing different enrichment statistical
-methods to extract biologically driven scores
-from omics data within a unified framework. This is its faster and memory efficient Python implementation,
-a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
+`decoupler` is a python package containing different enrichment statistical methods to extract biologically driven scores from omics data within a unified framework.
+This is its faster and memory efficient Python implementation, a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
 
 [//]: # (numfocus-fiscal-sponsor-attribution)
 
@@ -109,7 +107,7 @@ in particular, the [API documentation][].
 
 ## Installation
 
-You need to have Python 3.10 or newer installed on your system.
+You need to have Python 3.11 or newer installed on your system.
 If you don't have Python installed, we recommend installing [uv][].
 
 There are several alternative options to install decoupler:
@@ -138,6 +136,20 @@ mamba create -n=dcp conda-forge::decoupler-py
 pip install git+https://github.com/scverse/decoupler.git@main
 ```
 
+## Claude Code Skill
+
+decoupler ships an [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) for [Claude Code](https://claude.com/claude-code) that teaches the agent to use the library correctly. Install it once into your personal skills directory:
+
+```bash
+decoupler-install-skills
+```
+
+This copies the skill to `~/.claude/skills/decoupler/`, making it available in **every** project (re-run with `--force` after upgrading). Once installed, just ask Claude Code to do decoupler tasks ("find the most active TFs in this cell cluster", "score hallmark gene sets with ora", "build a consensus across methods") and the skill is consulted automatically. To avoid copying into your home directory, point Claude Code at the bundled copy instead:
+
+```bash
+export CLAUDE_SKILLS_PATH="$(decoupler-install-skills --print-path)"
+```
+
 ## Release notes
 
 See the [changelog][].

{decoupler-2.1.6 → decoupler-2.2.0}/README.md

@@ -26,10 +26,8 @@
 [badge-adown]: https://static.pepy.tech/badge/decoupler
 [badge-stars]: https://img.shields.io/github/stars/scverse/decoupler?style=flat&logo=github&color=yellow
 
-`decoupler` is a python package containing different enrichment statistical
-methods to extract biologically driven scores
-from omics data within a unified framework. This is its faster and memory efficient Python implementation,
-a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
+`decoupler` is a python package containing different enrichment statistical methods to extract biologically driven scores from omics data within a unified framework.
+This is its faster and memory efficient Python implementation, a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
 
 [//]: # (numfocus-fiscal-sponsor-attribution)
 
@@ -52,7 +50,7 @@ in particular, the [API documentation][].
 
 ## Installation
 
-You need to have Python 3.10 or newer installed on your system.
+You need to have Python 3.11 or newer installed on your system.
 If you don't have Python installed, we recommend installing [uv][].
 
 There are several alternative options to install decoupler:
@@ -81,6 +79,20 @@ mamba create -n=dcp conda-forge::decoupler-py
 pip install git+https://github.com/scverse/decoupler.git@main
 ```
 
+## Claude Code Skill
+
+decoupler ships an [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) for [Claude Code](https://claude.com/claude-code) that teaches the agent to use the library correctly. Install it once into your personal skills directory:
+
+```bash
+decoupler-install-skills
+```
+
+This copies the skill to `~/.claude/skills/decoupler/`, making it available in **every** project (re-run with `--force` after upgrading). Once installed, just ask Claude Code to do decoupler tasks ("find the most active TFs in this cell cluster", "score hallmark gene sets with ora", "build a consensus across methods") and the skill is consulted automatically. To avoid copying into your home directory, point Claude Code at the bundled copy instead:
+
+```bash
+export CLAUDE_SKILLS_PATH="$(decoupler-install-skills --print-path)"
+```
+
 ## Release notes
 
 See the [changelog][].

{decoupler-2.1.6 → decoupler-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "decoupler"
-version = "2.1.6"
+version = "2.2.0"
 description = "Python package to perform enrichment analysis from omics data."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -38,6 +38,7 @@ dependencies = [
 urls.Documentation = "https://decoupler.readthedocs.io/"
 urls.Homepage = "https://github.com/scverse/decoupler"
 urls.Source = "https://github.com/scverse/decoupler"
+scripts.decoupler-install-skills = "decoupler._skills.install:main"
 
 [dependency-groups]
 dev = [
@@ -84,11 +85,10 @@ full = [
 [tool.hatch]
 envs.default.installer = "uv"
 envs.default.dependency-groups = [ "dev" ]
-envs.docs.dependency-groups = [ "doc" ]
 envs.docs.scripts.build = "sphinx-build -M html docs docs/_build -W {args}"
-envs.docs.scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
 envs.docs.scripts.clean = "git clean -fdX -- {args:docs}"
-envs.hatch-test.dependency-groups = [ "dev", "test" ]
+envs.docs.scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
+envs.docs.dependency-groups = [ "doc" ]
 envs.hatch-test.matrix = [
   # Test the lowest and highest supported Python versions with normal deps
   { deps = [ "stable" ], python = [ "3.11", "3.14" ] },
@@ -98,8 +98,9 @@ envs.hatch-test.matrix = [
 # If the matrix variable `deps` is set to "pre",
 # set the environment variable `UV_PRERELEASE` to "allow".
 envs.hatch-test.overrides.matrix.deps.env-vars = [
-  { key = "UV_PRERELEASE", value = "allow", if = [ "pre" ] },
+  { value = "allow", key = "UV_PRERELEASE", if = [ "pre" ] },
 ]
+envs.hatch-test.dependency-groups = [ "dev", "test" ]
 
 [tool.ruff]
 line-length = 120
@@ -140,11 +141,11 @@ lint.per-file-ignores."tests/*" = [ "D" ]
 lint.pydocstyle.convention = "numpy"
 
 [tool.pytest]
-strict = true
-testpaths = [ "tests" ]
 addopts = [
   "--import-mode=importlib", # allow using test files with same name
 ]
+strict = true
+testpaths = [ "tests" ]
 
 [tool.coverage]
 run.omit = [

decoupler-2.2.0/src/decoupler/_skills/__init__.py

@@ -0,0 +1,6 @@
+"""Bundled Claude Code Agent Skill and its installer.
+
+This subpackage keeps the decoupler Agent Skill (the ``data/`` directory) and the
+command that installs it (``install.py``) together and out of the main package
+namespace. See ``install.py`` for usage.
+"""

decoupler-2.2.0/src/decoupler/_skills/data/SKILL.md

@@ -0,0 +1,85 @@
+---
+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](references/calling-convention.md)** — 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](references/io-and-outputs.md)** — 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](references/getting-started.md) |
+| how to **call a method**, what data/net formats are accepted, `tmin`/`raw`/`layer` semantics | [references/calling-convention.md](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](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](references/methods.md) |
+| getting **prior knowledge** — TF regulons (CollecTRI, DoRothEA), pathways (PROGENy), gene sets (MSigDB hallmarks), OmniPath, `.gmt`, organism translation | [references/priors.md](references/priors.md) |
+| **preprocessing** — pseudobulk from single cell, expression/sample filtering, layers, spatial kNN | [references/preprocessing.md](references/preprocessing.md) |
+| running **many methods at once** and combining them into a **consensus** | [references/multi-method.md](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](references/ranking-and-plotting.md) |
+| **benchmarking** methods/nets against a perturbation ground truth | [references/benchmarking.md](references/benchmarking.md) |
+| using a **bundled example dataset** (`dc.ds.*`) — and whether its `.X` is raw counts or already normalized | [references/datasets.md](references/datasets.md) |
+
+## 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](references/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](references/ranking-and-plotting.md).

decoupler-2.2.0/src/decoupler/_skills/data/references/benchmarking.md

@@ -0,0 +1,59 @@
+# Benchmarking methods and nets
+
+`dc.bm` evaluates how well a method + net recover a known ground truth — typically a
+perturbation dataset where you know which program was up/down in each sample. Use it
+to **choose a method** or **validate a net**, not for routine scoring.
+
+## `dc.bm.benchmark`
+
+```python
+dc.bm.benchmark(
+    adata,                 # AnnData with a perturbation ground truth in .obs
+    net,                   # a net, or a dict of {name: net} to compare several
+    metrics=None,          # e.g. ["auroc", "auprc"] (None = defaults)
+    groupby=None,          # obs column(s) to stratify the evaluation
+    runby="expr",          # evaluate per-observation ("expr") or per-source
+    sfilt=False,           # filter sources to those with a ground-truth label
+    thr=0.1, emin=5,
+    kws_decouple=None,     # kwargs forwarded to dc.mt.decouple (methods, args, tmin, ...)
+    verbose=False,
+)
+```
+
+- Internally runs `dc.mt.decouple`, so pass method selection and per-method args via
+  `kws_decouple` (e.g. `kws_decouple={"methods": ["ulm", "mlm"], "tmin": 3}`).
+- Pass a **dict of nets** to benchmark several priors head to head.
+- The ground truth (which source is perturbed, and its sign) must be encoded in
+  `adata.obs` — see the decoupler benchmarking tutorial for the expected columns.
+
+## Metrics and plots
+
+- `dc.bm.metric` — the scoring functions: `auc`, `fscore`, `qrank`, `hmean`,
+  `dict_metric`.
+- `dc.bm.pl` — plots of benchmark results: `auc`, `bar`, `fscore`, `qrank`, `summary`.
+
+```python
+res = dc.bm.benchmark(adata, {"collectri": net_a, "dorothea": net_b},
+                      kws_decouple={"methods": ["ulm", "mlm"]})
+dc.bm.pl.summary(res)   # compare methods × nets
+```
+
+## When to use
+
+- Deciding **which method** to trust for your data/organism.
+- Comparing **candidate nets** (e.g. CollecTRI vs DoRothEA levels).
+- Sanity-checking a **custom net** against a perturbation benchmark
+  (`dc.ds.knocktf` and similar provide ground-truth datasets).
+
+## Footguns
+
+- Benchmarking is only meaningful with a **real ground truth** — a toy net won't tell
+  you anything.
+- It re-runs scoring internally; keep `kws_decouple` consistent with how you intend to
+  score for real, or the comparison won't transfer.
+
+## Related references
+
+[multi-method.md](multi-method.md) (`decouple`, which `benchmark` wraps),
+[methods.md](methods.md) (candidate methods),
+[priors.md](priors.md) (candidate nets).

decoupler-2.2.0/src/decoupler/_skills/data/references/calling-convention.md

@@ -0,0 +1,91 @@
+# The unified method call
+
+Every enrichment method in `dc.mt` is a callable object with the **same signature**.
+Learn it once and it applies to `ulm`, `mlm`, `ora`, `gsea`, `gsva`, `aucell`,
+`viper`, `zscore`, `waggr`, `mdt`, `udt` (and `dc.mt.decouple`).
+
+```python
+import decoupler as dc
+
+adata, net = dc.ds.toy()          # AnnData (obs × var) + long-format net
+dc.mt.ulm(adata, net, tmin=3)     # writes adata.obsm["score_ulm"], ["padj_ulm"]
+```
+
+## Shared signature
+
+```python
+dc.mt.<method>(
+    data,              # AnnData | pandas.DataFrame | [matrix, obs_names, var_names]
+    net,               # long-format DataFrame: source, target, [weight]
+    tmin=5,            # drop sources with < tmin targets present in the data
+    raw=False,         # use adata.raw instead of adata.X
+    layer=None,        # use adata.layers[layer] instead of adata.X (passed via kwargs)
+    empty=True,        # drop all-zero observations/features before scoring
+    bsize=250_000,     # batch size (rows) for sparse / backed matrices
+    verbose=False,
+    **kwargs,          # method-specific args — see references/methods.md
+)
+```
+
+`layer=` is accepted even though it is not in the explicit signature — it is forwarded
+through `**kwargs` to the runner. Use `layer=` **or** `raw=`, not both.
+
+## Accepted input types (`data`)
+
+| Form | What it is | Returns |
+|---|---|---|
+| `AnnData` | scored on `.X` (or `.raw`/`layer`) | **`None`** — results written to `.obsm` in place |
+| `pandas.DataFrame` | observations (rows) × features (cols) | `(es, pv)` tuple of DataFrames |
+| `list` `[matrix, obs_names, var_names]` | numpy/sparse matrix + name arrays | `(es, pv)` tuple of DataFrames |
+
+See [io-and-outputs.md](io-and-outputs.md) for the return details.
+
+### Footgun — the matrix form must be a `list`, not a `tuple`
+
+```python
+# WRONG — a tuple raises "mat must be a list of [matrix, samples, features]"
+es, pv = dc.mt.ulm((X, obs, var), net)
+
+# RIGHT — wrap it in a list
+es, pv = dc.mt.ulm([X, obs, var], net)
+```
+
+## The three footguns that silently give wrong results
+
+1. **Input must be normalized, not raw counts.** decoupler expects
+   log-normalized expression — the same matrix you would use for differential
+   expression. **When normalizing, use `sc.pp.normalize_total(adata, target_sum=1e4)`**
+   followed by `sc.pp.log1p(adata)`. Passing raw counts runs without error but produces
+   meaningless scores. If your normalized data is in a layer, pass
+   `layer="lognorm"`; if in `.raw`, pass `raw=True`. **Check before normalizing:** if
+   `.X` is integer-valued with a large max it is raw counts; if it is small floats
+   (often with `adata.uns["log1p"]`) it is already normalized — do not normalize twice.
+   The bundled datasets differ; see [datasets.md](datasets.md) (e.g. `pbmc3k` is already
+   log-normalized, `covid5k` is raw counts).
+
+2. **`net` must be long-format** with columns `source`, `target`, and (for weighted
+   methods) `weight` — one row per (program, feature) edge. A wide/matrix net or wrong
+   column names will fail or misbehave. See [priors.md](priors.md).
+
+3. **`tmin` silently prunes.** Sources with fewer than `tmin` (default 5) targets
+   present in `data` are dropped *before* scoring — they simply won't appear in the
+   output. On small or toy nets this can drop everything; the examples use `tmin=3`.
+   Run with `verbose=True` to see `<method> - X sources with < tmin targets` and how
+   many survived.
+
+## Listing and introspecting methods
+
+```python
+dc.mt.show()          # DataFrame: name, desc, stype, weight, test, limits, reference
+```
+
+- `weight` — whether the method uses signed edge weights (`True` for ulm/mlm/viper/…).
+- `test` — whether it produces p-values (`padj`). `False` for aucell/gsva/mdt/udt.
+- `stype` / `limits` — value type and output range (e.g. aucell `(0, 1)`).
+
+## Related references
+
+[io-and-outputs.md](io-and-outputs.md) (return types, reading `.obsm` back),
+[methods.md](methods.md) (per-method kwargs and how to choose one),
+[priors.md](priors.md) (building/fetching `net`),
+[preprocessing.md](preprocessing.md) (getting a normalized matrix / layers).

decoupler-2.2.0/src/decoupler/_skills/data/references/datasets.md

@@ -0,0 +1,88 @@
+# Bundled example datasets (`dc.ds`)
+
+decoupler ships loaders for a toy dataset and several real ones. **They are not all in
+the same state** — some `.X` are raw counts, some are already log-normalized, one is a
+log2FC contrast statistic. Since methods expect **normalized** input (see
+[calling-convention.md](calling-convention.md)), you must know which is which or you
+will either skip a needed normalization or re-normalize already-normalized data.
+
+## Rule: inspect `.X` before assuming counts
+
+```python
+import numpy as np, scipy.sparse as sps
+X = adata.X.toarray() if sps.issparse(adata.X) else np.asarray(adata.X)
+X.max(), np.allclose(X[:50], np.round(X[:50])), "log1p" in adata.uns
+```
+
+- **Integer-valued and large max (hundreds–millions)** → raw counts → normalize first.
+- **Float, small max (roughly ≤ tens), often `adata.uns["log1p"]` present** → already
+  log-normalized → **score directly, do not normalize again**.
+- **Signed values (negatives)** → a contrast statistic (e.g. log2FC), not expression →
+  score directly.
+
+## The datasets
+
+| Loader | What it is | `.X` state | Before scoring | Organism |
+|---|---|---|---|---|
+| `dc.ds.toy()` | synthetic AnnData **+ matching net** | synthetic continuous | score directly (`tmin=3`) | — |
+| `dc.ds.toy_bench()` | toy + benchmark ground truth | synthetic continuous | feed to `dc.bm` | — |
+| `dc.ds.pbmc3k()` | 10x PBMCs (~2.6k cells) | **log-normalized** (max ~6) | **score directly** | human |
+| `dc.ds.erygast1k()` | mouse erythroid gastrulation (~800 cells) | **log-normalized** (`uns['log1p']`) | score directly | **mouse** |
+| `dc.ds.covid5k()` | COVID-19 PBMCs (~5k cells) | **raw counts** (max ~1e4) | **normalize + log1p** | human |
+| `dc.ds.hsctgfb()` | bulk RNA-seq, 6 HSC samples | **raw counts** | **filter + normalize** (bulk) | human |
+| `dc.ds.msvisium()` | Visium MS brain slide (spatial) | **raw counts** | **normalize** | human |
+| `dc.ds.knocktf()` | KnockTF TF-perturbation contrasts | **log2FC** (−20…20) | score directly (benchmark) | human |
+
+### Ready to score directly (do NOT normalize)
+
+```python
+adata = dc.ds.pbmc3k()            # already log-normalized
+net = dc.op.collectri(organism="human")
+dc.mt.ulm(adata, net)             # -> adata.obsm["score_ulm"], ["padj_ulm"]
+```
+
+- `erygast1k` is the same, but **mouse** — fetch a mouse net (`organism="mouse"`) or
+  translate a human one (`dc.op.translate`, see [priors.md](priors.md)). Its `obs` has
+  `celltype`, `stage`.
+- `pbmc3k.obs` has `celltype` and `leiden`; `obsm` has PCA/UMAP/tSNE already.
+
+### Raw counts → normalize first
+
+```python
+import scanpy as sc
+adata = dc.ds.covid5k()                    # raw integer counts
+sc.pp.normalize_total(adata, target_sum=1e4)
+sc.pp.log1p(adata)
+dc.mt.ulm(adata, dc.op.collectri())
+```
+
+- `covid5k.obs`: `individual`, `sex`, `disease`, `celltype`.
+- `hsctgfb` is **bulk** (6 samples, `obs`: `condition`, `sample_id`) — filter lowly
+  expressed genes with `dc.pp.filter_by_expr` then normalize; a natural fit for a
+  bulk/DE + activity workflow ([preprocessing.md](preprocessing.md)).
+- `msvisium` is **spatial** — normalize, then optionally build a neighbor graph with
+  `dc.pp.knn(adata, key="spatial")`. It carries `obsm["spatial"]`, `uns["spatial"]`
+  (H&E images), and `obs["niches"]`. To plot activity on the H&E, use `dc.pp.get_obsm` +
+  `sc.pl.spatial` (see [ranking-and-plotting.md](ranking-and-plotting.md)).
+
+### Benchmark inputs (not for routine scoring)
+
+- `dc.ds.knocktf()` — `.X` is already log2FCs; `obs["source"]` is the perturbed TF and
+  `obs["logFC"]` its effect. It is the ground truth for `dc.bm.benchmark`, not a matrix
+  you normalize. `thr_fc=-1` (default) keeps clearly down-regulated perturbations.
+- `dc.ds.toy_bench()` — toy data with ground truth in `obs["source"]` / `class` /
+  `type_p` for exercising the benchmark pipeline ([benchmarking.md](benchmarking.md)).
+
+## Gene identifiers
+
+Real datasets use gene **symbols** in `var_names` (matching the OmniPath priors). If you
+bring data with Ensembl IDs, convert with `dc.ds.ensmbl_to_symbol(...)` so `net`
+`target`s line up — mismatched namespaces get silently pruned by `tmin`
+(see the identifier footgun in [priors.md](priors.md)).
+
+## Related references
+
+[calling-convention.md](calling-convention.md) (normalized-input requirement),
+[preprocessing.md](preprocessing.md) (normalize / filter / pseudobulk / spatial kNN),
+[priors.md](priors.md) (matching organism and gene identifiers),
+[benchmarking.md](benchmarking.md) (`knocktf`, `toy_bench`).

decoupler-2.2.0/src/decoupler/_skills/data/references/getting-started.md

@@ -0,0 +1,82 @@
+# Getting started (end-to-end)
+
+A complete decoupler run has four steps: **get a normalized data matrix**, **get a
+prior net**, **score**, then **inspect/rank/plot**. Below are the two most common
+end-to-end shapes.
+
+## Minimal, self-contained (toy data)
+
+```python
+import decoupler as dc
+
+# 1. Data (obs × var, normalized) + 2. a prior net (source/target/weight)
+adata, net = dc.ds.toy()
+
+# 3. Score — results written into adata.obsm in place
+dc.mt.ulm(adata, net, tmin=3)
+
+# 4. Inspect: scores + adjusted p-values, both obs × sources
+adata.obsm["score_ulm"]
+adata.obsm["padj_ulm"]
+```
+
+`dc.ds.toy()` returns a small AnnData and a matching weighted net — use it for any
+quick check or when reproducing behavior.
+
+## Single-cell TF activity (realistic shape)
+
+```python
+import scanpy as sc
+import decoupler as dc
+
+# adata: raw counts in a single-cell AnnData
+sc.pp.normalize_total(adata, target_sum=1e4)   # when normalizing, use target_sum=1e4
+sc.pp.log1p(adata)                      # decoupler needs normalized input, not counts
+# NOTE: only normalize raw counts. Data that is already log-normalized (e.g.
+# dc.ds.pbmc3k()) must NOT be normalized again — see references/datasets.md.
+
+net = dc.op.collectri(organism="human")  # signed TF regulons
+
+dc.mt.ulm(adata, net)                    # -> adata.obsm["score_ulm"], ["padj_ulm"]
+
+# Turn scores into an AnnData for downstream scanpy/plotting
+acts = dc.pp.get_obsm(adata, key="score_ulm")   # obs × TFs
+
+# Which TFs are most active per cell type?
+df = dc.tl.rankby_group(acts, groupby="cell_type")
+# barplot/dotplot take DataFrames (not `acts`) — see ranking-and-plotting.md
+```
+
+## Pathway activity or gene-set enrichment
+
+Swap the net (and, for unweighted gene sets, the method):
+
+```python
+# Pathways (weighted) — ulm is fine
+prog = dc.op.progeny(organism="human", top=500)
+dc.mt.ulm(adata, prog)                   # adata.obsm["score_ulm"] = pathway activities
+
+# Hallmark gene sets (unweighted) — use a gene-set method
+hall = dc.op.hallmark(organism="human")
+dc.mt.ora(adata, hall)                   # adata.obsm["score_ora"], ["padj_ora"]
+```
+
+## Bulk / pseudobulk
+
+For bulk RNA-seq or pseudobulk from single cell, aggregate and filter first (see
+[preprocessing.md](preprocessing.md)), then score exactly the same way:
+
+```python
+pdata = dc.pp.pseudobulk(adata, sample_col="sample", groups_col="cell_type")
+dc.pp.filter_by_expr(pdata)              # drop lowly-expressed genes
+# ... normalize pdata (e.g. CPM + log1p) ...
+dc.mt.ulm(pdata, net)
+```
+
+## Where to go next
+
+- Method choice and kwargs → [methods.md](methods.md)
+- Getting/formatting the net → [priors.md](priors.md)
+- Return types and reading scores back → [io-and-outputs.md](io-and-outputs.md)
+- Running many methods + consensus → [multi-method.md](multi-method.md)
+- Ranking + plotting → [ranking-and-plotting.md](ranking-and-plotting.md)