alterlab-clinvar

ClinVar 数据库

概述

ClinVar 是 NCBI 免费开放的档案库，收录了人类遗传变异与表型之间关系的报告及其支持证据。该数据库汇总了基因组变异及其与人类健康关系的信息，并提供标准化的变异分类，供临床遗传学和研究使用。

何时使用此技能

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

• 按基因、疾病或临床意义搜索变异
• 解读临床意义分类（致病、良性、意义未明变异）
• 通过 E-utilities API 以编程方式访问 ClinVar 数据
• 从 FTP 下载并处理批量数据
• 了解审阅状态和星级评分
• 解决相互冲突的变异解读
• 为变异检出集添加临床意义注释

不适用的情况

场景	改用
群体等位基因频率／祖源特异性 AF、gnomAD 约束	alterlab-gnomad
体细胞癌症突变目录、Cancer Gene Census、突变特征	alterlab-cosmic
肿瘤队列（TCGA、MSK-IMPACT）中基因发生突变的频率	alterlab-cbioportal
药物基因组学中的基因–药物剂量建议（CPIC/DPWG）	alterlab-clinpgx

三种分类类型（自 2024 年起）。 ClinVar 现在分别维护生殖系致病性（ACMG/AMP）、体细胞临床影响（AMP/ASCO/CAP 分级）和致癌性（ClinGen/CGC/VICC）的汇总分类。API 和文件会分别提供这些分类：esummary JSON 包含 germline_classification、clinical_impact_classification 和 oncogenicity_classification 对象（每个对象均包含 description 和 review_status；不再有 clinical_significance 字段）；VCF 包含 CLNSIG/CLNREVSTAT（生殖系）、ONC/ONCREVSTAT 和 SCI/SCIREVSTAT；variant_summary.txt 包含 ClinicalSignificance（生殖系）以及 SomaticClinicalImpact 和 Oncogenicity 列。

核心功能

1. 搜索和查询 ClinVar

Web 界面查询

通过 Web 界面在 https://www.ncbi.nlm.nih.gov/clinvar/ 搜索 ClinVar。

常见搜索模式（已根据实时 einfo 字段列表核实字段标签——不存在 [CLNSIG] 或 [RVSTAT] 字段；使用这些标签时会静默回退到 [All Fields]，不会进行筛选）：

• 按基因：BRCA1[gene]
• 按临床意义：clinsig_pathogenic[Properties]（也可使用 clinsig_likely_pathogenic、clinsig_benign、clinsig_likely_benign、clinsig_vus、clinsig_has_conflicts——注意 VUS 对应 clinsig_vus；clinsig_uncertain 不会匹配任何结果）
• 按审阅状态："reviewed by expert panel"[Review status]、"practice guideline"[Review status]、"criteria provided, single submitter"[Review status]
• 按疾病："breast cancer"[Disease/Phenotype]
• 按变异："c.1310_1313del"[Variant name]
• 按染色体：13[chr]
• 组合查询：BRCA1[gene] AND clinsig_pathogenic[Properties]

通过 E-utilities 进行编程访问

通过 NCBI 的 E-utilities API 以编程方式访问 ClinVar。完整的 API 文档请参阅 references/api_reference.md，其中包括：

• esearch - 搜索符合条件的变异
• esummary - 获取变异摘要
• efetch - 下载完整 XML 记录
• elink - 查找 NCBI 其他数据库中的相关记录

使用 curl 的快速示例：

# Search for pathogenic BRCA1 variants
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+clinsig_pathogenic[Properties]&retmode=json"

务必检查响应中的 querytranslation 字段：如果某个 [...] 标签未知，NCBI 会将其改写为 [All Fields]，导致筛选条件被静默丢弃。

最佳实践：

• 自动化前先在 Web 界面中测试查询
• 使用 API 密钥，将请求速率限制从每秒 3 次提高到 10 次
• 针对速率限制错误实现指数退避
• 使用 Biopython 时设置 Entrez.email

2. 解读临床意义

了解分类

ClinVar 使用标准化术语对变异进行分类。详细解读指南请参阅 references/clinical_significance.md。

关键的生殖系分类术语（ACMG/AMP）：

