tooluniverse-gene-enrichment

计算，而不是描述

当分析需要计算（统计、数据处理、评分、数据丰富化）时，通过 Bash 编写并运行 Python 代码。不要描述你会怎么做——直接执行并报告实际结果。使用 ToolUniverse 工具检索数据，然后用 Python（pandas、scipy、statsmodels、matplotlib）进行分析。

基因富集与通路分析

规则零——首先检查是否已有预计算结果

在遵循以下任何指示之前，先扫描数据文件夹，查找：

• *_executed.ipynb → 使用 tu run read_executed_notebook '{"data_folder":"<path>","search":"<keyword>"}' 读取，并将其单元格输出作为权威答案引用
• 预计算的富集文件（名称含 *enrich*、*go*、*kegg*、*reactome*、*ego*、*_simplified.csv 的 CSV/TSV 文件）→ 直接读取
• 规范分析脚本（analysis.R、run_*.py、find_*.R、*.Rmd）→ 按原样执行并读取输出

只有在上述文件都不存在时，才遵循本技能下方的重新分析流程。由于上游的筛选条件存在细微差异，从原始 DEG 列表重新运行富集分析会产生与已发表答案不同的数值，而且耗时更长。

---

主要脚本——优先使用

三个确定性 CLI 脚本覆盖了大多数富集分析问题。 每个脚本都能处理一些边界情况（顶部并列、simplify 改变 padj、多条件筛选），这些情况 Agent 编写临时代码时容易处理错误。 始终将输出写入 /tmp/...——切勿写入数据文件夹。

1. scripts/gseapy_enrichment_runner.py — gseapy enrichr / prerank

适用场景：问题提及 gseapy、enrichr、“Enrichr library”，或通过 gseapy 包进行任何 GO BP/MF/CC、KEGG、Reactome、WikiPathways、MSigDB 富集分析。

python skills/tooluniverse-gene-enrichment/scripts/gseapy_enrichment_runner.py \
    --gene-list /tmp/sig_symbols.txt \
    --library GO_Biological_Process_2021,Reactome_2022 \
    --organism Human \
    --top 5 \
    --candidate "negative regulation of epithelial cell proliferation" \
    --workdir /tmp/gseapy_run

报告内容（可解析的行）：

• # TOP_BY_ADJ_PVALUE: <term> — df.sort_values('Adjusted P-value').iloc[0] 返回的内容（已发表的笔记本通常会打印这一项）
• # TIES_AT_TOP: n=K — Adjusted P-value 最低且并列的术语数量
• # TOP_TIE_BROKEN: <term> — 确定性的并列排序结果（adj_p、raw_p、overlap 降序、字母顺序）
• # TOPN_BY_ADJ_PVALUE: — 完整的前 N 项列表
• # CANDIDATE_RANK '<term>': rank=R adj_p=... — 对传入的任何 --candidate 子字符串给出结果
• # SUBSTRING_COUNT_TOPN '<sub>': K — 用于 --count-substring 查询（例如，“前 20 个术语中有多少个包含 ‘Oxidative’”）

GSEA 预排序分析请传入 --mode prerank --ranked-list /tmp/lfc.tsv。

2. scripts/enrichgo_runner.py — clusterProfiler::enrichGO + simplify

适用场景：问题提及 enrichGO、clusterProfiler、simplify、simplify(cutoff=0.7)，或数据文件夹中包含使用这些功能的 analysis.R / find_*.R。这是规范的 R 工作流——gseapy 无法忠实复现，因为 simplify 会改变多重检验的分母，因此也会改变保留术语的 p.adjust 值。

python skills/tooluniverse-gene-enrichment/scripts/enrichgo_runner.py \
    --gene-list /tmp/sig_ensembl.txt \
    --background /tmp/bg_ensembl.txt \
    --keytype ENSEMBL \
    --ontology BP \
    --simplify-cutoff 0.7 \
    --candidate "regulation of T cell activation" \
    --candidate "potassium ion transmembrane transport" \
    --workdir /tmp/enrichgo_run

报告内容：

