@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/pathogen-variant-surveillance/scripts/reporting_lag.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""Measure how long sequences take to appear, and how far back to trust the data.
+
+The single most common way to get variant surveillance wrong is to compute
+prevalence over the last few weeks. Those weeks are not a sample of what was
+circulating -- they are a sample of whichever laboratories report fastest, and
+they keep growing for months. This script measures that filling-in curve from
+the instance itself and turns it into a cutoff date.
+
+    python3 reporting_lag.py --instance sars-cov-2 --where country=USA
+    python3 reporting_lag.py --instance h5n1 --target 0.8
+
+Method: take monthly collection cohorts old enough to have settled, group each
+by submission date, and compute what fraction of the cohort's present-day total
+had arrived by each lag. Averaging across cohorts gives the curve.
+
+The curve is a **lower bound** on the true lag: a cohort's denominator is what
+has arrived so far, and even old cohorts still gain sequences. Treat the
+recommended cutoff as the least conservative one defensible.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date, timedelta
+
+from lapis_client import (
+    LapisError,
+    aggregated,
+    data_version,
+    describe_instance,
+    emit,
+    pick_date_field,
+    range_keys,
+    resolve_base_url,
+)
+
+COLUMNS = ("lag_days", "mean_complete", "min_complete", "max_complete", "cohorts")
+OFFSETS = (7, 14, 21, 30, 45, 60, 90, 120, 180)
+
+
+def month_window(anchor: date, months_back: int) -> tuple[date, date]:
+    """First and last day of the month ``months_back`` before ``anchor``."""
+    total = anchor.year * 12 + (anchor.month - 1) - months_back
+    year, month = divmod(total, 12)
+    first = date(year, month + 1, 1)
+    nxt = date(year + 1, 1, 1) if month == 11 else date(year, month + 2, 1)
+    return first, nxt - timedelta(days=1)
+
+
+def cohort_curve(
+    base_url: str,
+    filters: dict,
+    submission_field: str,
+    cohort_end: date,
+) -> tuple[dict[int, float], int, int] | None:
+    """Cumulative completeness by lag for one collection cohort.
+
+    Returns ``(curve, dated, undated)``. Sequences with no parseable submission
+    date are excluded from the denominator rather than counted as never having
+    arrived — the question is "of the ones we can date, how fast did they come"
+    — but they are returned so the caller can say how many were set aside.
+    """
+    rows = aggregated(base_url, filters, [submission_field])
+    lags: list[tuple[int, int]] = []
+    dated = 0
+    undated = 0
+    for row in rows:
+        value = str(row.get(submission_field) or "")
+        n = int(row.get("count") or 0)
+        try:
+            submitted = date.fromisoformat(value[:10])
+        except ValueError:
+            undated += n
+            continue
+        lags.append((max(0, (submitted - cohort_end).days), n))
+        dated += n
+    if dated == 0:
+        return None
+    lags.sort()
+    curve: dict[int, float] = {}
+    for offset in OFFSETS:
+        arrived = sum(n for lag, n in lags if lag <= offset)
+        curve[offset] = arrived / dated
+    return curve, dated, undated
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Measure sequence reporting lag and recommend a trust cutoff.",
+    )
+    parser.add_argument("--instance", default="sars-cov-2", help="registry name (default: sars-cov-2)")
+    parser.add_argument("--base-url", help="any other LAPIS deployment")
+    parser.add_argument("--date-field", help="override the auto-detected collection-date column")
+    parser.add_argument("--submission-field", help="override the auto-detected submission-date column")
+    parser.add_argument("--where", action="append", default=[], metavar="KEY=VALUE",
+                        help="extra filter, repeatable (lag differs sharply by country)")
+    parser.add_argument("--cohorts", type=int, default=6, help="monthly cohorts to average (default: 6)")
+    parser.add_argument("--skip-months", type=int, default=3,
+                        help="most recent months to exclude as unsettled (default: 3)")
+    parser.add_argument("--target", type=float, default=0.9,
+                        help="completeness the cutoff should reach (default: 0.9)")
+    parser.add_argument("--until", help="anchor date, YYYY-MM-DD (default: today)")
+    parser.add_argument("--format", choices=("table", "tsv", "json"), default="table")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        base_url = resolve_base_url(args.instance, args.base_url)
+        schema = describe_instance(base_url)
+        collection_field = pick_date_field(schema, "collection", args.date_field)
+        submission_field = pick_date_field(schema, "submission", args.submission_field)
+        if collection_field == submission_field:
+            raise LapisError(
+                f"collection and submission both resolved to {collection_field!r}; "
+                "the lag would be identically zero. Set --submission-field explicitly."
+            )
+        where: dict[str, str] = {}
+        for pair in args.where:
+            key, sep, value = pair.partition("=")
+            if not sep or key.split(".")[0] not in schema["types"]:
+                raise LapisError(f"bad --where {pair!r}")
+            where[key] = value
+    except LapisError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    anchor = date.fromisoformat(args.until) if args.until else date.today()
+    from_key, to_key = range_keys(collection_field)
+
+    curves: list[dict[int, float]] = []
+    sizes: list[int] = []
+    undated_total = 0
+    try:
+        for back in range(args.skip_months, args.skip_months + max(1, args.cohorts)):
+            start, end = month_window(anchor, back)
+            result = cohort_curve(
+                base_url,
+                {from_key: start.isoformat(), to_key: end.isoformat(), **where},
+                submission_field,
+                end,
+            )
+            if result:
+                curve, dated, undated = result
+                curves.append(curve)
+                sizes.append(dated)
+                undated_total += undated
+    except LapisError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if not curves:
+        print(
+            "error: no cohort in the requested range holds any sequence. "
+            "Widen --where, raise --cohorts, or lower --skip-months.",
+            file=sys.stderr,
+        )
+        return 1
+
+    rows = []
+    for offset in OFFSETS:
+        values = [c[offset] for c in curves]
+        rows.append(
+            {
+                "lag_days": offset,
+                "mean_complete": f"{sum(values) / len(values):.3f}",
+                "min_complete": f"{min(values):.3f}",
+                "max_complete": f"{max(values):.3f}",
+                "cohorts": len(values),
+            }
+        )
+
+    reached = [o for o in OFFSETS if sum(c[o] for c in curves) / len(curves) >= args.target]
+    print(emit(rows, COLUMNS, args.format))
+
+    sys.stdout.flush()
+    if args.format != "json":
+        print(
+            f"\n# {schema['name']} via {base_url} | data version {data_version(base_url)}"
+            f"\n# collection dates from {collection_field}, submission from {submission_field}"
+            f"\n# {len(curves)} monthly cohorts, {sum(sizes)} datable sequences"
+            + (f" ({undated_total} excluded for having no submission date)"
+               if undated_total else "")
+            + (f" | filters {where}" if where else ""),
+            file=sys.stderr,
+        )
+        if reached:
+            cutoff = anchor - timedelta(days=reached[0])
+            print(
+                f"# {args.target:.0%} of a cohort has arrived by {reached[0]} days.\n"
+                f"# Trust collection dates up to {cutoff.isoformat()}; treat anything "
+                f"later as provisional.",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"# no lag up to {OFFSETS[-1]} days reaches {args.target:.0%} completeness "
+                f"(best {max(sum(c[o] for c in curves) / len(curves) for o in OFFSETS):.0%}). "
+                f"Recent weeks cannot support a prevalence estimate here.",
+                file=sys.stderr,
+            )
+        print(
+            "# This curve is a lower bound: cohort denominators are still growing.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pathogen-variant-surveillance/scripts/resolve_lineage.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""Resolve a lineage name against the live nomenclature before trusting it.
+
+Pango names are not stable identifiers. They are minted continuously, aliased
+through a key that must be fetched to be read, and **withdrawn or redesignated
+after the fact** -- so a remembered lineage fact is not merely stale, it can be
+actively wrong. This script answers, for each name: does it still exist, what
+does it expand to, what is it descended from, and how many sequences carry it.
+
+    python3 resolve_lineage.py XFG.23.1.3 PQ.17 PC.2
+    python3 resolve_lineage.py XFG --descendants
+    python3 resolve_lineage.py 2.3.4.4b --instance h5n1
+
+Exit code is 1 when any name is withdrawn or unknown, so it works as a gate on
+a manuscript's lineage list.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+from lapis_client import (
+    LapisError,
+    children_map,
+    count,
+    data_version,
+    descendants,
+    describe_instance,
+    emit,
+    fetch_lineage_notes,
+    fetch_pango_aliases,
+    lineage_definition,
+    lineage_field_candidates,
+    parent_chain,
+    pango_provenance,
+    pick_lineage_field,
+    recombinant_parents,
+    resolve_base_url,
+    unalias_full,
+)
+
+COLUMNS = (
+    "query",
+    "status",
+    "unaliased",
+    "parent",
+    "recombinant_of",
+    "descendants",
+    "sequences",
+    "detail",
+)
+PANGO_FIELDS = {"pangoLineage", "nextcladePangoLineage"}
+REDESIGNATED = re.compile(r"[Rr]edesignated as ([A-Za-z][A-Za-z0-9.]*)")
+
+
+def normalise(name: str) -> str:
+    """Uppercase the alphabetic head so ``xfg.1`` matches ``XFG.1``."""
+    head, sep, tail = name.strip().partition(".")
+    return f"{head.upper()}{sep}{tail}"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Check lineage names against the live nomenclature.",
+    )
+    parser.add_argument("names", nargs="+", help="lineage or clade names to resolve")
+    parser.add_argument("--instance", default="sars-cov-2", help="registry name (default: sars-cov-2)")
+    parser.add_argument("--base-url", help="any other LAPIS deployment")
+    parser.add_argument("--lineage-field", help="override the auto-detected lineage column")
+    parser.add_argument("--descendants", action="store_true",
+                        help="list every descendant lineage instead of counting them")
+    parser.add_argument("--no-counts", action="store_true",
+                        help="skip the sequence counts (one fewer request per name)")
+    parser.add_argument("--format", choices=("table", "tsv", "json"), default="table")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        base_url = resolve_base_url(args.instance, args.base_url)
+        schema = describe_instance(base_url)
+        lineage_field, has_index = pick_lineage_field(schema, args.lineage_field)
+        # Fetched here, not inside the provenance f-string: a network failure at
+        # print time would raise after the table had already been written.
+        version = data_version(base_url)
+    except LapisError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    definition: dict = {}
+    if has_index:
+        try:
+            definition = lineage_definition(base_url, lineage_field)
+        except LapisError as exc:
+            print(f"warning: no lineage definition for {lineage_field}: {exc}", file=sys.stderr)
+
+    aliases: dict = {}
+    notes: dict = {}
+    if lineage_field in PANGO_FIELDS:
+        try:
+            aliases = fetch_pango_aliases()
+            notes = fetch_lineage_notes()
+        except LapisError as exc:
+            print(f"warning: pango-designation unreachable: {exc}", file=sys.stderr)
+
+    # Inverted once: the SARS-CoV-2 definition holds ~5,500 entries, so
+    # rebuilding it per name makes a list of lineages quadratic.
+    children = children_map(definition)
+
+    rows: list[dict] = []
+    failures = 0
+    for raw in args.names:
+        name = normalise(raw)
+        note = notes.get(name, {})
+        in_definition = name in definition
+
+        if note.get("status") == "withdrawn":
+            status = "withdrawn"
+        elif note.get("status") == "designated" or in_definition:
+            status = "current"
+        elif notes or definition:
+            status = "unknown"
+        else:
+            status = "unverified"
+        if status in {"withdrawn", "unknown"}:
+            failures += 1
+
+        detail = note.get("note", "")
+        successor = REDESIGNATED.search(detail)
+        if successor:
+            detail = f"now {successor.group(1)}; {detail}"
+        elif status == "unknown":
+            detail = "no such name in the live nomenclature for this instance"
+
+        chain = parent_chain(name, definition) if definition else []
+        kids = descendants(name, definition, children) if definition else []
+
+        sequences: object = ""
+        if not args.no_counts:
+            try:
+                query = f"{name}*" if has_index else name
+                sequences = count(base_url, {lineage_field: query})
+            except LapisError as exc:
+                # An indexed column rejects an unknown lineage outright rather
+                # than answering 0 -- which is the one place a typo is caught
+                # for you. An unindexed column would have returned 0 instead.
+                sequences = "n/a" if "not a valid lineage" in str(exc) else "error"
+
+        rows.append(
+            {
+                "query": raw,
+                "status": status,
+                "unaliased": unalias_full(name, aliases) if aliases else "",
+                "parent": chain[0] if chain else "",
+                "recombinant_of": "+".join(recombinant_parents(name, aliases)) if aliases else "",
+                "descendants": ", ".join(kids) if args.descendants else len(kids),
+                "sequences": sequences,
+                "detail": detail,
+            }
+        )
+
+    print(emit(rows, COLUMNS, args.format))
+    sys.stdout.flush()
+
+    if args.format != "json":
+        print(
+            f"\n# {schema['name']} via {base_url} | data version {version}"
+            f"\n# lineage column {lineage_field}"
+            f"{' with a lineage index' if has_index else ' with no lineage index'}"
+            + (
+                f"\n# nomenclature from pango-designation ({len(notes)} names, "
+                f"{sum(1 for v in notes.values() if v['status'] == 'withdrawn')} withdrawn)"
+                f"\n# source blobs {pango_provenance()}"
+                if notes
+                else ""
+            )
+            + ("\n# 'sequences' counts the lineage and its descendants" if has_index else ""),
+            file=sys.stderr,
+        )
+        others = [n for n, _ in lineage_field_candidates(schema) if n != lineage_field]
+        if others:
+            print(
+                f"# other lineage-like columns here: {', '.join(others)} "
+                f"(select one with --lineage-field)",
+                file=sys.stderr,
+            )
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pathway-enrichment/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: pathway-enrichment
+description: Run pathway and gene-set enrichment analysis on gene lists or ranked gene data, then interpret the results. Use whenever the user has a set of genes (differentially expressed genes from PyDESeq2/Scanpy, CRISPR-screen hits, cluster marker genes, proteomics hits) and wants to know which biological pathways, GO terms, or gene sets are over-represented or enriched. Covers over-representation analysis (ORA / Enrichr / Fisher / hypergeometric), ranked Gene Set Enrichment Analysis (GSEA / preranked), single-sample scoring (ssGSEA/GSVA), and functional profiling via gseapy, g:Profiler, Enrichr libraries, MSigDB, GO, KEGG, Reactome, and WikiPathways — plus gene-ID mapping, choosing the right background universe, multiple-testing correction, redundancy reduction, dotplots/enrichment maps, and publication-ready tables. Use this for "pathway analysis", "enrichment analysis", "GO enrichment", "KEGG/Reactome pathways", "GSEA", "over-representation", "functional annotation", or "what pathways are my genes in".
+license: MIT
+metadata:
+  version: "1.0"
+  skill-author: K-Dense Inc.
+---
+
+# Pathway Enrichment
+
+## Overview
+
+Enrichment analysis answers "what biology is over-represented in my genes?" It is the standard last step after differential expression, a screen, or clustering. There are two core methods, and choosing correctly is the single most important decision:
+
+- **ORA (over-representation analysis)** — take a *thresholded* gene list (e.g., padj < 0.05) and test which gene sets it overlaps more than chance, using Fisher's exact / hypergeometric tests. Tools: Enrichr, g:Profiler.
+- **GSEA (gene set enrichment analysis)** — take the *whole ranked list* of genes (no threshold) and test whether each gene set is concentrated toward the top or bottom. Preranked GSEA uses a per-gene score (e.g., the DESeq2 `stat`). Better when effects are broad and subtle.
+
+This skill orchestrates these analyses, the gene-set databases behind them, and the interpretation pitfalls that make results wrong or unpublishable.
+
+## When to Use This Skill
+
+Use this skill when the user wants to:
+- Find enriched GO terms / KEGG / Reactome / WikiPathways / MSigDB Hallmark sets in a gene list.
+- Run GSEA / preranked GSEA on DESeq2, edgeR, limma, or Scanpy `rank_genes_groups` output.
+- Score pathway activity per sample/cell (ssGSEA, GSVA).
+- Interpret, deduplicate, and visualize enrichment results, or build a publication table/figure.
+- Decide between ORA and GSEA, pick gene-set libraries, choose a background, or fix gene-ID problems.
+
+For quick one-off Enrichr lookups the `gget` skill (`gget enrichr`) is lighter weight; for raw pathway/interaction APIs (Reactome, KEGG, STRING) see the `database-lookup` skill. Use **this** skill for full, defensible enrichment workflows.
+
+## Choosing the Right Method
+
+| Situation | Method | Tool / entry point |
+|-----------|--------|--------------------|
+| You have a discrete hit list (DE genes, screen hits, cluster markers) | **ORA** | `gp.enrichr(...)` or g:Profiler |
+| You have a full ranked list (every tested gene + a score) | **Preranked GSEA** | `gp.prerank(...)` |
+| You have an expression matrix + class labels | **GSEA** | `gp.gsea(...)` |
+| You want a pathway score per sample/cell | **ssGSEA / GSVA** | `gp.ssgsea(...)`, `gp.gsva(...)` |
+| You need a custom background or 500+ organisms | **ORA with custom domain** | g:Profiler (`domain_scope='custom'`) |
+| You want TF / signaling *activity* (PROGENy, DoRothEA) | activity inference | see `references/databases-and-gene-sets.md` (decoupler) |
+
+When in doubt: a thresholded list → ORA; a ranked table with scores → GSEA. Never threshold a list and then feed it to GSEA — that discards the ranking GSEA depends on.
+
+## Setup
+
+```bash
+uv pip install gseapy gprofiler-official
+# gseapy pulls pandas, numpy, scipy, matplotlib. Network access is needed for
+# Enrichr, g:Profiler, and MSigDB downloads. For fully offline ORA, use a local
+# GMT file with gp.enrich() (see references/gseapy.md).
+```
+
+Verify and list available gene-set libraries (names change over time — never hardcode blindly):
+
+```python
+import gseapy as gp
+names = gp.get_library_name(organism="human")   # 200+ Enrichr libraries
+print([n for n in names if "Reactome" in n or "KEGG" in n or "Hallmark" in n])
+```
+
+## Quick Start
+
+### ORA on a hit list (gseapy + Enrichr)
+
+```python
+import gseapy as gp
+
+# Enrichr libraries expect HGNC gene SYMBOLS (human: UPPERCASE). Map IDs first if needed.
+genes = [g.strip() for g in open("deg_symbols.txt") if g.strip()]
+
+enr = gp.enrichr(
+    gene_list=genes,
+    gene_sets=["MSigDB_Hallmark_2020", "GO_Biological_Process_2023",
+               "KEGG_2021_Human", "Reactome_2022"],
+    organism="human",
+    outdir=None,            # in-memory; set a path to also write tables/plots
+)
+res = enr.results
+sig = res[res["Adjusted P-value"] < 0.05].sort_values("Adjusted P-value")
+print(sig[["Gene_set", "Term", "Overlap", "Adjusted P-value", "Combined Score", "Genes"]].head(20))
+```
+
+### Preranked GSEA from DESeq2 results
+
+```python
+import gseapy as gp
+import pandas as pd
+
+res = pd.read_csv("deseq2_results.csv", index_col=0)   # index = gene symbols
+# Rank by the test statistic (sign = direction, magnitude = evidence). This is
+# more stable than ranking by log2FoldChange, which is noisy for low-count genes.
+rnk = res["stat"].dropna().sort_values(ascending=False)
+rnk.index = rnk.index.str.upper()
+rnk = rnk[~rnk.index.duplicated(keep="first")]
+
+pre = gp.prerank(
+    rnk=rnk,
+    gene_sets=["MSigDB_Hallmark_2020", "GO_Biological_Process_2023"],
+    min_size=15, max_size=500,        # drop tiny/huge sets (noisy or generic)
+    permutation_num=1000, seed=123,   # seed = reproducible p-values
+    threads=4, outdir=None,
+)
+out = pre.res2d.sort_values("FDR q-val")
+print(out[["Term", "ES", "NES", "NOM p-val", "FDR q-val", "Lead_genes"]].head(20))
+```
+
+If you have no `stat` column, build the rank from `sign(log2FoldChange) * -log10(pvalue)`.
+
+## Core Workflow
+
+For a defensible analysis, work through these steps. The middle steps (ID type, background) are where results most often silently go wrong.
+
+### Step 1 — Pin down inputs and pick the method
+Confirm: which genes, what organism, is there a per-gene score (→ GSEA) or just a list (→ ORA), and what comparison they represent (direction matters for interpretation).
+
+### Step 2 — Get gene IDs into the right namespace
+Enrichr/MSigDB libraries are keyed by **gene symbols** (human UPPERCASE, mouse Title-case). If you have Ensembl/Entrez IDs, convert first. See `references/databases-and-gene-sets.md` for `gp.Biomart`, g:Profiler `g:Convert`, and `mygene`. A silent ID mismatch is the #1 cause of "nothing is significant".
+
+### Step 3 — Choose gene-set libraries to match the question
+Hallmark (broad themes) → GO:BP (mechanism) → KEGG/Reactome/WikiPathways (curated pathways) → C7 (immune), etc. Don't run 50 libraries; pick 2–4 that fit the biology. Catalog and selection guidance: `references/databases-and-gene-sets.md`.
+
+### Step 4 — Set the background universe (ORA only)
+The background must be the genes that *could* have been detected in your assay (e.g., all expressed/tested genes), not the whole genome. The wrong background inflates significance. Enrichr uses a fixed background; when background matters, use g:Profiler with `domain_scope='custom'` + your `background`, or `gp.enrich()` with an explicit background. Rationale in `references/interpretation.md`.
+
+### Step 5 — Run the analysis
+Use the Quick Start patterns or the bundled `scripts/run_enrichment.py`. For GSEA always set a `seed` and report `permutation_num`.
+
+### Step 6 — Filter on adjusted p-values
+Use `Adjusted P-value` (ORA, Benjamini–Hochberg) or `FDR q-val` (GSEA), not raw p-values. Typical cutoff 0.05; also check the overlap/gene count so a "hit" isn't 1 gene out of a 2000-gene set.
+
+### Step 7 — Visualize
+Dotplots, bar plots, enrichment maps, and GSEA running-score plots are built into gseapy (`gp.dotplot`, `gp.barplot`, `gp.enrichment_map`, `gp.gseaplot`). See `references/gseapy.md`.
+
+### Step 8 — Reduce redundancy and interpret
+GO especially returns many near-duplicate terms. Collapse with an enrichment map (term–term similarity), leading-edge overlap, or parent terms, and report representative terms. Interpretation framework and a publication-table format are in `references/interpretation.md`.
+
+## Helper Script
+
+`scripts/run_enrichment.py` runs ORA or GSEA end-to-end and writes a results table plus a dotplot, handling the boilerplate (symbol cleanup, dedup, NA removal, rank construction from a DESeq2 table, per-library FDR filtering).
+
+```bash
+# ORA from a hit list (one gene symbol per line)
+python scripts/run_enrichment.py ora \
+  --genes deg_symbols.txt \
+  --libraries MSigDB_Hallmark_2020 GO_Biological_Process_2023 KEGG_2021_Human \
+  --organism human --outdir results/
+
+# Preranked GSEA from a DESeq2 results CSV (auto-builds the rank from `stat`)
+python scripts/run_enrichment.py gsea \
+  --deseq2 deseq2_results.csv \
+  --libraries MSigDB_Hallmark_2020 GO_Biological_Process_2023 \
+  --organism human --outdir results/ --seed 123
+
+# Preranked GSEA from an explicit 2-column rank file (gene,score)
+python scripts/run_enrichment.py gsea --rnk ranked_genes.csv --outdir results/
+```
+
+Run `python scripts/run_enrichment.py --help` for all options (background file, FDR cutoff, min/max set size, permutations).
+
+## Common Pitfalls
+
+These cause most wrong or irreproducible results:
+
+1. **Gene-ID / organism mismatch** — symbols vs Ensembl, human vs mouse casing. Map IDs and set `organism` correctly, or matches silently drop to ~zero.
+2. **Wrong background (ORA)** — using the whole genome instead of the tested/expressed gene set inflates p-values. Set a custom background when it matters.
+3. **Thresholding before GSEA** — GSEA needs the *full* ranked list; only ORA uses a cut list.
+4. **Ranking GSEA by log2FoldChange alone** — unstable for low-count genes; prefer `stat` or `sign(LFC) * -log10(p)`.
+5. **Multiple-testing across libraries** — FDR is computed *within* a library; running many libraries multiplies tests. Report per-library FDR and stay conservative.
+6. **Redundant GO terms** — don't report 40 variants of the same term; collapse and show representatives.
+7. **Significance ≠ relevance** — check the overlap count and gene-set size; tiny sets reach significance trivially.
+8. **List too short/long for ORA** — <10 genes is underpowered; >2000 loses specificity (consider GSEA instead).
+9. **No reproducibility metadata** — Enrichr/GO libraries are versioned and drift over time. Record library names+date and set a GSEA `seed`.
+
+## Integration with Other Skills
+
+- **Upstream (where genes come from):** `pydeseq2` (DE genes + `stat` for GSEA), `scanpy` (`rank_genes_groups` markers / scores), `depmap`/`pytdc` (screen hits), proteomics skills (`pyopenms`, `matchms`).
+- **Databases / IDs:** `database-lookup` (Reactome, KEGG, STRING, Gene Ontology APIs), `gget` (`gget enrichr` quick path, `gget info` for ID mapping), `bioservices`.
+- **Downstream:** `scientific-visualization` (custom figures), `networkx` (enrichment-map graphs), `scientific-writing` / `literature-review` (interpret and cite), `statistical-analysis` (multiple-testing details).
+
+## Reference Files
+
+Read the relevant file when you need depth:
+
+- `references/gseapy.md` — full gseapy API: `enrichr`, offline `enrich`, `prerank`, `gsea`, `ssgsea`, `gsva`, `Msigdb`, `Biomart`, `get_library_name`/`read_gmt`, every plot, result-column meanings, GMT/offline usage, and troubleshooting (rate limits, empty results).
+- `references/databases-and-gene-sets.md` — GO, KEGG, Reactome, WikiPathways, MSigDB collections, Enrichr library naming, g:Profiler sources, organism handling, gene-ID conversion, library selection by question, and pointers to Reactome/STRING APIs and decoupler activity inference.
+- `references/interpretation.md` — ORA vs GSEA statistics, background-universe choice, multiple-testing methods (BH vs g:SCS vs Bonferroni), leading-edge genes, redundancy reduction, effect vs significance, a publication-table template, and reproducibility checklist.
+
+## Resources
+
+- gseapy docs: https://gseapy.readthedocs.io/ · repo: https://github.com/zqfang/GSEApy
+- g:Profiler: https://biit.cs.ut.ee/gprofiler/ · Python client: https://pypi.org/project/gprofiler-official/
+- Enrichr: https://maayanlab.cloud/Enrichr/ · MSigDB: https://www.gsea-msigdb.org/gsea/msigdb/
+- GSEA method: Subramanian et al. (2005) PNAS, DOI: 10.1073/pnas.0506580102