• Pathogenic（P） - 变异会导致疾病（概率约为 99%）
• Likely Pathogenic（LP） - 变异可能会导致疾病（概率约为 90%）
• Uncertain Significance（VUS） - 证据不足，无法分类
• Likely Benign（LB） - 变异可能不会导致疾病
• Benign（B） - 变异不会导致疾病

评审状态（星级）：

• ★★★★ 实践指南 - 置信度最高
• ★★★ 专家组评审（例如 ClinGen）- 高置信度
• ★★ 多个提交者，无冲突 - 中等置信度
• ★ 提供了标准，但只有一个提交者；或提供了标准，但分类存在冲突
• ☆ 未提供断言标准／未提供分类 - 低置信度

重要注意事项：

• 务必检查评审状态——优先选择 ★★★ 或 ★★★★ 评级
• 存在相互冲突的解读时，需要人工评估
• 随着新证据出现，分类可能发生变化
• VUS（意义未明）变异缺乏足够的临床应用证据

3. 从 FTP 下载批量数据

访问 ClinVar FTP 站点

从 https://ftp.ncbi.nlm.nih.gov/pub/clinvar/ 下载完整数据集（HTTPS 和 FTP 使用相同的目录结构）

全面的文件格式和处理文档请参阅 references/data_formats.md。

更新计划：

• 每月发布：每月第一个星期四（完整数据集，已归档）
• 每周更新：每周一（增量更新）

可用格式

XML 文件（内容最全面；自 2025-08-07 起采用当前格式，包含独立的生殖系／体细胞元素）：

• VCV（变异）文件：xml/ClinVarVCVRelease_YYYY-MM.xml.gz（以及 _00-latest 符号链接）- 以变异为中心的聚合数据
• RCV（记录）文件：xml/RCV_release/ClinVarRCVRelease_YYYY-MM.xml.gz - 变异与疾病的配对数据
• 旧版 ClinVarVariationRelease／ClinVarFullRelease 格式（含单一分类元素）已冻结在 xml/VCV_xml_old_format/ 和 xml/RCV_xml_old_format/ 中，不再受支持
• 包含完整的提交详情、证据和元数据

VCF 文件（用于基因组分析流程）：

• GRCh37：vcf_GRCh37/clinvar.vcf.gz
• GRCh38：vcf_GRCh38/clinvar.vcf.gz
• 限制：不包含大于 10 kb 的变异和复杂结构变异

制表符分隔文件（用于快速分析）：

• tab_delimited/variant_summary.txt.gz - 所有变异的摘要
• tab_delimited/var_citations.txt.gz - PubMed 引文
• tab_delimited/cross_references.txt.gz - 数据库交叉引用

下载示例：

# Download latest monthly VCV XML release
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_00-latest.xml.gz

# Download VCF for GRCh38
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz

4. 处理和分析 ClinVar 数据

使用 XML 文件

处理 XML 文件以提取变异详情、分类和证据。

使用 xml.etree 的 Python 示例：

import gzip
import xml.etree.ElementTree as ET

with gzip.open('ClinVarVCVRelease_00-latest.xml.gz', 'rt') as f:
    for event, elem in ET.iterparse(f, events=('end',)):
        if elem.tag == 'VariationArchive':
            variation_id = elem.attrib.get('VariationID')
            # Aggregate germline call lives under ClassifiedRecord/Classifications
            germline = elem.find('ClassifiedRecord/Classifications/GermlineClassification')
            if germline is not None:
                classification = germline.findtext('Description')      # e.g. "Pathogenic/Likely pathogenic"
                review_status = germline.findtext('ReviewStatus')
            elem.clear()  # Free memory

使用 VCF 文件

使用 bcftools 或 Python 注释变异调用结果，或按临床意义筛选。

使用 bcftools：

# Filter pathogenic variants
bcftools view -i 'INFO/CLNSIG~"Pathogenic"' clinvar.vcf.gz

# Extract specific genes
bcftools view -i 'INFO/GENEINFO~"BRCA"' clinvar.vcf.gz

# Annotate your VCF with ClinVar
bcftools annotate -a clinvar.vcf.gz -c INFO your_variants.vcf

