pathway-enrichment

用途

Pathway Enrichment 用于对基因列表或带排序的基因数据运行通路与基因集富集分析，并解读结果。它回答的核心问题是“我的基因中哪些生物学过程被显著富集”，通常作为差异表达分析、筛选或聚类之后的标准收尾步骤。

主要能力

该技能支持两类核心方法：

ORA（过表征分析）：输入经过阈值筛选的基因列表（例如 padj < 0.05），使用 Fisher 精确检验 / 超几何检验，判断哪些基因集被显著重叠。常用工具为 Enrichr、g:Profiler。
GSEA（基因集富集分析）：输入完整的排序基因列表（不设阈值），检验每个基因集是否集中在列表顶部或底部。Preranked GSEA 使用每个基因的评分（例如 DESeq2 的 stat）。当效应广泛而微弱时更适用。

此外还支持：

对每个样本/细胞进行通路活性打分（ssGSEA、GSVA）。
解读、去重和可视化富集结果，或构建发表级表格/图。
在 ORA 与 GSEA 之间做选择、挑选基因集库、选择背景、修复基因 ID 问题。

使用方式

安装：

uv pip install gseapy gprofiler-official

gseapy 会拉取 pandas、numpy、scipy、matplotlib。Enrichr、g:Profiler 和 MSigDB 下载需要网络访问。若需完全离线的 ORA，可使用本地 GMT 文件配合 gp.enrich()。

验证并列出可用的基因集库（名称会随时间变化，不要盲目硬编码）：

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])

对命中列表运行 ORA（gseapy + Enrichr）：

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))

从 DESeq2 结果运行 Preranked GSEA：

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))

如果没有 stat 列，可用 sign(log2FoldChange) * -log10(pvalue) 构建排序。

核心工作流包括：确定输入并选择方法；将基因 ID 转换到正确命名空间；选择与问题匹配的基因集库；设置背景基因集（仅 ORA）；运行分析；按校正后 p 值过滤；可视化；降低冗余并解读。

辅助脚本 scripts/run_enrichment.py 可端到端运行 ORA 或 GSEA，写出结果表与点图，处理符号清理、去重、去除 NA、从 DESeq2 表构建排序、按库进行 FDR 过滤等样板工作：

# 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/

运行 python scripts/run_enrichment.py --help 可查看所有选项（背景文件、FDR 阈值、最小/最大集合大小、置换次数）。

适用场景

在基因列表中寻找富集的 GO 术语 / KEGG / Reactome / WikiPathways / MSigDB Hallmark 基因集。
对 DESeq2、edgeR、limma 或 Scanpy rank_genes_groups 输出运行 GSEA / preranked GSEA。
对每个样本/细胞进行通路活性打分（ssGSEA、GSVA）。
解读、去重和可视化富集结果，或构建发表级表格/图。
在 ORA 与 GSEA 之间做选择、挑选基因集库、选择背景、修复基因 ID 问题。

对于快速一次性 Enrichr 查询，gget 技能（gget enrichr）更轻量；对于原始通路/互作 API（Reactome、KEGG、STRING），参见 database-lookup 技能。本技能用于完整、可辩护的富集工作流。

限制与注意事项

常见陷阱包括：基因 ID / 物种不匹配（符号 vs Ensembl，人类 vs 小鼠大小写）；ORA 背景错误（使用全基因组而非检测/表达基因集会夸大 p 值）；在 GSEA 之前做阈值筛选（GSEA 需要完整排序列表）；仅用 log2FoldChange 排序 GSEA（对低计数基因不稳定）；跨库多重检验（FDR 在库内计算，运行多个库会成倍增加检验）；GO 术语冗余；显著性不等于相关性；ORA 列表过短或过长（<10 个基因功效不足，>2000 失去特异性）；缺少可重复性元数据（Enrichr/GO 库有版本且会漂移，需记录库名+日期并设置 GSEA 种子）。

参考文件包括 references/gseapy.md（完整 gseapy API）、references/databases-and-gene-sets.md（数据库与基因集）、references/interpretation.md（解读与统计）。资源包括 gseapy 文档、g:Profiler、Enrichr、MSigDB 以及 GSEA 方法论文（Subramanian et al. 2005 PNAS）。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项