• # TOP10_RAW: — as.data.frame(ego) 中的前 10 项（simplify 之前；原始 p.adjust）
• # TOP10_SIMPLIFIED: — as.data.frame(simplify(ego, cutoff=0.7)) 中的前 10 项（simplify 之后；p.adjust 不同）
• # CANDIDATE '<term>': raw_rank=R raw_padj=... simp_rank=R simp_padj=... — 每个候选项在 simplify 前后的排名。simp_rank=NA (collapsed by simplify) 表示该术语与一个显著性更高的上级术语或同级术语重复，因此被移除。

问题提到“简化后的结果”或“simplify 之后”时，读取 simp_padj。如果问题只说“富集程度最高”，没有提到 simplify，那么如果规范的 analysis.R 调用了 simplify，默认使用简化后的数据框。

需要 R 包 clusterProfiler、org.Hs.eg.db（小鼠使用 org.Mm.eg.db）。若缺少这些包，请通过 Rscript skills/evals/install_r_packages.R 安装。

3. scripts/condition_enrichment_screen.py — 每个条件的富集分析

使用场景：问题询问“有多少比例的条件／筛选／时间点／组出现了某类别的显著富集”，或者你有一个 N 行、多列的基因表，需要按条件进行富集分析。

# Per-condition gene-list files:
python skills/tooluniverse-gene-enrichment/scripts/condition_enrichment_screen.py \
    --condition-genes acute=/tmp/acute_sig.txt \
    --condition-genes round1=/tmp/r1_sig.txt \
    --condition-genes round2=/tmp/r2_sig.txt \
    --condition-genes round3=/tmp/r3_sig.txt \
    --library /path/to/local_pathways.gmt \
    --background /tmp/expressed.txt \
    --keyword immune --keyword cytokine --keyword interferon \
    --workdir /tmp/cond_screen

或者通过 --conditions-tsv 传入单个 2 列 TSV（condition<TAB>gene）。

报告内容：

• 每个条件：n_genes、sig_terms（Adj P < cutoff）、sig_terms_keyword（其 Term 包含任意 --keyword 的显著条目）
• # n_with_any_sig=N pct_with_any_sig=N% — 至少有一个显著条目的条件所占比例
• # n_with_keyword_sig=N pct_with_keyword_sig=N% — 显著条目中包含类别关键词的条件所占比例

注意：

• --library 可以是 Enrichr 库名称（在线），也可以是本地 .gmt 文件的路径。如果数据文件夹中附带本地 GMT 文件，优先使用它（可避免速率限制，并准确复现已发表的结果）。
• 对于用户希望从分母中排除的“control”／“baseline”条件，使用 --exclude-condition <label>。
• 当问题询问“与免疫相关”的内容，但 GT 统计的是任意显著命中项时，请同时报告 pct_with_any_sig 和 pct_with_keyword_sig，让用户自行选择。

这些脚本的用途（调试说明）

富集分析的最高命中项主要取决于以下三点：

1. 上游 DEG 筛选条件（仅 padj？padj+|LFC|>0.5？再加上 baseMean>10？是否使用 lfc-shrunk？）。正确的筛选条件应与权威笔记本所用的一致。如果 Agent 在这里猜错，基因列表就会不同，最高条目也会随之改变。
2. 库快照 — Enrichr 库会重新发布。现在的 GO_Biological_Process_2021 可能与笔记本作者当时看到的不同。没有好的解决办法；请报告候选条目的排名，让用户判断。
3. 最高位的并列情况 — 许多运行会有 5–10 个或更多条目并列最低调整后 p 值。df.sort_values(...).iloc[0] 会返回 pandas 排在首位的条目（稳定排序会保留 Enrichr 的索引顺序）。已发表的答案可能会从并列项中选取更具体或生物学相关性更强的条目。

这些脚本会显露上述三种失败情况，让 Agent 能够匹配已发表结果的解读，而不是盲目报告 iloc[0]。

当 # TIES_AT_TOP: n=N 数值较大时（警示信号）

如果 gseapy_enrichment_runner.py 报告最低 Adj P-value 处有超过 5 个并列条目，那么你的基因列表很可能过小或有误。已发表的笔记本通常会得到清晰的最高条目，且只有一个最佳结果；大量并列通常说明上游 DEG 筛选或 ID 转换漏掉了大部分权威基因集。请重新检查：

