dbsnp-database

dbSNP 数据库集成

前置条件

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

核心规则

• 使用封装脚本：查询数据库时，始终执行提供的封装脚本 scripts/dbsnp_cli.py，而不要构造自定义 HTTP 或 curl 请求。该脚本会自动处理速率限制、重试和 JSON 解析。
• 命令选择：不要使用 search-region 查找特定变异的 rsID；应改用 resolve-variant。
• 输出大小：除非确有需要，否则避免对 get-variant 使用 --full，因为原始载荷可能超过 1 MB。
• Shell 安全：始终将 HGVS 字符串括在单引号中，以避免 Shell 展开错误。
• 通知：如果使用了此技能，确保在输出中提及。

适用场景

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

• 将基因组变异映射到其规范 rsID（通过 VCF 坐标或 HGVS 表示法）。
• 获取 rsID 的摘要数据：变异类型、基因关联、临床意义和群体等位基因频率。
• 将 rsID 转换回特定组装版本上的基因组坐标。
• 查找染色体区域内的所有已知变异。

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

• 获取包含提交者理由的临床致病性分类（使用 clinvar-database）。
• 获取按祖源分层的精确群体等位基因频率（使用 gnomad-database）。
• 预测新突变的功能影响（使用 alphagenome-single-variant-analysis）。
• 查看受变异影响的蛋白质 3D 结构（使用 alphafold-database-fetch-and-analyze / pdb-database）。

命令选择指南

首次就选对命令。 根据用户的输入，从下方选择正确的子命令——通常只需调用一次命令。

• 用户提供……：运行此命令
• 一个 rsID（例如 rs7412、rs268）：get-variant
• 基因组坐标：染色体位置参考等位基因替代等位基因（例如 8 19962213 C T）： resolve-variant
• 一个 HGVS 字符串（例如 NC_000008.11:g.19962213del）：resolve-hgvs
• 一个 rsID，且需要查询其坐标：resolve-rsid
• 一个染色体区域（染色体起始位置终止位置）：search-region

注意

**不要使用 search-region 查找特定变异的 rsID。**如果用户提供染色体、位置、参考等位基因和替代等位基因（四个值），请使用 resolve-variant——这是一次直接的 API 查询。search-region 仅用于调查某个位置范围内的所有变异，返回结果可能多达数百或数千条。

快速开始

# Look up variant rs7412: type, gene, clinical significance, MAF
uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

# Find the rsID for a variant at chr8:19962213 C>T
uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

所有子命令都会将 JSON 写入磁盘。始终将输出保存到 /tmp/ 目录中。必须指定 --output 标志。

命令

1. get-variant — 获取变异记录

检索一个 rsID 对应的 RefSNP 记录。默认情况下，输出会缩略为最有用的字段。rs268 和 268 均可接受。

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

参数：

• rsid（位置参数，必需）：RefSNP 标识符。
• --assembly：RefSeq 组装版本登录号（默认值：GCF_000001405.40 = GRCh38）。
• --full：返回完整的原始 JSON 负载 — 请参阅下方警告。
• --output：输出文件路径（默认值：/tmp/dbsnp_output.json）。

缩略输出字段：

• refsnp_id：数字形式的 rsID
• variant_type：例如 snv、ins、del、delins
• genes：按顺序排列的基因符号（基因座名称）列表
• clinical_significances：临床意义标签列表
• minor_allele_frequencies：研究名称、等位基因计数、总计数
• placements：所请求组装版本的基因组位置

警告

关于 --full： 原始 RefSNP 负载通常为 50–500 KB；对于提交记录众多的临床重要变异，可能会超过 1 MB。 仅当你确实需要缩略输出中没有的数据时才使用 --full — 例如：

• 所有转录本和蛋白质异构体的完整 HGVS 命名。
• 完整的提交历史，包括各提交者的详细信息和时间戳。
• 研究中按亚群划分的人群层面等位基因频率明细（例如，gnomAD 按人群划分的计数）。
• 多个组装版本中的完整基因组位置集（同时包含 GRCh37 和 GRCh38）。
• 合并历史，显示哪些较旧的 rsID 被合并到此 ID。

2. resolve-variant — 基因组坐标 → rsID

根据变异的基因组坐标（染色体、位置、参考等位基因、替代等位基因）确定其 rsID。当用户以空格分隔的坐标形式提供变异时，应使用此命令，例如 8 19962213 C T。

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

参数：

• chrom（位置参数）：染色体编号（例如 8）或 RefSeq 序列登录号（例如 NC_000008.11）。染色体 X 和 Y 必须分别以对应的数字传入：X 为 23，Y 为 24。
• pos（位置参数）：从 1 开始计数的基因组位置。
• ref（位置参数）：参考等位基因（例如 C）。
• alts（位置参数）：替代等位基因，可用逗号分隔（例如 T）。
• --assembly：RefSeq 组装版本登录号（默认值：GCF_000001405.40）。
• --output：输出文件路径（默认值：/tmp/dbsnp_output.json）。

输出： {"rsids": ["12345", "67890"]}

3. resolve-rsid — rsID → 基因组坐标

获取特定组装版本上已知 rsID 的基因组位置（序列 ID 和等位基因详细信息）。

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

参数：

• rsid（位置参数）：RefSNP 标识符。
• --assembly：RefSeq 组装版本登录号（默认值：GCF_000001405.40）。
• --output：输出文件路径（默认值：/tmp/dbsnp_output.json）。

