clinvar-database

ClinVar 数据库

前置条件

1. uv：阅读 uv 技能，并按照其中的设置说明操作，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/clinvar_database_LICENSE.txt，则（1）醒目地通知用户查看 https://www.ncbi.nlm.nih.gov/clinvar/ 上的条款，然后（2）创建该文件，记录通知文本和时间戳。
3. .env 文件：确保主目录中存在 .env 文件。如果不存在，请创建一个。
4. NCBI_API_KEY（可选）：将 NCBI 速率限制从每秒 3 次请求提高到 10 次。此技能无需 API 密钥也能使用，但如果用户计划进行大量查询或遇到 429 错误，建议使用密钥。你可以在 https://www.ncbi.nlm.nih.gov/account/settings/ 免费注册密钥。如果此技能看起来与用户的请求相关，你必须使用 credentials 技能中的安全凭据流程来检查并申请此密钥。

概述

ClinVar 是人类基因组变异临床分类的主要共识记录。它根据全球实验室提交的断言，提供致病性标签（Pathogenic、Likely Pathogenic、Benign、VUS）的“临床事实依据”。

适用场景

在以下情况下使用：

• 查询特定变异当前的临床意义和星级评级（审查状态）。
• 获取临床医生备注、断言标准，或以往临床实验室分类的依据。
• 获取特定变异的首选疾病名称及相关 HPO 术语。
• 查找变异列表（例如，“查找 HBB 基因中距离信号 50bp 以内的所有 Pathogenic 变异”）。
• 检查特定变异是否存在相互矛盾的解读，并确定提交各项分类的组织。

在以下情况下不要使用：

• 查询全球人群中的特定等位基因频率（使用 gnomAD）。
• 描述蛋白质的正常生物学作用和典型遗传模式（使用 OMIM）。
• 预测新突变（如移码或外显子跳跃）的机制效应（使用 AlphaGenome）。
• 查询携带致病变异患者的推荐监测计划（使用 GeneReviews）。
• 生成或查看受影响蛋白质的 3D 结构模型（使用 PDB / AlphaFold）。

快速入门

ClinVar 查询通过一个可靠的 Python 封装脚本执行，用于处理严格的速率限制以及 XML/JSON 解析。

示例：搜索 BRCA1 变异

uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json

核心规则

• Retmax 限制：搜索命令默认使用 --retmax 200。对于任何“列出全部”或全基因范围的请求，必须显式将 --retmax 设置为更高值（例如 1000），以确保数据完整。
• 使用封装脚本：标准查询优先使用封装脚本。它会为你处理速率限制、重试和复杂的 XML 解析。如果脚本解析后的输出不包含所需的特定字段，你可以修改脚本或直接查询 NCBI E-utilities API——但请注意，原始 XML 架构十分复杂，并且因记录类型而异。
• 如果触发速率限制，脚本会抛出明确的错误。如果发生这种情况，你必须使用 credentials 技能中的安全凭据流程，检查并申请 NCBI_API_KEY，以帮助用户将其添加到 .env 文件中。
• 通知：如果使用此技能，请确保在输出中提及。

实用脚本

1. count — 统计匹配的变异

用途： 无需获取 ID 即可检查有多少个变异匹配查询条件。可据此决定是否需要完整的 search。

参数：

• --query：（必填）NCBI Entrez 搜索查询字符串。
• --output：（必填）输出 JSON 文件路径。

示例： uv run scripts/clinvar_api.py count \ --query "TP53[gene] AND \"uncertain significance\"[clinsig]" \ --output count.json 输出： {"total_count": <int>}

2. search — 搜索变异

用途： 使用 NCBI Entrez 搜索语法，根据基因组位置、基因符号或临床属性识别变异。搜索命令会自动分页遍历所有匹配结果，确保检索完整且结果确定。

# Fetch ALL matching variants (default behavior)
uv run scripts/clinvar_api.py search \
  --query "BRCA1[gene]" --output results.json

# Search by Chromosome and Position Range
uv run scripts/clinvar_api.py search \
  --query "11[chr] AND 5225000:5226000[chrpos]" --output results.json

# Combine terms using Entrez syntax
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output results.json

# Cap results at 50
uv run scripts/clinvar_api.py search \
  --query "TP53[gene]" --retmax 50 --output results.json

参数：

• --query：（必填）NCBI Entrez 搜索查询字符串。
• --retmax：要返回的变异 ID 总数上限。默认值为 0，表示“获取所有匹配结果”。 设置为正整数可限制结果集。
• --page_size：每次 API 请求获取的 ID 数量（默认值：500；根据 NCBI 限制，最大值：10000）。
• --output：（必填）输出 JSON 文件路径。