在 Python 中使用 pysam（旧版 PyVCF／import vcf 软件包已无人维护，且无法在 Python 3.10 及更高版本中正常运行；请改用 pysam 或 cyvcf2）：

import pysam

vcf = pysam.VariantFile("clinvar.vcf.gz")
for rec in vcf:
    # CLNSIG is a comma/pipe-delimited string (e.g. "Pathogenic/Likely_pathogenic");
    # match as substring, not equality.
    clnsig = str(rec.info.get("CLNSIG", ""))
    if "Pathogenic" in clnsig:
        gene = rec.info.get("GENEINFO", "")
        print(f"{rec.chrom}:{rec.pos} {gene} - {clnsig}")

使用制表符分隔文件

使用 pandas 或命令行工具快速筛选和分析。

使用 pandas：

import pandas as pd

# Load variant summary (one row per variant *per assembly* — keep one build,
# or every count is doubled)
df = pd.read_csv('variant_summary.txt.gz', sep='\t', compression='gzip', low_memory=False)
df = df[df['Assembly'] == 'GRCh38']

# Filter pathogenic variants in specific gene
pathogenic_brca = df[
    (df['GeneSymbol'] == 'BRCA1') &
    (df['ClinicalSignificance'].str.contains('Pathogenic', na=False))
]

# Count variants by clinical significance
sig_counts = df['ClinicalSignificance'].value_counts()

使用命令行工具：

# Extract pathogenic TP53 variants (GRCh38 rows). Columns: 3 Name, 5 GeneSymbol,
# 7 ClinicalSignificance (germline), 17 Assembly, 25 ReviewStatus, 31 VariationID
zcat variant_summary.txt.gz | \
  awk -F'\t' '$5=="TP53" && $7~/Pathogenic/ && $17=="GRCh38"' | \
  cut -f3,5,7,25,31

5. 处理相互冲突的解释

当多个提交者对同一变异给出不同分类时，ClinVar 会报告“致病性分类相互冲突”（2024 年由“解释相互冲突”更名而来；VCF 值为 Conflicting_classifications_of_pathogenicity，审查状态为“已提供标准，相互冲突的分类”）。

解决策略：

1. 查看审查状态（星级评级）——评级较高的结果权重更大
2. 检查每位提交者提供的证据和判定标准
3. 考虑提交日期——较新的提交可能反映了更新的证据
4. 结合人群频率数据（例如 gnomAD）进行判断
5. 如有专家组分类（★★★），请予以参考
6. 用于临床时，务必听从遗传学专业人士的意见

排除冲突结果的搜索查询：

TP53[gene] AND clinsig_pathogenic[Properties] NOT clinsig_has_conflicts[Properties]

6. 跟踪分类更新

随着新证据出现，变异分类可能会随时间发生变化。

分类变化的原因：

• 新的功能研究或临床数据
• 更新的人群频率信息
• 修订后的 ACMG/AMP 指南
• 来自更多家系的共分离数据

最佳实践：

• 记录 ClinVar 版本和访问日期，以确保结果可复现
• 定期重新检查关键变异的分类
• 订阅 ClinVar 邮件列表，获取重要更新
• 使用每月归档版本，以获得稳定的数据集

7. 向 ClinVar 提交数据

组织可以向 ClinVar 提交变异解释。

提交方式：

• 网页提交门户：https://submit.ncbi.nlm.nih.gov/clinvar/
• API 提交（需要服务帐户）：参见 references/api_reference.md
• 通过 Excel 模板批量提交

要求：

• NCBI 组织帐户
• 判定标准（建议采用 ACMG/AMP 指南）
• 支持分类的证据

联系 [email protected] 设置提交帐户。

工作流示例

示例 1：识别基因中的高可信度致病变异

**目标：**查找 CFTR 基因中经专家组审核的致病变异。

步骤：

1. 使用网页界面或 E-utilities 进行搜索：

   CFTR[gene] AND clinsig_pathogenic[Properties] AND ("reviewed by expert panel"[Review status] OR "practice guideline"[Review status])
   

2. 查看结果，并留意审查状态（应为 ★★★ 或 ★★★★）
3. 导出变异列表，或通过 efetch 获取完整记录
4. 如适用，将结果与临床表现交叉比对

