clinvar-database

ClinVar Database 技能用于访问和解读 NCBI ClinVar 数据库。ClinVar 是 NCBI 提供的免费公开档案库，收录人类遗传变异与表型之间关系的报告及支持证据，汇集基因组变异及其与人类健康关系的信息，提供临床遗传学与研究中使用的标准化变异分类。

用途与适用时机 当需要按基因、疾病或临床意义搜索变异；解读致病性、良性、意义未明（VUS）等临床意义分类；通过 E-utilities API 程序化访问 ClinVar 数据；从 FTP 下载并处理批量数据；理解评审状态与星级；处理冲突的变异解读；为变异调用集合注释临床意义时，可使用本技能。

主要能力

1. 搜索与查询：可通过网页界面（https://www.ncbi.nlm.nih.gov/clinvar/）按基因（如 BRCA1[gene]）、临床意义（pathogenic[CLNSIG]）、疾病（breast cancer[disorder]）、变异名称、染色体等条件检索，并支持组合查询。也可通过 E-utilities API 程序化访问，包括 esearch 搜索、esummary 获取摘要、efetch 下载完整 XML 记录、elink 查找其他 NCBI 数据库中的相关记录。建议先在网页界面测试查询再自动化，使用 API key 将速率限制从每秒 3 次提升到 10 次，对速率限制错误实现指数退避，使用 Biopython 时设置 Entrez.email。
2. 解读临床意义：使用 ACMG/AMP 标准术语，包括致病（P）、可能致病（LP）、意义未明（VUS）、可能良性（LB）、良性（B）。评审状态用星级表示：四星为实践指南，三星为专家小组评审（如 ClinGen），二星为多个提交者且无冲突，一星为带标准的单一提交者，无星为无断言标准。应始终检查评审状态，优先三星或四星；冲突解读需人工评估；分类可能随新证据变化；VUS 变异缺乏足够证据用于临床。
3. 从 FTP 下载批量数据：地址为 ftp://ftp.ncbi.nlm.nih.gov/pub/clinvar/。每月发布在每月第一个周四（完整数据集并存档），每周一更新（增量）。格式包括：XML（最全面，VCV 变异文件与 RCV 记录文件，含完整提交详情、证据与元数据）；VCF（用于基因组流程，分 GRCh37 与 GRCh38，不含大于 10kb 的变异和复杂结构变异）；制表符分隔文件（variant_summary.txt.gz 等，用于快速分析）。
4. 处理与分析数据：可用 Python 的 xml.etree 流式解析 XML；用 bcftools 过滤或注释 VCF（如按 CLNSIG、GENEINFO 过滤，或用 annotate 为自有 VCF 添加注释）；用 PyVCF 读取；用 pandas 或命令行工具处理制表符文件。
5. 处理冲突解读：当多个提交者对同一变异给出不同分类时，ClinVar 报告“致病性解读冲突”。解决策略包括检查星级评审状态、审查各方证据与断言标准、考虑提交日期、参考人群频率数据（如 gnomAD）、查阅专家小组分类，临床使用应咨询遗传学专业人员。
6. 追踪分类更新：分类可能因新功能研究、临床数据、人群频率更新、ACMG/AMP 指南修订、家系共分离数据而变化。建议记录 ClinVar 版本与访问日期以便复现，对关键变异定期复查，订阅邮件列表，使用每月存档版本。
7. 向 ClinVar 提交数据：机构可通过网页提交门户、API（需服务账户）或 Excel 模板批量提交；需 NCBI 机构账户、断言标准（优选 ACMG/AMP）及支持证据；账户设置可联系 clinvar@ncbi.nlm.nih.gov。

使用方式 技能文档提供三个参考文件：references/api_reference.md（E-utilities API 完整文档与示例）、references/clinical_significance.md（临床意义分类与评审状态解读指南）、references/data_formats.md（XML、VCF、制表符格式与 FTP 目录结构、处理示例）。文档中还包含多个工作流示例，如查找某基因中高置信度致病变异、为 VCF 注释 ClinVar 分类、分析特定疾病相关变异、批量下载并构建本地数据库。

局限与注意事项 数据质量方面：并非所有提交权重相同，需看星级；存在冲突解读需人工评估；历史提交可能过时；VUS 不是临床诊断。范围方面：不用于直接临床诊断，应咨询遗传学专业人员；变异频率因血统而异；覆盖不完整；需统一基因组版本（GRCh37/GRCh38）。技术方面：VCF 不含大于 10kb 的变异；API 速率限制为每秒 3 次（有 key 为 10 次）；完整 XML 发布为多 GB 压缩文件；网站每周更新，FTP 每月/每周更新，无实时更新。

外部资源包括 ClinVar 主页与文档、E-utilities 文档、ACMG 变异解读指南（Richards et al., 2015, PMID: 25741868）、ClinGen 专家小组网站等。