alterlab-gnomad

gnomAD 数据库

概述

基因组聚合数据库（gnomAD）是目前公开可用的最大人类遗传变异集合，汇总了大型测序项目的数据。gnomAD v4 包含来自 730,947 名个体的外显子组序列，以及来自 76,215 名不同祖源个体的基因组序列。当前版本为 v4.1.1（2026 年 3 月 30 日），更新了基因约束指标（贝叶斯 LOEUF、chrX/chrY 覆盖度）和 LOFTEE 标记；API 数据集 ID 仍为 gnomad_r4。它提供群体等位基因频率、变异后果注释和基因层面的约束指标，这些信息对于解读遗传变异的临床意义至关重要。

关键资源：

• gnomAD 浏览器：https://gnomad.broadinstitute.org/
• GraphQL API：https://gnomad.broadinstitute.org/api
• 数据下载：https://gnomad.broadinstitute.org/downloads
• 文档：https://gnomad.broadinstitute.org/help

何时使用此技能

以下情况可使用 gnomAD：

• 查询变异频率：检查某个变异在人群中是罕见、常见还是不存在
• 致病性评估：罕见变异（MAF < 1%）可能导致疾病；gnomAD 可帮助筛除常见的良性变异
• 功能丧失不耐受性：使用 pLI 和 LOEUF 分数评估基因对蛋白质截短变异的耐受程度
• 按人群分层的频率：比较不同祖源人群的等位基因频率（非洲／非裔美国人、混合美洲人、阿什肯纳兹犹太人、东亚人、芬兰人、中东人、非芬兰欧洲人、南亚人）
• ClinVar／ACMG 变异分类：gnomAD 频率数据可用于变异分类的 BA1／BS1 证据代码
• 约束分析：识别错义变异或功能丧失变异数量减少的基因（z 分数、pLI、LOEUF）

不适用的情况

场景	改用
提交变异的临床意义／ACMG 分类	alterlab-clinvar
肿瘤中的体细胞突变频率	alterlab-cbioportal
变异后果预测（VEP）或基因／转录本模型	alterlab-ensembl
某种性状或变异的 GWAS 关联	alterlab-gwas
某个基因的组织表达或 eQTL	alterlab-gtex

核心功能

1. gnomAD GraphQL API

gnomAD 使用可通过 https://gnomad.broadinstitute.org/api 访问的 GraphQL API。大多数查询按基因或特定基因组位置获取变异。

可用数据集（DatasetId 枚举的取值）：

• gnomad_r4 — gnomAD v4（当前为 v4.1.1），GRCh38（推荐的默认值；每个变异均返回 exome 和 genome 两个数据块——没有单独的 gnomad_r4_genomes ID）
• gnomad_r4_non_ukb — v4，不包含 UK Biobank 样本
• gnomad_r3 — gnomAD v3 基因组，GRCh38（子集：gnomad_r3_non_cancer、_non_neuro、_non_topmed、_non_v2、_controls_and_biobanks）
• gnomad_r2_1 — gnomAD v2，GRCh37（仅在需要兼容 GRCh37 时使用；子集：_controls、_non_neuro、_non_cancer、_non_topmed）
• exac — 旧版 ExAC

（已于 2026-09-23 通过内省 DatasetId 枚举进行验证；请使用 { __type(name: "DatasetId") { enumValues { name } } } 重新检查。）

结构变异和拷贝数变异使用独立的枚举：structural_variants(dataset: gnomad_sv_r4)（v2 结构变异：gnomad_sv_r2_1）和 copy_number_variants(dataset: gnomad_cnv_r4)。

参考基因组：

• GRCh38 — v3/v4 的默认版本
• GRCh37 — 用于 v2

2. 按基因查询变异

import requests