输出： {"rsid": "7412", "assembly": "...", "placements": [...]}

4. resolve-hgvs — HGVS → rsID

查找与 HGVS 表达式对应的 rsID。

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

参数：

• hgvs（位置参数）：HGVS 字符串。
• --assembly：RefSeq 组装版本登录号（默认值：GCF_000001405.40）。
• --output：输出文件路径（默认值：/tmp/dbsnp_output.json）。

输出： {"rsids": ["12345"]}

提示

HGVS 字符串通常包含 shell 会解释的字符（冒号、大于号）。请始终用单引号括住它们，以避免 shell 展开。

5. search-region — 区域变异搜索

查找限定染色体区域内的所有 rsID。

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --output /tmp/region.json

参数：

• chrom（位置参数）：染色体（例如 7）。染色体 X 使用 23， 染色体 Y 使用 24。
• start（位置参数）：起始位置。
• end（位置参数）：结束位置。
• --retmax：返回的 rsID 最大数量（默认值：500，上限：5 000）。
• --output：输出文件路径（默认值：/tmp/dbsnp_output.json）。

输出：

{
  "rsids": ["12345", "67890", "..."],
  "returned": 500,
  "total_available": 1423,
  "truncated": true,
  "note": "Only 500 of 1423 variants returned.  Increase --retmax ..."
}

当 total_available 大于返回数量时，输出会包含 truncated 标记和 note。增大 --retmax 可检索更多结果（最多 5 000 个）。

典型工作流

根据坐标识别已知变异

# Step 1: Map VCF coordinates to rsID
uv run scripts/dbsnp_cli.py resolve-variant 19 44908684 T C \
  --output /tmp/step1.json

# Step 2: Get the full details for the resolved rsID
uv run scripts/dbsnp_cli.py get-variant <rsid_from_step1> \
  --output /tmp/step2.json

调查基因区域内的变异

# Step 1: Find all variants in a region spanning the CFTR gene
uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --retmax 1000 --output /tmp/region.json

# Step 2: Retrieve details on individual rsIDs of interest
uv run scripts/dbsnp_cli.py get-variant <rsid> --output /tmp/detail.json

将 HGVS 表示法转换为基因组坐标

# Step 1: Get the rsID for an HGVS expression
uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000019.10:g.44908684T>C' \
  --output /tmp/hgvs.json

# Step 2: Resolve that rsID to VCF-style coordinates
uv run scripts/dbsnp_cli.py resolve-rsid <rsid> --output /tmp/coords.json

组装版本默认值和自动回退

Variation Services 端点（由 get-variant、resolve-variant、 resolve-rsid、resolve-hgvs 使用）要求提供 RefSeq 组装版本登录号。 GRCh38 的 RefSeq 登录号为 GCF_000001405.40，GRCh37 的为 GCF_000001405.25。

search-region 子命令始终搜索 GRCh38 坐标。

重要

自动组装版本回退： resolve-variant 和 resolve-hgvs 命令会先自动尝试 GRCh38。如果未找到 rsID，则会在报告失败前 改用 GRCh37 重试。发生回退时，输出 JSON 会包含一个 "note" 字段，说明 哪个组装版本成功。 你无需手动改用其他组装版本重试——脚本会自动处理。

只有在你明确希望将查询限制在某个组装版本时（例如，已知用户的坐标 属于 GRCh37），才需要覆盖 --assembly。

NCBI API 密钥和速率限制

未使用 API 密钥时，脚本的请求速率限制为每秒 3 次。使用密钥后，速率 可提高到每秒 10 次。

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

HTTP 500 错误排查

参考等位基因不匹配

如果收到 HTTP 500 错误，且错误消息指出断言的参考等位基因与参考序列不相符：

**含义：**坐标位置可能有效，但你提供的参考等位基因（ref）与所请求 组装版本中该位置的碱基不匹配。

**操作：**1. 不要机械地重试完全相同的查询。2. 检查组装版本：坐标因 组装版本而异。3. 切换组装版本：如果查询的是 GRCh37，请尝试 GRCh38（使用 --assembly GCF_000001405.40）；如果查询的是 GRCh38，请尝试 GRCh37（使用 --assembly GCF_000001405.25）。

常见错误

• 错误： 忘记给 HGVS 字符串加引号 修正： 用单引号括起来：'NC_000008.11:g.19962213del'

• 错误： 向 resolve-variant 传入染色体名称，而不是序列登录号 修正： 使用染色体数字 ID（例如 8）或 RefSeq 登录号，例如 NC_000008.11

• 错误： 不需要时仍在 get-variant 中使用 --full 修正： 简略输出已能满足大多数使用场景；--full 会返回 50–500 KB 以上的 JSON

• 错误： 认为 search-region 默认会返回所有结果 修正： 默认 --retmax 为 500；查看输出中的 total_available，确认结果是否被截断

• 错误： 在 search-region 中使用 GRCh37 坐标 修正： search-region 始终使用 GRCh38 坐标；如果起始坐标来自 GRCh37，请先进行坐标转换

• 错误： 首次调用失败时，手动使用不同的 --assembly 重试 resolve-variant 或 resolve-hgvs 修正： 脚本会自动依次尝试 GRCh38 和 GRCh37；调用一次即可

• 错误： 将 X 或 Y 作为染色体值传入 修正： 使用对应的数字：染色体 X 为 23，染色体 Y 为 24。CLI 默认按数字处理染色体。