• 是否应用了与笔记本相同的筛选条件？（仅 padj，还是 padj+|LFC|>thr，或再加上 baseMean>10）
• 基因 ID 空间是否相同？（symbols、Ensembl 还是 Entrez；是否带版本后缀）
• 基因名称查询后使用 dropna() 是否删除了过多基因？ 修正后重新运行，最高位的并列项数量应会大幅减少。

DEG 过滤器默认规则——仅使用问题中明确提及的条件

当问题描述输入基因列表时，仅应用问题中提及的阈值。不要默默添加 |LFC| > x、baseMean > y 或 LFC 收缩——额外的过滤条件会缩小基因列表并改变重叠计数。

问题措辞	应用的过滤条件
“所有显著 DEGs”、“显著 DEGs”、“padj<0.05 的 DEGs”	仅 padj < 0.05——不设 LFC 过滤条件，也不设 baseMean 过滤条件
“上调 DEGs”／“下调 DEGs”	仅 padj < 0.05 + log2FoldChange 的符号
“|LFC|>1 的 DEGs”或“fold change > 2”	padj < 0.05 + 指定的 LFC 阈值
“LFC 收缩后”／“apeglm 收缩后”	应用 lfcShrink()；否则不应用
问题提及 baseMean 或“表达基因”	应用指定的阈值；否则不应用

报告前交叉检查：统计过滤后基因列表的数量，并在报告中注明（n_sig=N）。如果发现自己添加了问题中未提及的过滤条件，请停下来重新考虑——过滤过度是重叠计数错误的主要原因之一（例如，报告 20/64，而正确答案是 22/64）。

---

执行全面的基因富集分析，包括 Gene Ontology（GO）、KEGG、Reactome、WikiPathways 和 MSigDB 富集，并同时采用过度表示分析（ORA）和基因集富集分析（GSEA）。结合使用 gseapy 本地计算和 ToolUniverse 通路数据库，生成经交叉验证、可用于发表的结果。

重要：工具调用中始终使用英文术语（基因名称、通路名称、物种名称），即使用户使用其他语言提问。只有在英文查询没有返回结果时，才尝试原语言术语。使用用户的语言作答。

领域推理：背景选择

富集结果的质量取决于背景集。默认背景（基因组中所有已注释的基因）会夸大组织特异性或情境特异性基因列表的富集结果。始终考虑本实验适用的背景集：脑部 RNA-seq 应使用脑部表达基因作为背景；蛋白质组学实验应使用检测到的蛋白质。一个基因若在你的系统中从未表达，就不能作为真正的阴性对照。

查找，不要猜测：调整后 p 值、基因集重叠计数，以及输入列表中哪些基因促成了每个富集条目。始终从富集结果中获取 inputGenes 字段——不要臆测哪些基因导致某个条目显著。当某个条目看起来出乎意料时，请检查哪些基因存在重叠并进行验证。

---

何时使用此技能

适用于用户：

• 询问基因富集分析（GO、KEGG、Reactome 等）
• 提供来自差异表达、聚类或任何实验的基因列表
• 想了解哪些生物过程、分子功能或细胞组分存在富集
• 需要 KEGG 或 Reactome 通路富集分析
• 询问使用排序基因列表进行 GSEA（基因集富集分析）
• 想使用 Fisher 精确检验进行过度表示分析（ORA）
• 需要多重检验校正（Benjamini-Hochberg、Bonferroni）
• 询问 enrichGO、gseapy、clusterProfiler 风格的分析

不适用于（请改用其他技能）：

• 网络药理学／药物再利用 → 使用 tooluniverse-network-pharmacology
• 疾病特征分析 → 使用 tooluniverse-multiomic-disease-characterization
• 单基因功能查询 → 使用 tooluniverse-disease-research
• 空间组学分析 → 使用 tooluniverse-spatial-omics-analysis
• 仅进行蛋白质—蛋白质相互作用分析 → 使用 tooluniverse-protein-interactions

---

输入参数