def query_gnomad_gene(gene_symbol, dataset="gnomad_r4", reference_genome="GRCh38"):
    """Fetch variants in a gene from gnomAD."""
    url = "https://gnomad.broadinstitute.org/api"

    query = """
    query GeneVariants($gene_symbol: String!, $dataset: DatasetId!, $reference_genome: ReferenceGenomeId!) {
      gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
        gene_id
        symbol
        variants(dataset: $dataset) {
          variant_id
          pos
          ref
          alt
          consequence
          genome {
            af
            ac
            an
            ac_hom
            populations {
              id
              ac
              an
              ac_hom
            }
          }
          exome {
            af
            ac
            an
            ac_hom
          }
          lof
          lof_flags
          lof_filter
        }
      }
    }
    """

    variables = {
        "gene_symbol": gene_symbol,
        "dataset": dataset,
        "reference_genome": reference_genome
    }

    response = requests.post(url, json={"query": query, "variables": variables})
    return response.json()

# Example
result = query_gnomad_gene("BRCA1")
gene_data = result["data"]["gene"]
variants = gene_data["variants"]

# Filter to rare protein-truncating variants.
# Note the parentheses: without them `and` binds tighter than `or`, so the AF
# filter would silently apply only to the consequence branch.
# Per-population frequency is af = ac / an (the populations entries expose
# ac/an, not af). Genome `af` here is absent for variants seen only in exomes,
# so fall back to exome af.
def variant_af(v):
    g = (v.get("genome") or {}).get("af")
    return g if g is not None else (v.get("exome") or {}).get("af", 1)

rare_ptvs = [
    v for v in variants
    if (v.get("lof") == "HC" or v.get("consequence") in ["stop_gained", "frameshift_variant"])
    and variant_af(v) < 0.001
]
print(f"Found {len(rare_ptvs)} rare PTVs in {gene_data['symbol']}")

3. 查询特定变异

import requests

def query_gnomad_variant(variant_id, dataset="gnomad_r4"):
    """Fetch details for a specific variant (e.g., '1-55516888-G-GA')."""
    url = "https://gnomad.broadinstitute.org/api"

    # On a single variant, consequence/lof are NOT top-level fields — they
    # live under transcript_consequences[] (per transcript). Populations
    # expose ac/an only; compute per-population af = ac / an.
    query = """
    query VariantDetails($variantId: String!, $dataset: DatasetId!) {
      variant(variantId: $variantId, dataset: $dataset) {
        variant_id
        chrom
        pos
        ref
        alt
        rsids
        genome {
          af
          ac
          an
          ac_hom
          populations { id ac an ac_hom }
        }
        exome {
          af
          ac
          an
          ac_hom
          populations { id ac an ac_hom }
        }
        transcript_consequences {
          gene_symbol
          major_consequence
          lof
          lof_flags
          is_canonical
        }
        in_silico_predictors {
          id
          value
          flags
        }
      }
    }
    """

    response = requests.post(
        url,
        json={"query": query, "variables": {"variantId": variant_id, "dataset": dataset}}
    )
    return response.json()

# Example: query a specific variant
result = query_gnomad_variant("17-43094692-G-C")  # BRCA1 missense, rs80357199
variant = result["data"]["variant"]

if variant:
    genome_af = (variant.get("genome") or {}).get("af", "N/A")
    exome_af = (variant.get("exome") or {}).get("af", "N/A")
    # Pick the consequence from the canonical transcript when present.
    tcs = variant.get("transcript_consequences") or []
    canonical = next((t for t in tcs if t.get("is_canonical")), tcs[0] if tcs else {})
    print(f"Variant: {variant['variant_id']}")
    print(f"  Consequence: {canonical.get('major_consequence')}")
    print(f"  Genome AF: {genome_af}")
    print(f"  Exome AF: {exome_af}")
    print(f"  LoF: {canonical.get('lof')}")

4. 基因约束评分

gnomAD 约束评分用于评估基因对变异的耐受程度与预期相比如何：

import requests

