@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/pathway-enrichment/references/databases-and-gene-sets.md

@@ -0,0 +1,140 @@
+# Databases, Gene Sets, and Gene-ID Mapping
+
+## Contents
+- [Picking libraries by question](#picking-libraries-by-question)
+- [The main gene-set databases](#the-main-gene-set-databases)
+- [MSigDB collections](#msigdb-collections)
+- [g:Profiler (alternative ORA, custom background, 500+ organisms)](#gprofiler)
+- [Gene-ID types and conversion](#gene-id-types-and-conversion)
+- [Organism handling](#organism-handling)
+- [Pathway/interaction APIs (Reactome, KEGG, STRING)](#pathwayinteraction-apis)
+- [Activity inference (decoupler: PROGENy, DoRothEA/CollecTRI)](#activity-inference)
+
+## Picking libraries by question
+
+Match the database to the biological question instead of running everything:
+
+| Question | Best gene sets |
+|----------|----------------|
+| "What are the broad themes?" | MSigDB **Hallmark** (50 curated, low redundancy) |
+| "What mechanism/process?" | **GO Biological Process** |
+| "Which curated pathways?" | **Reactome**, **KEGG**, **WikiPathways** |
+| "Molecular function / localization?" | GO MF / GO CC |
+| "Immune signatures?" | MSigDB **C7** (ImmuneSigDB) |
+| "Oncogenic / perturbation?" | MSigDB **C6** (oncogenic), **C2:CGP** |
+| "TF targets / regulons?" | MSigDB **C3**, ChEA, or decoupler (below) |
+| "Disease/phenotype association?" | g:Profiler HP, DisGeNET, GWAS Catalog |
+
+Start narrow (Hallmark + one of GO:BP / Reactome). Add libraries only if the
+question needs them — each extra library multiplies the testing burden.
+
+## The main gene-set databases
+
+- **GO (Gene Ontology)** — three namespaces: Biological Process (BP), Molecular
+  Function (MF), Cellular Component (CC). Hierarchical → highly redundant; collapse
+  terms after testing (see `interpretation.md`).
+- **KEGG** — manually curated metabolic & signaling pathways. Compact, well known.
+- **Reactome** — large, expert-curated, hierarchical human pathway set; good
+  granularity. APIs in `database-lookup`.
+- **WikiPathways** — community-curated pathways; complements KEGG/Reactome.
+- **MSigDB** — collections of collections (Hallmark, curated, GO, immune, etc.);
+  the standard source of GMT files for GSEA.
+
+## MSigDB collections
+
+| Collection | Contents |
+|-----------|----------|
+| **H** (`h.all`) | Hallmark — 50 refined, non-redundant signatures (best default for GSEA) |
+| **C2:CP** | Canonical Pathways: `c2.cp.kegg_medicus`, `c2.cp.reactome`, `c2.cp.wikipathways`, `c2.cp.biocarta` |
+| **C2:CGP** | Chemical & genetic perturbations |
+| **C3** | Regulatory targets (TFT, miRNA) |
+| **C5** | Ontology: `c5.go.bp`, `c5.go.mf`, `c5.go.cc`, `c5.hpo` |
+| **C6** | Oncogenic signatures |
+| **C7** | ImmuneSigDB |
+| **C8** | Cell-type signatures |
+
+Fetch via gseapy: `gp.Msigdb().get_gmt(category="h.all", dbver="2024.1.Hs")`
+(use `dbver="…Mm"` for mouse symbols). See `gseapy.md`.
+
+## g:Profiler
+
+The official client (`gprofiler-official`) is the best path when you need a
+**custom background**, **many organisms** (~500), or g:Profiler's `g:SCS`
+multiple-testing correction. It performs ORA over GO, KEGG, Reactome,
+WikiPathways, miRTarBase, CORUM, HP, and more in one call.
+
+```python
+from gprofiler import GProfiler
+
+gp = GProfiler(return_dataframe=True)
+res = gp.profile(
+    organism="hsapiens",                      # mmusculus, dmelanogaster, ...
+    query=gene_list,                          # symbols, Ensembl, Entrez — auto-detected
+    sources=["GO:BP", "KEGG", "REAC", "WP"],  # restrict sources
+    user_threshold=0.05,
+    significance_threshold_method="g_SCS",    # default; or "fdr" / "bonferroni"
+    domain_scope="custom",                    # use a custom statistical background
+    background=expressed_genes,               # the tested/expressed universe
+    no_iea=False,                             # True = drop electronic GO annotations
+)
+# columns: source, native, name, p_value, term_size, query_size,
+#          intersection_size, effective_domain_size, intersections
+```
+
+`gp.convert(organism="hsapiens", query=ids, target_namespace="ENTREZGENE")` maps
+IDs; `gp.orth(...)` maps orthologs across organisms.
+
+## Gene-ID types and conversion
+
+Enrichr and MSigDB libraries are keyed by **gene symbols**. Convert other ID
+types before ORA/GSEA, or matches silently drop.
+
+| You have | Convert with |
+|----------|--------------|
+| Ensembl gene IDs (`ENSG…`) | `gp.Biomart`, g:Profiler `g:Convert`, or `mygene` |
+| Entrez IDs | `mygene`, g:Profiler |
+| Mouse symbols → human | g:Profiler `g:Orth`, `mygene` (then run human libraries) |
+
+`mygene` example:
+```python
+import mygene
+mg = mygene.MyGeneInfo()
+hits = mg.querymany(ensembl_ids, scopes="ensembl.gene",
+                    fields="symbol", species="human", as_dataframe=True)
+symbols = hits["symbol"].dropna().tolist()
+```
+Strip Ensembl version suffixes first (`ENSG00000141510.16` → `ENSG00000141510`).
+The `gget` skill (`gget info`) is another quick ID-mapping path.
+
+## Organism handling
+
+- Human symbols are UPPERCASE (`TP53`); mouse symbols are Title-case (`Trp53`).
+- Set `organism=` for `gp.enrichr` (Enrichr) and use the matching MSigDB `dbver`
+  (`…Hs` vs `…Mm`) or g:Profiler `organism=` code.
+- Don't run human libraries on mouse symbols — convert or map orthologs first.
+
+## Pathway/interaction APIs
+
+For raw pathway content or network context (not enrichment statistics), use the
+`database-lookup` skill, which wraps:
+- **Reactome** content + Analysis Service (submit a gene list, get pathway
+  over-representation).
+- **KEGG** pathways/compounds.
+- **STRING** — protein–protein interactions plus its own functional-enrichment
+  endpoint for a submitted gene set; pairs well with `networkx` for network views.
+- **Gene Ontology / QuickGO** term metadata.
+
+## Activity inference
+
+When the goal is **pathway or TF activity** (a continuous score per sample/cell)
+rather than over-representation of a list, use `decoupler`. It runs multiple
+enrichment/activity methods (ORA, GSEA, univariate linear models, etc.) against
+curated priors:
+- **PROGENy** — 14 signaling pathway responsive signatures.
+- **DoRothEA / CollecTRI** — TF→target regulons for TF-activity inference.
+- **MSigDB** priors via its OmniPath integration.
+
+decoupler integrates natively with AnnData/Scanpy (per-cell activities) and with
+per-sample pseudobulk matrices. APIs evolve between major versions — check the
+current decoupler docs (https://decoupler-py.readthedocs.io/) for exact function
+names before writing code.

package/skills/pathway-enrichment/references/gseapy.md

@@ -0,0 +1,189 @@
+# gseapy Reference
+
+gseapy (v1.1.x, Python/Rust) wraps GSEA, preranked GSEA, ssGSEA, GSVA, and the
+Enrichr API behind a pandas-friendly interface. License: BSD-3-Clause.
+
+## Contents
+- [Module map](#module-map)
+- [ORA: enrichr (online) and enrich (offline)](#ora)
+- [Preranked GSEA](#preranked-gsea)
+- [Standard GSEA (matrix + classes)](#standard-gsea)
+- [ssGSEA and GSVA](#ssgsea-and-gsva)
+- [Gene sets: libraries, MSigDB, GMT](#gene-sets)
+- [Gene-ID mapping with Biomart](#biomart)
+- [Plotting](#plotting)
+- [Result columns](#result-columns)
+- [Troubleshooting](#troubleshooting)
+
+## Module map
+
+```python
+import gseapy as gp
+gp.enrichr      # online ORA via Enrichr API
+gp.enrich       # offline ORA against a local GMT / dict
+gp.prerank      # preranked GSEA (per-gene score)
+gp.gsea         # standard GSEA (expression matrix + class labels)
+gp.ssgsea       # single-sample GSEA (per-sample scores)
+gp.gsva         # GSVA (per-sample scores)
+gp.Msigdb       # download MSigDB collections
+gp.Biomart      # gene/ID conversion
+gp.get_library_name(organism="human")  # list Enrichr libraries
+gp.get_library("KEGG_2021_Human")      # fetch a library as a dict
+gp.read_gmt("sets.gmt")                 # load a local GMT as a dict
+# plots: gp.dotplot, gp.barplot, gp.ringplot, gp.enrichment_map,
+#        gp.gseaplot, gp.gseaplot2, gp.heatmap
+```
+
+## ORA
+
+### enrichr (online)
+```python
+enr = gp.enrichr(
+    gene_list=genes,                 # list, Series, DataFrame, or txt path (symbols)
+    gene_sets=["MSigDB_Hallmark_2020", "KEGG_2021_Human"],  # names, GMT, or dict
+    organism="human",                # human|mouse|fly|yeast|worm|fish
+    background=None,                  # list or count; default is the library background
+    outdir=None,                      # None = in-memory only
+)
+enr.results        # DataFrame: all terms across all libraries (Gene_set column)
+```
+Key result columns: `Gene_set`, `Term`, `Overlap` (k/K), `P-value`,
+`Adjusted P-value` (BH within library), `Odds Ratio`, `Combined Score`, `Genes`.
+
+`background` note: Enrichr's online API largely ignores arbitrary custom
+backgrounds (it has fixed per-library backgrounds). For a true custom background
+use `gp.enrich()` (below) or g:Profiler. See `interpretation.md`.
+
+### enrich (offline, custom background)
+```python
+gene_sets = gp.read_gmt("c2.cp.reactome.v2024.1.Hs.symbols.gmt")  # dict
+enr = gp.enrich(
+    gene_list=genes,
+    gene_sets=gene_sets,
+    background=expressed_genes,       # REQUIRED here; the tested/expressed universe
+    outdir=None,
+)
+```
+Use this when reviewers will ask about the background, or when offline.
+
+## Preranked GSEA
+
+```python
+pre = gp.prerank(
+    rnk=rnk,                          # Series indexed by gene, or 2-col DataFrame/.rnk path
+    gene_sets=["MSigDB_Hallmark_2020"],
+    min_size=15, max_size=500,        # filter sets by size
+    permutation_num=1000,             # >=1000 for publication
+    weight=1.0,                       # weighted KS (classic = 0)
+    seed=123, threads=4, outdir=None,
+)
+pre.res2d        # DataFrame of results (see Result columns)
+pre.results      # dict keyed by term with ES curve, lead genes, etc.
+```
+`rnk` must be sorted high→low and have no duplicate gene IDs. Rank by the DESeq2
+`stat`, or `sign(log2FoldChange) * -log10(pvalue)`; avoid log2FC alone.
+
+## Standard GSEA
+
+When you have the expression matrix and class labels (rather than a precomputed
+rank), GSEA computes the ranking internally per the chosen metric.
+```python
+gsea = gp.gsea(
+    data=expr_df,                     # genes x samples (DataFrame or GCT path)
+    gene_sets="MSigDB_Hallmark_2020",
+    cls=["A","A","B","B"],            # class vector or .cls path
+    permutation_type="phenotype",     # or "gene_set" for few samples
+    method="signal_to_noise",         # ranking metric
+    permutation_num=1000, seed=123, threads=4, outdir=None,
+)
+gsea.res2d
+```
+With < ~7 samples per group, use `permutation_type="gene_set"`.
+
+## ssGSEA and GSVA
+
+Per-sample pathway scores (no class labels) — useful as features for ML or for
+heatmaps of pathway activity across samples/cells.
+```python
+ss = gp.ssgsea(data=expr_df, gene_sets="MSigDB_Hallmark_2020",
+               sample_norm_method="rank", outdir=None, threads=4)
+ss.res2d                              # long-form NES per (Term, Name)
+scores = ss.res2d.pivot(index="Term", columns="Name", values="NES")  # terms x samples
+
+gsva = gp.gsva(data=expr_df, gene_sets="MSigDB_Hallmark_2020", outdir=None)
+```
+
+## Gene sets
+
+### List / fetch Enrichr libraries
+```python
+gp.get_library_name(organism="human")     # names drift; check, don't hardcode
+lib = gp.get_library("Reactome_2022")     # dict: {term: [genes]}
+```
+Common human libraries: `MSigDB_Hallmark_2020`, `GO_Biological_Process_2023`,
+`GO_Molecular_Function_2023`, `GO_Cellular_Component_2023`, `KEGG_2021_Human`,
+`Reactome_2022`, `WikiPathway_2023_Human`, `MSigDB_Oncogenic_Signatures`.
+
+### MSigDB collections
+```python
+msig = gp.Msigdb()
+print(msig.list_dbver())                   # available MSigDB versions
+cats = msig.list_category(dbver="2024.1.Hs")
+hallmark = msig.get_gmt(category="h.all", dbver="2024.1.Hs")  # dict for prerank/gsea
+```
+Useful categories: `h.all` (Hallmark), `c2.cp.kegg_medicus`, `c2.cp.reactome`,
+`c2.cp.wikipathways`, `c5.go.bp`, `c7.immunesigdb`.
+
+### Local GMT
+```python
+gene_sets = gp.read_gmt("my_sets.gmt")     # then pass to enrich/prerank/gsea
+```
+
+## Biomart
+
+```python
+bm = gp.Biomart()
+# Ensembl gene IDs -> HGNC symbols
+conv = bm.query(dataset="hsapiens_gene_ensembl",
+                attributes=["ensembl_gene_id", "external_gene_name"],
+                filters={"ensembl_gene_id": ensembl_ids})
+```
+For mouse→human ortholog mapping or many IDs, g:Profiler `g:Convert`/`g:Orth`
+or the `mygene` package are often easier (see `databases-and-gene-sets.md`).
+
+## Plotting
+
+```python
+gp.dotplot(enr.results, column="Adjusted P-value", size=5, top_term=15,
+           title="ORA", cmap="viridis_r", ofname="dot.png")
+gp.barplot(enr.results, column="Adjusted P-value", top_term=15, ofname="bar.png")
+gp.dotplot(pre.res2d, column="FDR q-val", title="GSEA", ofname="gsea_dot.png")  # GSEA
+gp.gseaplot(term=pre.res2d.Term.iloc[0], ofname="running.png",
+            **pre.results[pre.res2d.Term.iloc[0]])                    # running-ES curve
+gp.enrichment_map(pre.res2d)          # nodes=terms, edges=gene overlap (returns graph)
+```
+`dotplot`/`barplot` return a Matplotlib `Axes`; `get_figure().savefig(...)` to save.
+
+## Result columns
+
+Enrichr (ORA): `Gene_set`, `Term`, `Overlap`, `P-value`, `Adjusted P-value`,
+`Old P-value`, `Old Adjusted P-value`, `Odds Ratio`, `Combined Score`, `Genes`.
+
+GSEA/prerank (`res2d`): `Name`, `Term`, `ES` (enrichment score), `NES`
+(normalized ES — compare across sets), `NOM p-val`, `FDR q-val`, `FWER p-val`,
+`Tag %`, `Gene %`, `Lead_genes` (leading-edge genes driving the signal).
+
+Rank by `NES` for direction/magnitude; filter by `FDR q-val`. Positive NES =
+enriched at the top of the rank (e.g., up in your test condition).
+
+## Troubleshooting
+
+- **Empty / near-empty results** → almost always a gene-ID or organism mismatch.
+  Check overlap: `set(genes) & set(gp.get_library(lib).keys()...)`; confirm symbols
+  and `organism`.
+- **HTTP errors / timeouts from Enrichr or MSigDB** → transient; retry, reduce the
+  number of libraries, or switch to offline `gp.enrich()` with a local GMT.
+- **`prerank` complains about duplicates / non-numeric** → dedupe the index and
+  coerce scores to float; drop NaN before sorting.
+- **Too few genes match a set** → raise `min_size` caution; tiny overlaps are noise.
+- **Different results between runs (GSEA)** → set `seed` and report `permutation_num`.

package/skills/pathway-enrichment/references/interpretation.md

@@ -0,0 +1,118 @@
+# Interpreting Enrichment Results
+
+## Contents
+- [ORA vs GSEA: the statistics](#ora-vs-gsea-the-statistics)
+- [The background universe (ORA)](#the-background-universe-ora)
+- [Multiple-testing correction](#multiple-testing-correction)
+- [Reading GSEA output](#reading-gsea-output)
+- [Reducing redundant terms](#reducing-redundant-terms)
+- [Significance vs relevance](#significance-vs-relevance)
+- [Reproducibility checklist](#reproducibility-checklist)
+- [Publication table template](#publication-table-template)
+- [Common misinterpretations](#common-misinterpretations)
+
+## ORA vs GSEA: the statistics
+
+**ORA** asks: among my *k* hits (out of a background of *N* genes), are more in
+gene set *S* (size *K*) than expected by chance? This is a hypergeometric /
+Fisher's exact test. It depends entirely on the threshold used to define hits and
+on the background *N*. Good when there is a clear, strong hit list.
+
+**GSEA** asks: walking down the *fully ranked* list of all tested genes, is gene
+set *S* concentrated near the top (or bottom)? It uses a weighted Kolmogorov–
+Smirnov-like running sum; significance comes from permutations. No arbitrary
+threshold; sensitive to coordinated, modest shifts across many genes. Better when
+effects are broad/subtle or when a hit list would be very short or very long.
+
+Rule of thumb: a discrete hit list → ORA; a ranked table with per-gene scores →
+GSEA. They answer different questions and can legitimately disagree.
+
+## The background universe (ORA)
+
+The background (the "domain" / universe) is the set of genes that *could* have
+appeared as a hit. For RNA-seq that is the set of **expressed/tested genes**, not
+all ~20,000 protein-coding genes. Using too large a background makes ordinary
+housekeeping categories look significant — the most common way ORA results
+mislead.
+
+- Enrichr's online API uses fixed per-library backgrounds and largely ignores a
+  custom one. If the background matters for your claim, use **g:Profiler**
+  (`domain_scope='custom'`, `background=...`) or **gseapy `gp.enrich()`** with an
+  explicit `background`.
+- The background should use the same ID namespace as the query and the library.
+
+## Multiple-testing correction
+
+- **Benjamini–Hochberg (FDR)** — default for Enrichr/gseapy (`Adjusted P-value`,
+  `FDR q-val`). Controls expected false-discovery proportion. Use `< 0.05`.
+- **g:SCS** — g:Profiler's default; accounts for the correlated structure of GO
+  and overlapping terms; generally stricter and more appropriate than BH for
+  ontology hierarchies.
+- **Bonferroni** — very conservative; only when you have few, independent tests.
+
+FDR is computed *within a library/run*. Running many libraries multiplies the
+total tests, so report per-library FDR and avoid cherry-picking the one library
+that produced a hit.
+
+## Reading GSEA output
+
+- **NES (normalized enrichment score)** — the headline metric; normalized for set
+  size so it is comparable across sets. Sign = direction (positive = enriched at
+  the top of your ranking, e.g., up in the test condition).
+- **FDR q-val** — significance; filter on this (`< 0.05`, or `< 0.25` for
+  exploratory hypothesis generation, the GSEA convention).
+- **Leading-edge genes** (`Lead_genes`) — the subset of genes that drive the
+  signal (those before the running-sum peak). Report these; they are the concrete
+  biology and are useful for overlap/redundancy analysis.
+
+## Reducing redundant terms
+
+GO and large pathway sets return many overlapping terms describing the same
+biology. Don't list 40 near-duplicates. Options:
+- **Enrichment map** — graph with terms as nodes and edges weighted by gene
+  overlap (Jaccard/overlap coefficient); cluster it and label clusters. gseapy:
+  `gp.enrichment_map(...)`; render with `networkx` (see the networkx skill).
+- **Leading-edge / gene overlap clustering** — group terms sharing most genes;
+  keep one representative per group.
+- **Parent terms / semantic similarity** — collapse child GO terms to a parent;
+  REVIGO-style reduction by semantic similarity.
+- Report a representative term per cluster plus the count of related terms.
+
+## Significance vs relevance
+
+- Check the **overlap count**, not just the p-value. "Term enriched, padj=0.01"
+  with 2 genes out of a 1500-gene set is rarely meaningful.
+- Watch **gene-set size**: tiny sets reach significance with few genes; huge,
+  generic sets ("metabolic process") are uninformative — the `min_size`/`max_size`
+  filters (15–500) exist for this reason.
+- A very short ORA input (<10 genes) is underpowered; a very long one (>2000)
+  loses specificity — prefer GSEA in both extremes.
+
+## Reproducibility checklist
+
+- Record exact **library names and versions/date** (Enrichr/GO libraries drift).
+- Record the **background** used (or state the default).
+- For GSEA, record `permutation_num`, `seed`, `min_size`, `max_size`, weight, and
+  the **ranking metric** (e.g., DESeq2 `stat`).
+- State the **organism** and **gene-ID namespace**.
+- Save the full results table, not just the filtered top hits.
+
+## Publication table template
+
+Report a compact, reviewer-friendly table:
+
+| Term | Source | Direction (NES / Odds Ratio) | Overlap / Set size | FDR | Key genes |
+|------|--------|------------------------------|--------------------|-----|-----------|
+| Interferon alpha response | Hallmark | NES +2.1 | 38/97 | 1e-4 | STAT1, IRF7, ISG15 |
+
+For ORA use Odds Ratio + Overlap (k/K); for GSEA use NES + leading-edge size.
+Note method, library version, background, and correction in the legend.
+
+## Common misinterpretations
+
+- "Enriched pathway X" does **not** mean pathway X is activated — ORA is
+  direction-agnostic unless you split up/down lists; GSEA NES sign gives direction.
+- Overlapping significant GO terms are **not** independent findings.
+- Absence of enrichment ≠ absence of biology (power, annotation gaps, wrong
+  background, or ID mismatch can all hide real signal).
+- Don't compare raw ES across gene sets — use NES.

package/skills/pathway-enrichment/scripts/run_enrichment.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""Run over-representation (ORA) or preranked GSEA with gseapy.
+
+Handles the boilerplate that every enrichment run repeats: symbol cleanup,
+deduplication, NA removal, building a ranking metric from a DESeq2 table,
+per-library FDR filtering, and a dotplot. Outputs a combined results CSV and a
+dotplot PNG into --outdir.
+
+Examples
+--------
+# ORA from a hit list (one gene symbol per line, or a CSV whose first column is genes)
+python 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 rank from `stat`)
+python 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 ranked file with columns: gene,score
+python run_enrichment.py gsea --rnk ranked_genes.csv --outdir results/
+
+Requires: gseapy, pandas, matplotlib (uv pip install gseapy).
+Network access is needed for Enrichr / library downloads.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+try:
+    import gseapy as gp
+except ImportError:
+    print("Error: gseapy not installed. Install with: uv pip install gseapy")
+    sys.exit(1)
+
+DEFAULT_LIBRARIES = [
+    "MSigDB_Hallmark_2020",
+    "GO_Biological_Process_2023",
+    "KEGG_2021_Human",
+    "Reactome_2022",
+]
+
+
+def _clean_symbols(genes, organism: str):
+    """Normalize gene symbols (human -> UPPER, mouse -> Title) and dedupe."""
+    out, seen = [], set()
+    for g in genes:
+        g = str(g).strip()
+        if not g or g.lower() in {"nan", "none"}:
+            continue
+        if organism == "human":
+            g = g.upper()
+        elif organism == "mouse":
+            g = g.capitalize()
+        if g not in seen:
+            seen.add(g)
+            out.append(g)
+    return out
+
+
+def _read_gene_list(path: Path):
+    """Read a gene list: one per line, or the first column of a CSV/TSV."""
+    if path.suffix.lower() in {".csv", ".tsv"}:
+        sep = "\t" if path.suffix.lower() == ".tsv" else ","
+        df = pd.read_csv(path, sep=sep)
+        return df.iloc[:, 0].tolist()
+    return [line.strip() for line in path.read_text().splitlines() if line.strip()]
+
+
+def _build_rank_from_deseq2(path: Path, organism: str) -> pd.Series:
+    """Build a ranking metric from a DESeq2-style results table.
+
+    Prefers the Wald `stat`; otherwise sign(log2FoldChange) * -log10(pvalue).
+    """
+    df = pd.read_csv(path, index_col=0)
+    cols = {c.lower(): c for c in df.columns}
+    if "stat" in cols:
+        rnk = df[cols["stat"]].dropna()
+    elif "log2foldchange" in cols and "pvalue" in cols:
+        lfc = df[cols["log2foldchange"]]
+        pval = df[cols["pvalue"]].clip(lower=1e-300)
+        rnk = (np.sign(lfc) * -np.log10(pval)).dropna()
+    else:
+        sys.exit(
+            "DESeq2 table needs a 'stat' column, or 'log2FoldChange' + 'pvalue'. "
+            f"Found: {list(df.columns)}"
+        )
+    rnk.index = _clean_index(rnk.index, organism)
+    rnk = rnk[~rnk.index.duplicated(keep="first")]
+    return rnk.sort_values(ascending=False)
+
+
+def _read_rnk(path: Path, organism: str) -> pd.Series:
+    """Read an explicit ranked file: columns gene,score (header optional)."""
+    df = pd.read_csv(path, header=None)
+    if df.shape[1] < 2:
+        sys.exit("Ranked file must have two columns: gene,score")
+    # Drop a header row if the score column is not numeric.
+    if not pd.api.types.is_numeric_dtype(pd.to_numeric(df[1], errors="coerce")):
+        df = df.iloc[1:]
+    rnk = pd.Series(
+        pd.to_numeric(df[1].values, errors="coerce"),
+        index=df[0].astype(str).values,
+    ).dropna()
+    rnk.index = _clean_index(rnk.index, organism)
+    rnk = rnk[~rnk.index.duplicated(keep="first")]
+    return rnk.sort_values(ascending=False)
+
+
+def _clean_index(index, organism: str):
+    idx = pd.Index([str(g).strip() for g in index])
+    if organism == "human":
+        idx = idx.str.upper()
+    elif organism == "mouse":
+        idx = idx.str.capitalize()
+    return idx
+
+
+def _dotplot(df: pd.DataFrame, column: str, title: str, outpath: Path):
+    try:
+        ax = gp.dotplot(df, column=column, title=title, top_term=15, cutoff=1.0)
+        fig = ax.get_figure()
+        fig.savefig(outpath, dpi=200, bbox_inches="tight")
+        print(f"  dotplot -> {outpath}")
+    except Exception as exc:  # plotting is best-effort, never fatal
+        print(f"  (dotplot skipped: {exc})")
+
+
+def run_ora(args):
+    genes = _clean_symbols(_read_gene_list(Path(args.genes)), args.organism)
+    if len(genes) < 5:
+        print(f"WARNING: only {len(genes)} genes after cleanup; ORA is underpowered.")
+    background = None
+    if args.background:
+        background = _clean_symbols(_read_gene_list(Path(args.background)), args.organism)
+
+    enr = gp.enrichr(
+        gene_list=genes,
+        gene_sets=args.libraries,
+        organism=args.organism,
+        background=background,
+        outdir=None,
+    )
+    res = enr.results.copy()
+    sig = res[res["Adjusted P-value"] < args.fdr].sort_values("Adjusted P-value")
+    print(f"{len(sig)}/{len(res)} terms with Adjusted P-value < {args.fdr}")
+    return res, sig, "Adjusted P-value"
+
+
+def run_gsea(args):
+    if args.deseq2:
+        rnk = _build_rank_from_deseq2(Path(args.deseq2), args.organism)
+    elif args.rnk:
+        rnk = _read_rnk(Path(args.rnk), args.organism)
+    else:
+        sys.exit("GSEA needs --deseq2 or --rnk")
+    print(f"Ranked {len(rnk)} genes (top: {rnk.index[0]}={rnk.iloc[0]:.2f}, "
+          f"bottom: {rnk.index[-1]}={rnk.iloc[-1]:.2f})")
+
+    pre = gp.prerank(
+        rnk=rnk,
+        gene_sets=args.libraries,
+        min_size=args.min_size,
+        max_size=args.max_size,
+        permutation_num=args.permutations,
+        seed=args.seed,
+        threads=args.threads,
+        outdir=None,
+    )
+    res = pre.res2d.copy()
+    res["FDR q-val"] = pd.to_numeric(res["FDR q-val"], errors="coerce")
+    sig = res[res["FDR q-val"] < args.fdr].sort_values("FDR q-val")
+    print(f"{len(sig)}/{len(res)} gene sets with FDR q-val < {args.fdr}")
+    return res, sig, "FDR q-val"
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="method", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--libraries", nargs="+", default=DEFAULT_LIBRARIES,
+                        help="Enrichr library names, GMT paths, or MSigDB names.")
+    common.add_argument("--organism", default="human",
+                        help="human, mouse, fly, yeast, worm, fish (default: human).")
+    common.add_argument("--outdir", default="enrichment_results", help="Output directory.")
+    common.add_argument("--fdr", type=float, default=0.05, help="Adjusted-p/FDR cutoff.")
+
+    ora = sub.add_parser("ora", parents=[common], help="Over-representation analysis.")
+    ora.add_argument("--genes", required=True, help="Hit list: one symbol per line or CSV first column.")
+    ora.add_argument("--background", help="Optional background gene list file.")
+
+    gsea = sub.add_parser("gsea", parents=[common], help="Preranked GSEA.")
+    gsea.add_argument("--deseq2", help="DESeq2 results CSV (index=genes; uses `stat`).")
+    gsea.add_argument("--rnk", help="Ranked file with columns: gene,score.")
+    gsea.add_argument("--min-size", type=int, default=15, dest="min_size")
+    gsea.add_argument("--max-size", type=int, default=500, dest="max_size")
+    gsea.add_argument("--permutations", type=int, default=1000)
+    gsea.add_argument("--seed", type=int, default=123)
+    gsea.add_argument("--threads", type=int, default=4)
+
+    args = p.parse_args()
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    if args.method == "ora":
+        res, sig, col = run_ora(args)
+        title = "ORA"
+    else:
+        res, sig, col = run_gsea(args)
+        title = "GSEA (preranked)"
+
+    res_path = outdir / f"{args.method}_results.csv"
+    sig_path = outdir / f"{args.method}_significant.csv"
+    res.to_csv(res_path, index=False)
+    sig.to_csv(sig_path, index=False)
+    print(f"all terms -> {res_path}")
+    print(f"significant -> {sig_path}")
+    _dotplot(sig if len(sig) else res, col, title, outdir / f"{args.method}_dotplot.png")
+
+
+if __name__ == "__main__":
+    main()