alterlab-gwas

GWAS Catalog 数据库

概述

GWAS Catalog 是由 NHGRI 和 EBI 维护的已发表全基因组关联研究精选存储库。它包含数千篇 GWAS 出版物中的 SNP-性状关联数据，包括遗传变异、相关性状和疾病、p 值、效应量，以及许多研究的完整汇总统计数据。

脚本

scripts/query_gwas.py — 查询 GWAS Catalog REST API（仅使用标准库，将 JSON 输出到 stdout）：

python scripts/query_gwas.py variant rs7903146                 # associations for a SNP (strongest first)
python scripts/query_gwas.py trait MONDO_0005148 --size 100    # associations for a trait
python scripts/query_gwas.py gene TCF7L2                       # associations mapped to a gene
python scripts/query_gwas.py find-trait "type 2 diabetes"      # free text -> efo_id
python scripts/query_gwas.py study GCST001795                  # study metadata (+ summary-stats FTP link)

何时使用此技能

在以下情况下使用此技能：

• 遗传变异关联 — 与疾病或性状相关的 SNP
• SNP 查询 — 特定变异（rs ID）的信息
• 性状／疾病搜索 — 表型的遗传关联
• 基因关联 — 特定基因内或附近的变异
• GWAS 汇总统计数据 — 完整的全基因组关联数据
• 研究元数据 — 出版物和队列信息
• 群体遗传学 — 特定祖源的关联
• 多基因风险评分 — 用于风险预测模型的变异
• 功能基因组学／系统综述 — 变异效应、文献综合

不适用的情况

场景	改用
靶点－疾病关联评分、药物靶点的 L2G／共定位证据	alterlab-opentargets
变异的临床致病性（ACMG/AMP、评审星级）	alterlab-clinvar
群体等位基因频率或基因约束	alterlab-gnomad
变异调控的基因／组织（eQTL/sQTL）	alterlab-gtex
变异后果（VEP）、坐标、基因模型	alterlab-ensembl

数据模型

四种核心实体，各自都有规范标识符：

• 研究 → GCST 登录号（例如，GCST001234）
• 关联 → 带有 p 值的 SNP-性状关联（全基因组显著：p ≤ 5×10⁻⁸）
• 变异 → rs 编号（例如，rs7903146）
• 性状 → efo_id 中的本体短格式名称（例如，MONDO_0005148 = 2 型糖尿病）；基因使用 HGNC 符号（例如，TCF7L2）

性状 ID 注意事项（已于 2026-09 验证）： 许多性状已重新映射为 MONDO／当前 EFO 短格式名称，过时的 ID 会返回空页面而不是报错——associations?efo_id=EFO_0001360（旧版 2 型糖尿病）返回 0 行，而 efo_id=MONDO_0005148 返回数千行。请先使用 GET /v2/efo-traits?efo_trait=type 2 diabetes 解析自由文本，并使用返回的 efo_id。较早的论文和工作流仍可能引用旧版 EFO ID。

API

• GWAS Catalog REST API v2（于 2025 年 8 月发布）：https://www.ebi.ac.uk/gwas/rest/api/v2 — 精选的顶级关联、研究、SNP、性状、基因和出版物。免费，无需密钥；限流为每秒 15 次请求；默认分页大小为 20（请将 size 保持在 ≤ 200——更大的分页会超时）。交互式参考文档：https://www.ebi.ac.uk/gwas/rest/api/v2/docs
• 旧版 v1（/gwas/rest/api/singleNucleotidePolymorphisms/...、/efoTraits/...、驼峰式字段）已弃用，原计划于 2026 年 5 月前停用；它可能仍可响应，但不要基于它编写新代码。
• Summary Statistics API（/gwas/summary-statistics/api）已停用（HTTP 410）；完整汇总统计数据通过 FTP 站点提供（见工作流第 6 步）。EBI 表示替代 API“即将推出”。

v2 核心端点：/v2/associations（筛选项 rs_id、efo_id、efo_trait、mapped_gene、accession_id、pubmed_id；sort=p_value&direction=asc）、/v2/studies 和 /v2/studies/{accession_id}、/v2/single-nucleotide-polymorphisms（按 rs_id、mapped_gene，或 chromosome + bp_start／bp_end 查询）、/v2/efo-traits、/v2/genes/{gene_name}。响应采用 HAL+JSON，字段使用蛇形命名法：结果位于 _embedded.<resource> 下（associations、studies、snps、efo_traits），分页信息位于 page 下（totalElements、totalPages、number），后续页面位于 _links.next。