def query_gnomad_constraint(gene_symbol, reference_genome="GRCh38"):
    """Fetch constraint scores for a gene."""
    url = "https://gnomad.broadinstitute.org/api"

    query = """
    query GeneConstraint($gene_symbol: String!, $reference_genome: ReferenceGenomeId!) {
      gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
        gene_id
        symbol
        gnomad_constraint {
          exp_lof
          exp_mis
          exp_syn
          obs_lof
          obs_mis
          obs_syn
          oe_lof
          oe_mis
          oe_syn
          oe_lof_lower
          oe_lof_upper
          lof_z
          mis_z
          syn_z
          pLI
        }
      }
    }
    """

    response = requests.post(
        url,
        json={"query": query, "variables": {"gene_symbol": gene_symbol, "reference_genome": reference_genome}}
    )
    return response.json()

# Example
result = query_gnomad_constraint("KCNQ2")
gene = result["data"]["gene"]
constraint = gene["gnomad_constraint"]

print(f"Gene: {gene['symbol']}")
print(f"  pLI:   {constraint['pLI']:.3f}  (>0.9 = LoF intolerant)")
print(f"  LOEUF: {constraint['oe_lof_upper']:.3f}  (<0.45 = constrained, v4.1.1 guidance)")
print(f"  Obs/Exp LoF: {constraint['oe_lof']:.3f}")
print(f"  Missense Z:  {constraint['mis_z']:.3f}")

约束评分解读：

评分	范围	含义
pLI	0–1	LoF 不耐受的概率；>0.9 表示高度不耐受
LOEUF	0–∞	LoF 观察值/预期值的上限；在 v4.1.1 中 <0.45 表示存在约束（旧版 <0.35 的阈值基于 v2 校准，对 v4 来说过于严格）
oe_lof	0–∞	LoF 变异的观察值/预期值比率
mis_z	−∞ 至 ∞	错义变异约束 z 分数；>3.09 表示存在约束
syn_z	−∞ 至 ∞	同义变异 z 分数（对照；应接近 0）

5. 群体频率分析

import requests
import pandas as pd

def get_population_frequencies(variant_id, dataset="gnomad_r4"):
    """Extract per-population allele frequencies for a variant."""
    url = "https://gnomad.broadinstitute.org/api"

    query = """
    query PopFreqs($variantId: String!, $dataset: DatasetId!) {
      variant(variantId: $variantId, dataset: $dataset) {
        variant_id
        genome {
          populations {
            id
            ac
            an
            ac_hom
          }
        }
      }
    }
    """

    response = requests.post(
        url,
        json={"query": query, "variables": {"variantId": variant_id, "dataset": dataset}}
    )
    data = response.json()
    populations = data["data"]["variant"]["genome"]["populations"]

    df = pd.DataFrame(populations)
    df = df[df["an"] > 0].copy()
    df["af"] = df["ac"] / df["an"]
    df = df.sort_values("af", ascending=False)
    return df

# Population IDs in gnomAD v4:
# afr = African/African American
# ami = Amish
# amr = Admixed American
# asj = Ashkenazi Jewish
# eas = East Asian
# fin = Finnish
# mid = Middle Eastern
# nfe = Non-Finnish European
# sas = South Asian
# remaining = Other

6. 结构变异（gnomAD-SV）

gnomAD 还包含结构变异数据集：

import requests

def query_gnomad_sv(gene_symbol):
    """Query structural variants overlapping a gene."""
    url = "https://gnomad.broadinstitute.org/api"

    # structural_variants requires a dataset argument (gnomad_sv_r4).
    query = """
    query SVsByGene($gene_symbol: String!, $dataset: StructuralVariantDatasetId!) {
      gene(gene_symbol: $gene_symbol, reference_genome: GRCh38) {
        structural_variants(dataset: $dataset) {
          variant_id
          type
          chrom
          pos
          end
          af
          ac
          an
        }
      }
    }
    """

    response = requests.post(
        url,
        json={"query": query, "variables": {"gene_symbol": gene_symbol, "dataset": "gnomad_sv_r4"}}
    )
    return response.json()

