gsea-enrichment-analysis

GSEA 和通路富集分析

概述

本技能介绍 OmicVerse 中的基因集富集分析（GSEA）和通路富集工作流，并提供关键指导，帮助正确使用数据格式和 API，避免常见错误。

关键 API 参考——基因集格式

重要：使用字典格式，而不是文件路径！

ov.bulk.geneset_enrichment() 函数需要的是基因集的字典，而不是文件路径字符串。必须先使用 ov.utils.geneset_prepare() 加载基因集文件。

正确用法：

# Step 1: Download pathway database (if not already available)
ov.utils.download_pathway_database()

# Step 2: Load geneset file into dictionary format - REQUIRED!
pathways_dict = ov.utils.geneset_prepare(
    'genesets/GO_Biological_Process_2021.txt',  # or .gmt file
    organism='Human'  # or 'Mouse'
)

# Step 3: Now run enrichment with the DICTIONARY
enr = ov.bulk.geneset_enrichment(
    gene_list=deg_genes,
    pathways_dict=pathways_dict,  # Pass the DICTIONARY, not file path!
    pvalue_type='auto',
    organism='Human'
)

错误用法——请勿使用：

# WRONG! Don't pass file path directly to geneset_enrichment!
# enr = ov.bulk.geneset_enrichment(
#     gene_list=deg_genes,
#     pathways_dict='genesets/GO_Biological_Process_2021.gmt'  # ERROR! String path doesn't work!
# )

# WRONG! geneset_enrichment expects dict, not file path
# enr = ov.bulk.geneset_enrichment(
#     gene_list=deg_genes,
#     pathways_dict='GO_Biological_Process_2021'  # ERROR!
# )

文件格式支持

文件扩展名	加载方法	说明
.txt	ov.utils.geneset_prepare()	OmicVerse 格式
.gmt	ov.utils.geneset_prepare()	标准 GMT 格式
.json	json.load() then convert	需要自定义处理

完整的富集分析工作流

import omicverse as ov

# 1. Setup
ov.plot_set()

# 2. Ensure pathway database is available
ov.utils.download_pathway_database()

# 3. Load gene sets - ALWAYS use geneset_prepare first!
go_bp = ov.utils.geneset_prepare('genesets/GO_Biological_Process_2021.txt', organism='Human')
go_mf = ov.utils.geneset_prepare('genesets/GO_Molecular_Function_2021.txt', organism='Human')
kegg = ov.utils.geneset_prepare('genesets/KEGG_2021_Human.txt', organism='Human')

# 4. Prepare gene list (e.g., from DEG analysis)
# Assuming dds is a pyDEG object with results
deg_genes = dds.result.loc[dds.result['sig'] != 'normal'].index.tolist()

# 5. Run enrichment with dictionary
enr_go_bp = ov.bulk.geneset_enrichment(
    gene_list=deg_genes,
    pathways_dict=go_bp,  # Dictionary, NOT file path!
    pvalue_type='auto',
    organism='Human'
)

# 6. Visualize results
ov.bulk.geneset_plot(enr_go_bp, figsize=(6, 8), num=10)

# 7. For multiple databases, combine into dict
enr_dict = {
    'GO_BP': enr_go_bp,
    'GO_MF': enr_go_mf,
    'KEGG': enr_kegg
}
colors_dict = {
    'GO_BP': '#1f77b4',
    'GO_MF': '#ff7f0e',
    'KEGG': '#2ca02c'
}
ov.bulk.geneset_plot_multi(enr_dict, colors_dict, num=5)

常见错误和解决方案

错误：“FileNotFoundError”或“pathways_dict is not a dict”

原因：传递给 geneset_enrichment() 的是文件路径字符串，而不是字典 解决方案：先使用 ov.utils.geneset_prepare() 加载，再传入返回的字典

错误：“Missing file 'genesets/GO_Biological_Process_2021.gmt'”

原因：尚未下载通路数据库 解决方案：先运行 ov.utils.download_pathway_database()

错误：“No enriched pathways found”

原因：基因列表与通路基因没有重叠，或者物种不匹配 解决方案：

• 确认基因符号匹配（人类与小鼠的大小写规则不同）
• 检查 organism 参数是否与数据匹配
• 确保基因列表包含足够多的基因（建议超过 10 个）

可用的通路数据库

运行 ov.utils.download_pathway_database() 后可用：

• GO_Biological_Process_2021.txt
• GO_Molecular_Function_2021.txt
• GO_Cellular_Component_2021.txt
• KEGG_2021_Human.txt
• KEGG_2021_Mouse.txt
• Reactome_2022.txt
• WikiPathway_2023_Human.txt
• 以及更多……

最佳实践

1. 始终先加载基因集：切勿将文件路径直接传递给 geneset_enrichment()
2. 检查基因格式：确保基因符号匹配（人类使用大写，小鼠使用首字母大写）
3. 只需下载一次：在每个环境中运行一次 download_pathway_database()
4. 指定物种：始终设置 organism='Human' 或 organism='Mouse'
5. 使用背景基因：提供 background 参数，以获得更准确的结果

示例

• “使用正确的 geneset_prepare 工作流，对我的 DEG 结果进行 GO 富集分析”
• “使用正确的字典格式，对上调基因进行 KEGG 通路分析”
• “使用 geneset_plot_multi 比较 GO BP、MF 和 KEGG 富集结果”

参考资料

• 教程笔记本：t_deg.ipynb（富集分析部分）
• 通路下载：ov.utils.download_pathway_database()
• 快速参考：reference.md