核心工作流

1. 识别实体 — 获取 efo_id（性状；通过 /v2/efo-traits?efo_trait= 将自由文本解析为对应实体）、rs ID（变异）、GCST（研究）或 HGNC 符号（基因）。
2. 查询匹配的端点 — 性状/变异/研究/基因/区域；通过 page/size 遍历分页，或跟随 _links.next。
3. 筛选 — 按 p 值（≤ 5×10⁻⁸ 表示具有全基因组显著性）、祖源、样本量、发现/重复验证状态筛选。
4. 提取 — rs ID 和效应等位基因（snp_allele[]）、效应大小（or_per_copy_num 或 beta 文本）、p 值。对于非常强的信号，p_value 会下溢为 0.0（2 型糖尿病中的 rs7903146 达到 3×10⁻¹³¹⁵），因此应使用 pvalue_mantissa / pvalue_exponent 排序和报告。
5. 交叉引用 — Ensembl（后果）、gnomAD（频率）、Open Targets、PGS Catalog。
6. 进行全基因组分析 — 使用 /v2/studies?efo_id=...&full_pvalue_set=true 查找研究；每项研究的 full_summary_stats 字段提供其 FTP 目录。协调后的文件位于 https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST<range>/<GCST>/harmonised/<GCST>.h.tsv.gz（GWAS-SSF 列，已建立索引的 .tbi），因此可以使用 tabix <url> 10:112900000-113200000 远程提取某个区域，而无需下载整个文件。不要为此抓取关联端点——这些端点仅包含经过整理的主要命中结果。

路由指南

• 编写 API 调用 / 需要可复制粘贴的代码（端点、四个完整示例、汇总统计数据访问、交叉引用、完整分页 Python 辅助函数）→ references/query_examples.md。
• 执行多步骤任务（以疾病、变异、基因为中心的查询、系统综述、汇总统计分析）或网页界面搜索语法 → references/query_workflows.md。
• 需要响应字段名称、分页详情或最佳实践 / 数据质量指南 → references/data_fields_and_best_practices.md。
• 深入了解端点规范、所有查询参数、错误处理、高级筛选 → references/api_reference.md。

参考索引

• references/query_examples.md — REST 端点代码、四个典型查询示例（疾病、变异、汇总统计数据、染色体区域）、汇总统计数据访问、交叉引用，以及返回 DataFrame 的完整分页 Python 集成示例。
• references/query_workflows.md — 五种分步查询工作流（疾病、变异、基因、系统综述、汇总统计数据）以及网页界面搜索模式。
• references/data_fields_and_best_practices.md — 关联/研究响应字段、分页、查询和解读最佳实践、速率限制伦理以及数据质量注意事项。
• references/api_reference.md — 全面的端点规范、查询参数/筛选器、响应格式、错误处理以及与外部数据库的集成。

引用和资源

使用 GWAS Catalog 数据时，请引用：

• Sollis E, et al. (2023) The NHGRI-EBI GWAS Catalog: knowledgebase and deposition resource. Nucleic Acids Research 51:D977-D985. PMID: 36350656. DOI: 10.1093/nar/gkac1010

• 如有版本信息，请注明访问日期和版本；讨论具体发现时，请引用原始研究。

• 网站：https://www.ebi.ac.uk/gwas/

• 文档：https://www.ebi.ac.uk/gwas/docs

• API v2 文档：https://www.ebi.ac.uk/gwas/rest/api/v2/docs (OpenAPI：https://www.ebi.ac.uk/gwas/rest/api/v2/rest-api-doc.yaml)

• 汇总统计数据访问：https://www.ebi.ac.uk/gwas/docs/methods/summary-statistics

• FTP 站点：https://ftp.ebi.ac.uk/pub/databases/gwas/

• 培训材料：https://github.com/EBISPOT/GWAS_Catalog-workshop（Jupyter 笔记本、Colab）

• PGS Catalog（多基因评分）：https://www.pgscatalog.org/

• 帮助与支持：[email protected]