查询工作流

工作流 1：变异致病性评估

1. 检查群体频率 — 该变异是否足够罕见，可能具有致病性？

   • 隐性疾病使用 gnomAD AF < 1%，显性疾病使用 < 0.1%
   • 检查祖源特异性频率（总体罕见的变异在某个群体中可能很常见）

2. 评估功能影响 — LoF 变异的先验概率最高

   • 检查 lof 字段：HC = 高置信度 LoF，LC = 低置信度
   • 检查 lof_flags，查看是否存在 "NAGNAG_SITE"、"PHYLOCSF_WEAK" 等问题

3. 应用 ACMG 标准：

   • BA1：AF > 5% → 良性独立证据
   • BS1：AF > 疾病患病率阈值 → 良性支持证据
   • PM2：在 gnomAD 中不存在或极其罕见 → 中等致病证据

工作流 2：罕见病基因优先级排序

1. 查询候选基因的约束评分
2. 筛选 LOEUF < 0.45 的基因（gnomAD v4.1.1 建议）——若必须与较早的文献保持一致，则使用 pLI > 0.9
3. 与该基因中已观察到的 LoF 变异交叉比对
4. 综合参考 ClinVar 和疾病数据库

工作流 3：群体遗传学研究

1. 从 GWAS 或临床数据中确定感兴趣的变异
2. 查询各群体的频率
3. 比较不同祖源之间的频率差异
4. 检验该变异是否在特定创始人群体中富集

最佳实践

• 使用 gnomAD v4 (gnomad_r4) 获取最新数据；仅在需要兼容 GRCh37 时使用 v2 (gnomad_r2_1)
• 处理 null 响应：gnomAD 中未观察到某个变异，并不代表该变异一定具有致病性——缺失信息本身具有参考价值
• 区分外显子组与基因组数据：基因组数据的覆盖更均匀；外显子组数据量更大，但可能存在覆盖缺口
• 限制 GraphQL 查询频率：请求之间添加延迟；尽可能批量查询
• 纯合计数（ac_hom）与隐性疾病分析相关
• 基因约束分析优先使用 LOEUF，而非 pLI（对样本量不那么敏感）；v4.1.1 采用贝叶斯（Gamma 后验）框架计算该值，并将约束评估扩展至 chrX/chrY，因此数值与 v4.1 不同——请记录所用版本

数据访问

• 浏览器：https://gnomad.broadinstitute.org/ — 交互式浏览变异和基因
• GraphQL API：https://gnomad.broadinstitute.org/api — 程序化访问
• 下载：https://gnomad.broadinstitute.org/downloads — VCF、Hail 表格、约束表格
• Google Cloud：gs://gcp-public-data--gnomad/

其他资源

• gnomAD 网站：https://gnomad.broadinstitute.org/
• gnomAD 博客：https://gnomad.broadinstitute.org/news
• 下载：https://gnomad.broadinstitute.org/downloads
• API 浏览器：https://gnomad.broadinstitute.org/api（交互式 GraphiQL）
• 约束文档：https://gnomad.broadinstitute.org/help/constraint
• 引用文献：Karczewski KJ et al. (2020) Nature. PMID: 32461654；Chen S et al. (2024) Nature. PMID: 38057664
• GitHub：https://github.com/broadinstitute/gnomad-browser

脚本

scripts/query_gnomad.py — 用于 gnomAD GraphQL API 的可运行辅助脚本（无需密钥）。它包含内联 PEP 723 依赖，因此请使用 uv run 直接运行文件（而不是 uv run python ...），以自动安装 requests：

uv run scripts/query_gnomad.py variant 17-43094692-G-C --dataset gnomad_r4
uv run scripts/query_gnomad.py constraint BRCA1 --genome GRCh38