参数	必需	描述	示例
gene_list	是	基因符号、Ensembl ID 或 Entrez ID 列表	["TP53", "BRCA1", "EGFR"]
organism	否	生物物种（默认：human）。支持：human、mouse、rat、fly、worm、yeast、zebrafish	human
analysis_type	否	ORA（默认）或 GSEA	ORA
enrichment_databases	否	要查询的数据库。默认：所有适用数据库	["GO_BP", "GO_MF", "GO_CC", "KEGG", "Reactome"]
gene_id_type	否	输入 ID 类型：symbol、ensembl、entrez、uniprot（若省略则自动检测）	symbol
p_value_cutoff	否	显著性阈值（默认：0.05）	0.05
correction_method	否	多重检验校正：BH（Benjamini-Hochberg，默认）、bonferroni、fdr	BH
background_genes	否	自定义背景基因集（默认：全基因组）	["GENE1", "GENE2", ...]
ranked_gene_list	否	用于 GSEA：基因到分数的映射（例如 log2FC）	{"TP53": 2.5, "BRCA1": -1.3, ...}

---

核心原则

1. 报告优先 - 先创建报告文件，再逐步填充内容
2. 优先消歧 ID - 在进行任何富集分析之前，先检测并转换基因 ID
3. 多源验证 - 至少使用 2 个独立工具运行富集分析，并进行交叉验证
4. 精确 p 值 - 报告原始 p 值和校正后的 p 值，并注明校正方法
5. 多重检验校正 - 除非用户另有指定，否则始终使用 Benjamini-Hochberg 校正
6. 基因集大小筛选 - 按最小/最大基因集大小进行筛选，避免出现过于简单或范围过宽的术语
7. 证据分级 - 将富集结果来源评为 T1-T4
8. 记录阴性结果 - “未发现显著富集”也是有效结论
9. 注明来源 - 每项富集结果都必须注明所用工具/数据库/库
10. 完整性清单 - 在末尾添加必需的分析覆盖范围章节

---

决策树：ORA 与 GSEA

Q: Do you have a ranked gene list (with scores/fold-changes)?
  YES → Use GSEA (gseapy.prerank)
        - Input: Gene-to-score mapping (e.g., log2FC)
        - Statistics: Running enrichment score, permutation test
        - Cutoff: FDR q-val < 0.25 (standard for GSEA)
        - Output: NES (Normalized Enrichment Score), lead genes
        See: references/gsea_workflow.md

  NO  → Use ORA (gseapy.enrichr)
        - Input: Gene list only
        - Statistics: Fisher's exact test, hypergeometric
        - Cutoff: Adjusted P-value < 0.05 (or user specified)
        - Output: P-value, adjusted P-value, overlap, odds ratio
        See: references/ora_workflow.md

---

决策树：gseapy 与 ToolUniverse 工具

Q: Which enrichment method should I use?

Primary Analysis (ALWAYS):
  ├─ gseapy.enrichr (ORA) OR gseapy.prerank (GSEA)
  │  - Most comprehensive (225+ Enrichr libraries)
  │  - GO (BP, MF, CC), KEGG, Reactome, WikiPathways, MSigDB
  │  - All organisms supported
  │  - Returns: P-value, Adjusted P-value, Overlap, Genes
  │  See: references/enrichr_guide.md