输出： 包含以下内容的 JSON 对象：

• total_count — ClinVar 中匹配的变异总数。
• fetched_count — 实际检索到的 ID 数量。
• variant_ids — ClinVar Variation ID 字符串列表。

3. summary — 获取解读摘要

用途： 获取临床意义标签、星级评分（审查状态）和基本表型数据，以便快速筛查变异。

# Get summary for one or more Variation IDs
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

参数：

• --variant_ids：（必填）一个或多个 ClinVar Variation ID。
• --output：（必填）输出 JSON 文件路径。

输出： JSON 摘要对象列表，每个对象包含：

• variant_id、title、clinical_significance、review_status、
  last_evaluated、phenotypes
• genes — {gene_id, symbol, strand} 列表
• variation_type — 例如，单核苷酸变异、缺失、插入
• molecular_consequences — 字符串列表（例如，["错义变异",
  "无义"]）

4. evidence — 获取临床证据

用途： 获取单个变异的完整临床记录，包括临床医生的自由文本解释、断言方法和提交者的具体备注。

# Get full evidence for a single Variation ID
uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

参数：

• --variant_id：（必填）单个 ClinVar Variation ID。
• --output：（必填）输出 JSON 文件路径。

输出： 包含以下内容的 JSON 对象：

• variant_id
• allele_info — {chromosome, position_start, position_stop, reference_allele, alternate_allele, cytogenetic_band, dbsnp_rsid}（优先使用 GRCh38）
• conditions — {name, medgen_cui, omim_id, orphanet_id, hpo_terms} 列表
• functional_consequences — {value, sequence_ontology_id} 列表
• structural_variant_details — {outer_start, inner_start, inner_stop, outer_stop, copy_number}（仅 CNV 提供，否则为 null）
• citation_references — 在全局“Citations”部分引用的 PubMed ID 列表
• submissions — 各提交者记录的列表，每条记录包含：
  • submitter_name、classification、curator_notes、 assertion_criteria
  • date_last_evaluated — 提交者上次审查该分类的日期

典型工作流

先统计工作流（推荐）

对于大型或数量未知的结果集，先使用 count 判断是否继续，然后使用 search（它会自动分页并返回 total_count / fetched_count），再使用 summary 进行筛查。

# Step 1: Gauge size (optional — search also returns total_count)
uv run scripts/clinvar_api.py count \
  --query "HBB[gene] AND pathogenic[clinsig]" --output count.json

# Step 2: Fetch all variant IDs (auto-paginates)
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output ids.json

# Step 3: Get summaries (extract variant_ids from search output)
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

深入分析：search → evidence

如果需要了解特定变异的完整临床情况，包括提交者的解释、PubMed 引文、与本体关联的疾病以及等位基因坐标，请使用 evidence。

uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

工作流：稳健的变异发现（三角验证）

ClinVar 元数据并不一致。为满足“列出所有”这类请求，不要只依赖单一筛选条件。请在同一轮中执行以下操作并合并结果：

1. 按确切标签搜索（例如，"3 prime UTR variant"[molecular_consequence]）。
2. 按 HGVS 命名模式搜索（例如，c.*）。
3. 按基因组坐标范围搜索（使用 [chrpos]）。

这种“三角验证”可确保不会遗漏缺少标签的结构变异。

通过 HGVS 验证编码与非编码状态

仅凭 molecular_consequences 可能无法明确判断（例如，splice donor variant 同时出现在编码和非编码情形中）。务必交叉核对 title 字段中的 HGVS 模式：

• c.-… — 5' UTR（非编码）
• c.*… — 3' UTR（非编码）
• c.123+N / c.123-N — 内含子（非编码）
• p.Trp146Arg 等 — 蛋白质影响（编码）

具有 UTR／内含子 HGVS 且没有 p. 注释的变异属于非编码变异，即使带有剪接标签也是如此。反之，任何 p. 注释都表示存在编码影响。

ClinVar 元数据参考

• 3' UTR
  • 搜索字符串："3 prime UTR variant"[mol_consequence]
  • HGVS：c.*
• 5' UTR
  • 搜索字符串："5 prime UTR variant"[mol_consequence]
  • HGVS：c.-
• 要查找“高置信度”变异或经专家评审达成共识的结果，请使用 review_status 筛选条件。这是区分单个实验室提交的断言与经专家小组评审的可靠结果的最高效方式。

字段用途