示例 2：使用 ClinVar 分类注释 VCF

**目标：**为变异调用添加临床意义注释。

步骤：

1. 下载合适的 ClinVar VCF（匹配基因组版本：GRCh37 或 GRCh38）：

   wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
   wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi
   

2. 使用 bcftools 进行注释：

   bcftools annotate -a clinvar.vcf.gz \
     -c INFO/CLNSIG,INFO/CLNDN,INFO/CLNREVSTAT \
     -o annotated_variants.vcf \
     your_variants.vcf
   

3. 筛选注释后的 VCF，获取致病变异：

   bcftools view -i 'INFO/CLNSIG~"Pathogenic"' annotated_variants.vcf
   

示例 3：分析与特定疾病相关的变异

**目标：**研究所有与遗传性乳腺癌相关的变异。

步骤：

1. 按疾病搜索：

   "hereditary breast cancer"[Disease/Phenotype] OR "Breast-ovarian cancer, familial"[Disease/Phenotype]
   

2. 将结果下载为 CSV，或通过 E-utilities 获取
3. 按审查状态筛选，优先考虑高可信度变异
4. 分析变异在各基因中的分布（BRCA1、BRCA2、PALB2 等）
5. 单独检查解释相互冲突的变异

示例 4：批量下载并构建数据库

**目标：**构建本地 ClinVar 数据库，用于分析工作流。

步骤：

1. 下载每月版本，以确保结果可复现：

   wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_YYYY-MM.xml.gz
   # previous years' monthly files move to xml/archive/<year>/
   

2. 解析 XML 并载入数据库（PostgreSQL、MySQL、MongoDB）
3. 按基因、位置、临床意义和审查状态建立索引
4. 实现版本跟踪，以便更新
5. 安排从 FTP 站点每月更新

重要限制与注意事项

数据质量

• 并非所有提交的权重都相同——检查审查状态（星级评级）
• 存在解释相互冲突的情况——需要人工评估
• 历史提交可能已过时——较新的数据可能更准确
• VUS 分类并非临床诊断——这意味着证据不足

范围限制

• 不用于直接临床诊断 — 务必咨询遗传学专业人士
• 针对特定人群 — 变异频率因祖源而异
• 覆盖范围不完整 — 并非所有基因或变异都经过充分研究
• 依赖版本 — 在各项分析中统一基因组版本（GRCh37/GRCh38）

技术限制

• VCF 文件不包含大型变异 — 大于 10 kb 的变异不采用 VCF 格式
• API 速率限制 — 无密钥时为 3 req/sec，使用 API 密钥时为 10 req/sec
• 文件大小 — 完整的 XML 版本是压缩后数 GB 的文件
• 无实时更新 — 网站每周更新，FTP 每月/每周更新

资源

参考文档

此技能包含全面的参考文档：

• references/api_reference.md — 完整的 E-utilities API 文档，包含 esearch、esummary、efetch 和 elink 的示例；涵盖速率限制、身份验证以及 Python/Biopython 代码示例

• references/clinical_significance.md — 临床意义分类、审查状态星级、冲突解决以及变异解读最佳实践的详细指南

• references/data_formats.md — XML、VCF 和制表符分隔文件格式的文档；涵盖 FTP 目录结构、处理示例和格式选择指南

外部资源

• ClinVar 主页：https://www.ncbi.nlm.nih.gov/clinvar/
• ClinVar 文档：https://www.ncbi.nlm.nih.gov/clinvar/docs/help/
• E-utilities 文档：https://www.ncbi.nlm.nih.gov/books/NBK25501/
• ACMG 变异解读指南：Richards 等人，2015 年（PMID: 25741868）
• ClinGen 专家组：https://clinicalgenome.org/

联系方式

如有关于 ClinVar 或数据提交的问题，请联系：[email protected]

脚本

scripts/query_clinvar.py — 通过 NCBI E-utilities 查询 ClinVar 的可运行辅助脚本（无需密钥；设置 NCBI_API_KEY 可提高速率限制）：

python scripts/query_clinvar.py search "BRCA1[gene] AND clinsig_pathogenic[Properties]" --retmax 5
python scripts/query_clinvar.py summary 12345,12346