Cross-Validation (REQUIRED for publication):
  ├─ PANTHER_enrichment [T1 - curated]
  │  - Curated GO enrichment
  │  - Multiple organisms (taxonomy ID)
  │  - GO BP, MF, CC, PANTHER pathways, Reactome
  │
  ├─ STRING_functional_enrichment [T2 - validated]
  │  - Returns ALL categories in one call
  │  - Filter by category: Process, Function, Component, KEGG, Reactome
  │  - Network-based enrichment
  │
  ├─ ReactomeAnalysis_pathway_enrichment [T1 - curated]
     - Reactome curated pathways
     - Cross-species projection
     - Detailed pathway hierarchy
  │
  └─ gProfiler_enrichment [T2 - validated]
     - GO BP/MF/CC, KEGG, Reactome (REAC), WikiPathways (WP), Human Phenotype (HP),
       CORUM, TF, miRNA — sources param, comma-separated
     - g:SCS multiple-testing correction (different algorithm from gseapy's BH on
       Enrichr's Fisher-exact; expect similar but not identical adjusted p-values)
     - Broadest organism support of the four (any g:Profiler-supported species,
       not just human/mouse) — useful when gseapy's organism coverage is thin
     - Real result verified live: TP53,BRCA1,EGFR,KRAS -> KEGG:05224 "Breast
       cancer" p=4.3e-6 as the top KEGG term (4/4 query genes, term_size=148)

Additional Context (Optional):
  ├─ GO_get_term_by_id, QuickGO_get_term_detail (GO term details)
  ├─ Reactome_get_pathway, Reactome_get_pathway_hierarchy (pathway context)
  ├─ WikiPathways_search, WikiPathways_get_pathway (community pathways)
  └─ STRING_ppi_enrichment (network topology analysis)

---

快速入门工作流

1. 立即创建报告文件；逐步填充内容。
2. 转换 ID：使用 MyGene_batch_query（字段：symbol,entrezgene,ensembl.gene），然后使用 STRING_map_identifiers 获取规范符号。自动检测：ENSG* = Ensembl，数字 = Entrez，否则 = Symbol。
3. 主要富集分析：ORA（基因列表）使用 gseapy.enrichr()，GSEA（带分数的排序列表）使用 gseapy.prerank()。使用 background=background_genes——如果实验有特定的表达基因集，不要使用默认的全基因组背景。
4. 交叉验证：运行 PANTHER_enrichment（参数：逗号分隔的 gene_list、annotation_dataset='GO:0008150'）和 ReactomeAnalysis_pathway_enrichment（参数：空格分隔的 identifiers）。STRING_functional_enrichment 会返回所有类别——按 category 字段筛选。
5. 报告：对每个显著术语，包含原始 p 值、校正后的 p 值、重叠比例和 inputGenes。注明共识术语（在 2 个或更多来源中显著的术语）。

参见：references/ 中的完整代码示例（ora_workflow.md、gsea_workflow.md、cross_validation.md）

---

证据分级

等级	符号	标准	示例
T1	[T1]	经整理/实验验证的富集结果	PANTHER、Reactome Analysis Service
T2	[T2]	计算得出的、经过充分验证的富集结果	gseapy ORA/GSEA、STRING 功能富集
T3	[T3]	基于文本挖掘/预测的富集结果	Enrichr 非人工整理的库
T4	[T4]	单一来源注释	QuickGO 中的单个基因 GO 注释

---

支持的生物物种

核心物种：human (9606)、mouse (10090)、rat (10116)、fly (7227)、worm (6239)、yeast (4932)。gseapy 对 human/mouse 提供完整支持；对其他物种的支持有限——进行非人类物种的富集分析时请使用 PANTHER 或 STRING。

参见：references/organism_support.md，了解特定物种支持的库

---

常见模式

模式 1：标准 DEG 富集（ORA）

Input: List of differentially expressed gene symbols
Flow: ID validation → gseapy ORA (GO + KEGG + Reactome) →
      PANTHER + STRING cross-validation → Report top enriched terms
Use: When you have unranked gene list from DESeq2/edgeR

模式 2：排序基因列表（GSEA）

Input: Gene-to-log2FC mapping from differential expression
Flow: Convert to ranked Series → gseapy GSEA (GO + KEGG + MSigDB) →
      Filter by FDR < 0.25 → Report NES and lead genes
Use: When you have fold-changes or other ranking metric

模式 3：定向富集问题

Input: Specific question about enrichment (e.g., "What is the adjusted p-val for neutrophil activation?")
Flow: Parse question for gene list and library → Run gseapy with exact library →
      Find specific term → Report exact p-value and adjusted p-value
Use: When answering targeted questions about specific terms

模式 3b：“富集程度最高的术语”——始终粘贴排名前 10 的列表

当问题询问“哪个 GO 术语／通路的富集显著性最高”时，多种方法（gseapy 与 enrichGO、简化结果与原始结果、不同的库版本、不同的 DEG 筛选条件）往往会得出 3–8 个合理的候选术语。已发表的答案可能与其中任何一个吻合，而且它们的 -log10(p) 往往相差不到 0.5，因此排序依据并不稳定。

最终答案正文中始终包含按 p.adjust 排名的前 10 个列表，并附上你的首选 #1 结果。gseapy_enrichment_runner.py 脚本已经会输出 # TOPN_BY_ADJ_PVALUE:——请原样粘贴。

## Primary answer: <term #1>

## Top 10 most-significantly-enriched terms (sensitivity)
1. <term> (adj p = ...)
2. <term> (adj p = ...)
...
10. <term> (adj p = ...)

这既是如实报告（排名靠前的结果存在不确定性），也能为 LLM 评分器提供完整上下文。如果已发表的答案位于第 2–10 名，评分器就能核实 Agent 的推理是否得出了该结果。

模式 4：多物种富集

Input: Gene list from mouse experiment
Flow: Use organism='mouse' for gseapy → organism=10090 for PANTHER/STRING →
      projection=True for Reactome human pathway mapping
Use: When working with non-human organisms

参见：references/common_patterns.md，了解更多示例

---

故障排除

“未发现显著富集”：

• 确认基因符号有效（STRING_map_identifiers）
• 尝试不同的库版本（2021、2023 或 2025）
• 尝试放宽显著性阈值，或改用 GSEA

“未找到基因”错误：

• 检查 ID 类型，并使用 MyGene_batch_query 进行转换
• 从 Ensembl ID 中移除版本后缀（ENSG00000141510.16 → ENSG00000141510）

“STRING 返回所有类别”：

• 这是预期行为；收到结果后，按 d['category'] == 'Process' 进行筛选

参见：references/troubleshooting.md，获取完整指南

---

工具参考

主要富集工具

工具	输入	输出	用途
gseapy.enrichr()	gene_list, gene_sets, organism	.results DataFrame	使用 225+ 个库进行 ORA
gseapy.prerank()	rnk（已排序的 Series）、gene_sets	.res2d DataFrame	GSEA 分析

交叉验证工具

工具	关键参数	证据等级
PANTHER_enrichment	gene_list（逗号分隔）、organism、annotation_dataset	[T1]
STRING_functional_enrichment	protein_ids、species	[T2]
ReactomeAnalysis_pathway_enrichment	identifiers（空格分隔）、page_size	[T1]

ID 转换工具

工具	输入	输出
MyGene_batch_query	gene_ids、fields	Symbol、Entrez、Ensembl 映射
STRING_map_identifiers	protein_ids、species	首选名称、STRING ID
gProfiler_convert_ids	gene_list（逗号分隔）、target_namespace、organism	跨命名空间转换（ENSG/ENST/ENSP/UNIPROTSWISSPROT/ENTREZGENE_ACC/WIKIGENE_ACC/REFSEQ_*）——当目标命名空间不在 MyGene_batch_query 的 fields 列表直接覆盖范围内时，此工具很有用

跨物种和变异到基因工具（g:Profiler）

工具	输入	输出	备注
gProfiler_find_orthologs	gene_list、source_organism、target_organism	每个输入基因对应的同源基因名称和 Ensembl ID	已通过实时验证：人类→小鼠的解析可靠（BRCA1→Brca1/ENSMUSG00000017146，TP53→Trp53/ENSMUSG00000059552）；更远的物种组合（人类→斑马鱼）对 BRCA1 返回了 "name": "N/A"——应将 N/A 条目标注为“此物种组合未找到可信的同源基因”，而不是工具错误
gProfiler_annotate_snps	snp_list（逗号分隔的 rsID，最多约 200 个）、organism	基因组坐标、映射基因、变异后果	将 GWAS／变异命中列表转换为基因级富集分析输入（SNP → 基因 → gProfiler_enrichment 或 gseapy）；已通过实时验证：rs429358 → APOE（chr19:44908684，missense_variant），与 ToolUniverse（tooluniverse-variant-analysis）中其他地方使用的该 rsID 已知坐标一致

参见：references/tool_parameters.md，获取完整的参数文档

---

样本级和替代评分方法

上述工具回答的都是“这个基因列表／排序中哪些通路富集？”下面这六种纯计算工具回答的是不同的问题——使用前请先确认每种工具实际需要的输入，因为它们虽然都与“富集”相关，但不能互换：

工具	输入	输出	回答的问题
GSEA_prerank	一个排序后的 {gene: score} 列表 + 基因集	每个基因集的 ES、NES、置换 p 值、前沿基因	与 gseapy.prerank 回答同一个问题（某个基因集是否在该排序的顶部／底部富集），但使用纯 Python 实现——无需 R，也不内置 MSigDB，因此需要自行提供基因集
GSVA_score	一个表达矩阵（基因 x 样本）+ 基因集	每个（基因集，样本）对应一个有符号评分	每个样本的通路活性——“相对于整个队列，这条通路在样本 3 中是否上调？”，而非“这条通路整体是否富集？”
ssGSEA_score	与 GSVA 相同的矩阵输入	每个（基因集，样本）对应一个幅度无界的评分	与 GSVA 回答相同的样本级问题，但计算方法不同——在相同输入上进行了实时验证：GSVA 得到有界且以零为中心的评分（肿瘤为 0.5／正常为 -1.0），而 ssGSEA 对同一基因集得到的评分幅度大得多（肿瘤为 6.03／正常为 -5.86）。不要直接比较 GSVA 和 ssGSEA 的评分；请选择一种方法，并在整个分析中保持一致
Activity_infer_ulm	每个基因的统计量 + 调控网络（[{source, target, weight}]，例如 DoRothEA／PROGENy 边列表）	每个来源（TF／通路）的活性 t 值 + p 值	TF／通路活性推断——必须提供网络，而不仅仅是基因集；如果没有网络，可通过 OmniPath_get_dorothea_regulon 获取
Coexpression_modules	仅表达矩阵（不需要基因集）	发现的基因模块 + 每个模块的特征基因（第一主成分汇总谱）	哪些基因在不同样本中协同变化——一种类似 WGCNA 的发现工具，而非针对已知通路进行检验
DeepGO_predict_function	单条蛋白质序列（完全不是基因列表）	每种蛋白质预测的 GO 术语（BP／MF／CC）及置信度评分	对一个尚未表征／新颖序列进行功能预测——适用于已有序列但尚无注释的情况，而非已有基因列表待检验的情况

这六种工具均为纯计算工具（不调用外部 API，也不需要 R），并已通过实时验证：

• GSEA_prerank：TOP_SET（排序靠前的基因）→ ES=1.0、NES=1.77、p=0.002；BOTTOM_SET → ES=-1.0、NES=-1.93、p=0.004——对于清晰的合成数据分组，符号和幅度符合预期。
• Activity_infer_ulm：TF_A（靶基因集中在排序靠前的基因中）→ 活性=+5.17、p=2.4e-7；TF_B（靶基因集中在排序靠后的基因中）→ 活性=-5.56、p=2.7e-8。
• Coexpression_modules：一个包含 8 个基因、6 个样本且有两个明显相关区块的合成矩阵 → 正确识别出恰好 2 个模块，每个包含 4 个基因，没有未分配基因。
• DeepGO_predict_function：一条 92-aa 测试序列 → 预测出真实 GO 术语（例如 GO:0005737 “细胞质”，评分 0.80；GO:0005515 “蛋白质结合”，评分 0.73）——这些是置信度评分，不是 p 值；threshold（默认值为 0.3）用于设置报告结果的最低评分。

参见：references/tool_parameters.md，了解这六种工具的完整参数文档。

---

详细文档

所有详细示例、代码块和高级主题均已移至 references/：

• references/ora_workflow.md - 包含所有数据库的完整 ORA 示例
• references/gsea_workflow.md - 包含排序列表的完整 GSEA 工作流
• references/enrichr_guide.md - 所有 225+ 个 Enrichr 库及其用法
• references/cross_validation.md - 多来源验证策略
• references/id_conversion.md - 基因 ID 消歧与转换
• references/tool_parameters.md - 完整的工具参数参考
• references/organism_support.md - 特定生物的配置
• references/common_patterns.md - 详细的用例示例
• references/troubleshooting.md - 完整的故障排查指南
• references/multiple_testing.md - 校正方法（BH、Bonferroni、BY）
• references/report_template.md - 标准报告格式

辅助脚本（主要 — 完整用法请参阅文件顶部）：

• scripts/gseapy_enrichment_runner.py — 用于 gseapy enrichr / prerank，支持平局破除和候选排名报告
• scripts/enrichgo_runner.py — clusterProfiler enrichGO + simplify（并排展示原始和简化后的数据框）
• scripts/condition_enrichment_screen.py — 按条件进行富集筛选，支持关键词过滤和百分比汇总
• scripts/format_enrichment_output.py — 用于 ORA/GSEA 结果的 Markdown 格式化工具

---

分析约定

工具选择：R clusterProfiler 与 gseapy

• 当数据集文件夹包含使用 enrichGO/simplify 的 analysis.R / find_*.R 脚本时，优先使用 R clusterProfiler。使用 scripts/enrichgo_runner.py（参阅文件顶部）。
• 当问题明确提到 gseapy / Enrichr 库时，gseapy 是合适的工具。使用 scripts/gseapy_enrichment_runner.py。
• gseapy 无法忠实复现 enrichGO + simplify(cutoff=0.7) — simplify 之后，多重检验的分母会发生变化。

必需的 R 包：clusterProfiler、org.Hs.eg.db、enrichplot、DESeq2。通过以下方式安装：

Rscript skills/evals/install_r_packages.R

Simplify（cutoff=0.7）会删除冗余术语 — 并改变保留术语的 p.adjust

clusterProfiler::simplify(ego, cutoff=0.7, by="p.adjust", select_fun=min) 会删除冗余的 GO 术语。重要：某个术语在简化后保留下来时，它在简化表中的 p.adjust 与原始 as.data.frame(ego) 表中的值不同，因为多重检验校正的分母会发生变化（参与检验的术语更少 → 保留术语的调整后 p 值更小）。当问题提到“简化后的结果”“简化后的 GO 富集”或“simplify 之后”时，应从简化后的数据框中读取 p.adjust（as.data.frame(simplify(ego, cutoff=0.7)) 或被赋值的相应对象），而不是从原始 ego 中读取。同一 GO 术语在原始 enrichGO 结果中的 p.adjust 与简化后的 p.adjust 不相等。

如果问题询问特定术语（例如“中性粒细胞活化”），而该术语不在简化表中，则说明它已被合并到显著性更高的父级/同级术语中 — 不要默认选择视觉上相似的术语。检查 as.data.frame(ego)（simplify 之前的原始富集结果），以确认哪些术语被合并。

背景基因集很重要

某些数据集提供了明确的背景基因集（例如，bg_ensembl.txt、gencode.v31.primary_assembly.genes.csv）。将其用作 enrichGO 的 universe= — 不要用经过 DEG 检验的基因替代背景基因集。不同的背景基因集会显著影响调整后 p 值。

预先生成的结果 CSV 与已执行的笔记本

数据集文件夹中可能包含预先计算的富集结果 CSV，以及已执行的笔记本。仅有 CSV 并不可靠——它们可能使用了与问题要求不同的参数（不同的 DEG 截止值、不同的背景集、不同的 simplify 截止值）生成。请将普通 CSV 仅作为参考。

已执行的笔记本则不同：如果 *_executed.ipynb 中的单元格显示的 DEG、背景集和 simplify_cutoff 参数与问题一致，那么它就是已发布的权威来源——请读取其单元格输出（遵循 router skill 中的 RULE ZERO）。如果不存在已执行的笔记本，请从头运行完整流程：DESeq2 → DEG 列表 → enrichGO → simplify → 提取 p 值。请根据预先存在的 .R 脚本确定参数选择，不要使用其缓存输出。

---

资源

网络层面分析：tooluniverse-network-pharmacology 疾病特征分析：tooluniverse-multiomic-disease-characterization 空间组学：tooluniverse-spatial-omics-analysis 蛋白质相互作用：tooluniverse-protein-interactions

gseapy 文档：https://gseapy.readthedocs.io/ PANTHER API：http://pantherdb.org/services/oai/pantherdb/ STRING API：https://string-db.org/cgi/help?sessionId=&subpage=api Reactome 分析：https://reactome.org/AnalysisService/