• 快速查看致病性标签 — 使用 summary → clinical_significance
• 基因符号和链方向 — 使用 summary → genes
• 变异类型（SNV、del 等） — 使用 summary → variation_type
• 蛋白质水平影响 — 使用 summary → molecular_consequences
• 基因组坐标（GRCh38） — 使用 evidence → allele_info
• 关联疾病（本体） — 使用 evidence → conditions
• SO 功能后果 — 使用 evidence → functional_consequences
• CNV 断点／拷贝数 — 使用 evidence → structural_variant_details
• PubMed 文献引用 — 使用 evidence → citation_references
• 最近一次实验室评审日期 — 同时使用 → last_evaluated
• 临床医生的判定理由 — 使用 evidence → submissions[].curator_notes

检索基因组坐标（默认采用 HG38/GRCh38）

要获取 <chrom>:<pos>:<ref>><alt> 格式的精确基因组坐标 （例如，chr5:70951945:G>A），必须使用 evidence 命令，因为 summary 输出中不包含这些详细信息。

列出或展示变异时，必须始终包含 <chrom>:<pos>:<ref>><alt> 格式的基因组坐标，即使用户没有明确要求。如果 summary 中缺少坐标，请使用 evidence 命令或 dbSNP 回退方案检索。

1. 获取证据：使用 uv run scripts/clinvar_api.py evidence --variant_id <ID> --output evidence.json。
2. 提取 VCF 属性：evidence 命令会解析 XML。请提取：
   • 染色体：Chr
   • 位置：positionVCF（或 start）
   • Ref：referenceAlleleVCF（或 referenceAllele）
   • Alt：SequenceLocation 元素中 Assembly="GRCh38" 对应的 alternateAlleleVCF（或 alternateAllele）。

坐标不精确时的回退方案（基因范围）：对于非编码变异，ClinVar 通常会返回完整的基因范围。如果提取的坐标对应的是基因范围，而不是特定位置，请使用 dbsnp-database skill，通过 dbsnp_rsid 或 HGVS 标题解析精确坐标：1.检查 evidence 输出中是否有 dbsnp_rsid。2. 运行 uv run scripts/dbsnp_cli.py resolve-rsid {rsid} 获取精确的 GRCh38 坐标。3. 使用 dbSNP 中的 SPDI 或 HGVS 数据，将坐标格式化为 <chrom>:<pos>:<ref>><alt>。

结构变异说明

structural_variant_details 字段仅针对拷贝数变异（CNV）填充。对于标准 SNV 和小型插入缺失，该字段为 null。 请改用 allele_info 字段（position_start、position_stop、 reference_allele、alternate_allele）。

CNV / 大片段缺失说明

大型拷贝数变异（CNV）的 molecular_consequences 字段通常为空。如果变异标题中提到“del”，且坐标与目标区域重叠，那么无论是否缺少标签，该变异都相关。

获取和使用 API 密钥

你可以在 https://www.ncbi.nlm.nih.gov/account/settings/ 免费注册获取密钥。如果此技能看起来与用户请求相关，你必须使用 credentials 技能中的安全凭据协议检查并申请此密钥。

最佳实践

• 始终使用 uv run 执行 python。
• 如果无法使用 jq，请立即改用 Python 单行命令处理 JSON（例如，uv run python3 -c "import json; ..."）。
• 使用 count，然后再使用 search，以了解结果集的大小。
• search 命令默认会获取所有结果，并在输出中包含 total_count 和 fetched_count——请务必确认两者相符，以确保检索完整。
• Entrez 结果未排序。若要按日期排序，请获取所有结果，然后在本地按 last_evaluated 排序。

常见错误

• 尝试自行解析 E-utilities XML——始终使用提供的 clinvar_api.py 客户端，它可以稳健地处理不可预测的 XML 架构。
• 遇到 HTTP 429 Too Many Requests——客户端会抛出异常并提示你暂停。你必须使用 credentials 技能中的安全凭据协议检查并申请 NCBI_API_KEY，帮助用户将其添加到 .env 文件，然后重试。
• 向 API 发送原始 DNA 序列——API 需要 HGVS 命名法、RS ID 或正确的 Entrez 坐标语法（11[chr] AND 1234[chrpos]），而不是原始 ATCG 字符串。
• 对于同义或非编码变异——HGVS 命名法（例如，CAPN3 AND "c.551C>T"）比坐标搜索（[chrpos]）更可靠，因为 ClinVar 中许多此类记录都没有精确的基因组定位。
• 分子后果的大小写敏感性——ClinVar 返回的字符串大小写混杂。筛选时始终使用不区分大小写的匹配（.lower()）。
• 将 search 输出解析为普通列表——search 返回的是包含 total_count、fetched_count 和 variant_ids 的 JSON 对象，而不是普通列表。