onekgpd

OneKGPd：1000 Genomes Project 的个体级查询

范围

此技能查询 1000 Genomes Project 数据集——即基于 GRCh38 组装、由 3,202 名全基因组测序个体组成的高覆盖扩展队列。所有结果均来自该队列，技能返回的样本名称（例如 HG00096 或 NA21130）标识其参与者。

查询针对该队列的每个个体基因型数据进行解析。这支持两类互补的问题：选择某个区域内携带的变异（跨越整个队列或在指定的个体集合内），以及选择携带符合给定条件变异的个体。变异选择可按等位基因频率、预测后果、临床意义、AlphaMissense 分类以及下文列出的其他注释维度进行过滤。两个具名个体之间的亲缘关系也可查询。

变异被携带的基因型状态——杂合或纯合——是查询可以指定的条件；结果以变异或样本名称的形式返回，而不是原始基因型。

公共服务是 TLS gRPC，位于 db.dnaerys.org:443，通过 dnaerys 0.2.1（Python 3.11+）访问；它不是 REST 基 URL。维护中的服务快照声明 VEP 115 / GENCODE 49、ClinVar 202502 和 gnomAD 4.1。这些是服务的注释版本，而不是各上游资源的最新版本。在解释结果时请记录它们。

何时使用

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

• 在整个队列中查找某个区域或一组区域内携带的、符合某些条件的变异（select-variants）。
• 在特定个体集合中查找某个区域或一组区域内携带的、符合某些条件的变异（select-variants-in-samples）。
• 查找某个区域或一组区域内哪些 1000 Genomes 个体携带符合某些条件的变异（select-samples）。
• 统计有多少个体携带特定变异（count-samples）。
• 将任何变异查询限制为仅杂合或仅纯合携带，或同时查询两者（默认）。
• 确定哪些个体在单个位置为纯合参考（select-samples-hom-ref）。
• 确定两个具名 1000 Genomes 个体之间的亲缘关系——既包括程度（同卵双生 / 一级 / 二级 / 三级 / 无亲缘关系），也包括 KING 亲缘系数（kinship）。
• 获取数据集总计——样本数、性别分布、变异数、组装版本（dataset-info）。
• 变异选择可通过 KGP 等位基因频率、gnomAD 4.1 外显子组和 gnomAD 4.1 基因组等位基因频率、AlphaMissense Score 和 AlphaMissense Class、ClinVar 意义（202502）以及 VEP 注释（impact、biotype、feature type、variant class、consequences）来指定。

不要将此技能用于：

• 将基因符号、rsID 或转录本解析为坐标，或获取参考序列。请先解析坐标（见下文坐标来源），然后用解析后的 GRCh38 区域查询此技能。
• 除 1000 Genomes Project 以外的任何队列——此技能仅服务于该数据集。

前置条件

1. uv：本技能的脚本通过 uv run 运行，它会读取脚本的内联依赖元数据并临时配置环境。请确保 uv 已安装并位于 PATH 中（https://docs.astral.sh/uv/）。
2. 数据使用条款：1000 Genomes Project 数据是公开的；用户应了解 1000 Genomes Project / IGSR 的数据使用条款 （https://www.internationalgenome.org/data）。
3. 访问限制：无需 API key，无需 .env 文件，也无需配置速率限制 token。
4. 超时：网络命令默认每个 RPC 使用 --timeout 30 秒。 允许使用正的有限值覆盖该设置。分页会发起多个 RPC，且可重试的失败会将整个抓取最多重试三次，因此这不是整个命令的截止时间。

核心规则

• 使用封装脚本：务必执行提供的辅助脚本，而不是自行构造客户端调用或网络请求。使用 scripts/onekgpd_api.py 进行变异/样本/亲缘关系查询（它处理连接、流式传输、分页和 JSON 序列化），使用 scripts/onekgpd_meta.py 获取样本/群体元数据（离线，参见 样本与群体元数据）。
• 坐标必须先对照权威来源进行解析 —— 参见 坐标来源。这是强制要求，而非建议。
• 先计数再选择：每个变异和样本选择都有配对的计数命令。先调用计数命令以确定结果集规模，然后仅在计数可控时才进行选择。
• 默认包含两种接合性：选择和计数命令默认同时包含杂合和纯合携带。当问题明确针对某一种状态时，可用 --het-only 或 --hom-only 缩小范围。（无需传入任何参数即可同时获取两者。）
• 输出：脚本将完整 JSON 写入文件（--output，默认位于 /tmp/ 下），并向 stdout 打印简明摘要。不要将大型 JSON 文件读入上下文——使用 jq 或一次性的小型 uv run python 代码片段来 提取字段。--page-size 会检索每一页，但会将所有变异累积在内存中；它不是有界内存导出。请先确定查询规模。
• 检查完整性：result_incomplete=true 表示结果无法支持确定的零/不存在结论。请在服务恢复后重新运行。对于有上限的变异选择，truncated=true 表示已达到限制且可能存在更多记录，即使聚类结果本身是完整的。

坐标来源（强制第一步）

在任何基于区域的查询之前，请对照权威来源（例如 Ensembl 或 NCBI）将基因或特征解析为 GRCh38 坐标，并使用这些解析后的坐标进行查询。输入是 1-based、包含端点：BED 区间 [start0, end0) 变为 start=start0+1, end=end0。记录来源 accession、 注释版本和检索日期；即使在同一组装版本上，基因边界也可能因注释版本不同而不同。组装版本必须明确，且基因范围 在使用前必须解析为精确位置。这是结构性的，而非建议性的：没有任何来源侧护栏会发现位置错误的区域， 因此未经验证的坐标会返回非预期位置的结果，且不会报错。

# Resolve gene symbol -> GRCh38 region with an authoritative source FIRST,
# then pass the verified coordinates to the OneKGPd query below.

注意

该数据集是 GRCh38。GRCh37 坐标，或任何未正确对应到 GRCh38 上预期特征的区域，都会返回 非预期位置的结果，且不会引发错误。请在查询前验证 组装版本和解析后的坐标。

命令选择指南

将问题与命令相对应。计数类命令开销较小，应先于其对应的选择类命令执行。

• 哪些个体在某个区域携带匹配的变异 → count-samples 然后 select-samples
• 某个区域、整个队列范围内携带哪些变异 → count-variants 然后 select-variants
• 某个区域、在一组指定个体范围内携带哪些变异 → count-variants-in-samples 然后 select-variants-in-samples
• 谁在单个位点上为纯合参考 → count-samples-hom-ref 然后 select-samples-hom-ref
• 两个指定个体之间的亲缘关系（亲缘度 + 系数）→ kinship
• 数据集总量（样本数、性别分布、变异总数、装配版本）→ dataset-info

队列解读

3,202 个样本的队列包含亲属：额外增加的 698 个高覆盖度样本扩展了原先的 2,504 个样本的 panel。因此，携带者计数并非独立观测的计数，队列 AF 也不是人群患病率估计。对于关联分析或频率比较，请记录所选人群及亲缘关系处理策略；在选择或审核分析集时，请使用随附的谱系元数据和 kinship。参见 IGSR 队列公告。

注释过滤器（在变异与样本的选择/计数间共享）

所有变异与样本选择命令（count-variants、select-variants 及其 -in-samples 形式、count-samples、select-samples）都接受相同的注释过滤器。不同过滤器字段之间以 AND 组合；同一字段内的多个值之间以 OR 组合。枚举值不区分大小写（例如 missense_variant 或 MISSENSE_VARIANT）。

这些是在服务端应用的选择条件。所选变异上返回的字段列在返回变异的命令下；用于过滤的条件不一定会回显在返回的变异上。

• --af-lt / --af-gt：1000 Genomes 数据集等位基因频率边界
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt：gnomAD v4.1 外显子组 AF 边界
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt：gnomAD v4.1 基因组 AF 边界
• --clin-significance：ClinVar 显著性术语，CSV（例如 PATHOGENIC,LIKELY_PATHOGENIC）
• --consequence：Sequence Ontology 后果术语，CSV（例如 MISSENSE_VARIANT,STOP_GAINED）
• --impact：VEP 影响，CSV（HIGH,MODERATE,LOW,MODIFIER）
• --variant-type、--feature-type、--bio-type：SO 变异类别 / VEP 特征 / VEP 生物类型，CSV
• --alpha-missense-class：AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS（CSV）
• --alpha-missense-score-lt / --alpha-missense-score-gt：AlphaMissense 分数边界
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp：替代等位基因长度边界（bp）

说明

--alpha-missense-class 与 --alpha-missense-score-* 互斥（当设置了分数边界时，引擎会忽略类别）。--biallelic-only 与 --multiallelic-only 互斥。--exclude-males 与 --exclude-females 互斥。将某个 *-gt 边界设置为其匹配的 *-lt 边界或更大，会定义空范围并返回空结果。

说明

gnomad_exomes_af、gnomad_genomes_af 和 am_score 使用 0.0 表示在该服务快照中未注释。这并不证明其在当前 gnomAD 版本中不存在、具有生物学罕见性或为良性预测。数据集自身的 af 字段是另一种统计量，不是这个哨兵值。

注意

在服务端，数值为零的过滤器表示未设置，因此 --gnomad-exomes-af-gt 0 不会排除缺失的注释。封装层会拒绝零、非有限、超出范围以及 float32 下溢的边界。请选择一个明确的正阈值（例如 --gnomad-exomes-af-gt 0.000001 表示 AF > 1e-6，而不仅仅是存在注释）。若要精确表示 > 0，请获取完整变异集并在本地对返回的 AF 进行后过滤。仅使用 < X 过滤器会包含未注释的零值。对 AlphaMissense 也应同样注意缺失分数的情况。

分类注释会跨转录本保留。组合后果与影响过滤器并不能证明它们描述的是同一个转录本。amino_acids 可能包含多个 HGVSp 条目；通用 gRPC 服务将规范注释放在前面，而单独的 MCP 层会裁剪其输出。请保留转录本标识符，不要把模型的可能致病类别视为临床诊断或参与者表型。

快速开始

# Step 1. NCBI Gene 672, GRCh38.p14 / NC_000017.11, RS_2025_08:
# BRCA1 spans chr17:43044295-43170327 (1-based inclusive).
# Source: https://www.ncbi.nlm.nih.gov/gene/672 ; re-resolve for your analysis.
# Step 2. Size the result set: how many individuals carry predicted likely-pathogenic
#    missense variants in this region?
uv run scripts/onekgpd_api.py count-samples \
  --chrom chr17 --start 43044295 --end 43170327 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/count.json
# Step 3. If the count is manageable, list those individuals.
uv run scripts/onekgpd_api.py select-samples \
  --chrom chr17 --start 43044295 --end 43170327 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/samples.json
# Step 4. Count then select variants for actual returned sample IDs.
# HG03169,NA20506 below are illustrative IDs; substitute the Step 3 results.
uv run scripts/onekgpd_api.py count-variants-in-samples \
  --chrom chr17 --start 43044295 --end 43170327 \
  --samples HG03169,NA20506 \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variant_count.json
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom chr17 --start 43044295 --end 43170327 \
  --samples HG03169,NA20506 \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

命令

每条命令都会将完整 JSON 写入文件（--output PATH，默认为临时文件），并向 stdout 打印简洁摘要。所有区域/样本命令共享：区域输入（--chrom/--start/--end 以及可选的 --ref/--alt，或一个或多个重复的 --region CHR:START-END）、接合性标志（--het-only/--hom-only，默认两者都包括），以及上述注释过滤器。完整的逐标志表位于 references/onekgpd_commands.md。

返回变异体的命令

select-* 返回匹配的变异体；count-* 返回整数计数。

• count-variants — 在整个队列范围内统计某个区域中的变异体数量。
• select-variants — 在整个队列范围内选择某个区域中的变异体。使用 --limit N （硬上限，默认 200）或 --page-size N（分页检索完整集合）；两者互斥。达到上限时，摘要会标记 truncated。
• count-variants-in-samples — 与 count-variants 相同，但限定于 --samples NAME1,NAME2,...（必填）。
• select-variants-in-samples — 与 select-variants 相同，但限定于 --samples NAME1,NAME2,...（必填）。

每个返回的变异体都包含以下 22 个键：chr、start、end、ref、 alt、af、ac、an、hom_samples、het_samples、mis_samples、 hom_samples_fx、het_samples_fx、mis_samples_fx、hom_samples_mxy、 het_samples_mxy、mis_samples_mxy、gnomad_exomes_af、gnomad_genomes_af、 am_score、amino_acids、biallelic。 ClinVar 显著性和 VEP 后果仅作为筛选条件，不会被返回。完整 schema： references/onekgpd_commands.md。

返回样本的命令

• count-samples — 统计某个区域中携带匹配变异体的个体数量。
• select-samples — 列出携带匹配变异体的个体名称。 支持 --skip N 和 --limit N。仅返回名称；要查看某个个体因哪些 变异体而符合条件，可将这些名称传入 select-variants-in-samples。

纯合参考命令

通过 --chrom + --position 指定单个位置（而非区域）。

• count-samples-hom-ref — 统计该位置为 0/0 基因型的个体数量。 该计数使用哨兵值：-1 = 该位置根本不存在变异体； 0 = 存在变异体但没有任何个体为纯合参考；>0 = 纯合参考个体的数量。这些解读要求 result_incomplete=false；否则 variant_present 为 null。没有变异体 记录并不证明全部 3,202 个个体都具有可检出的 0/0 基因型。
• select-samples-hom-ref — 列出该位置为 0/0 基因型的个体。

亲缘关系命令

• kinship --sample1 NAME --sample2 NAME — 两个指定个体之间的 亲缘关系：亲缘程度（TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED）以及 KING 亲缘系数 （phi_bwf）。

数据集元数据命令

• dataset-info — 数据集总计：samples_total（3,202）、女性/男性 分布、variants_total、assembly（GRCh38）以及队列明细。无需 区域；也可用作连通性检查。

样本与群体元数据（离线）

群体、性别、家系和超级群体相关问题由第二个脚本 scripts/onekgpd_meta.py 回答，其数据来自技能中内置的数据文件——无需网络、无需凭证、无需坐标。样本 ID 与变异命令使用的是同一套名称，因此这两层可以组合使用（例如，先按群体挑选队列，再查询其变异）。运行 uv run scripts/onekgpd_meta.py <command>。

该队列包含 5 个超级群体（AFR、AMR、EAS、EUR、SAS）和 26 个群体。群体/超级群体值按短代码或全名进行不区分大小写匹配；样本 ID 区分大小写。

• sample-metadata --samples NA19240,HG00096 — 给定样本的家系、性别、父母、子女、群体、超级群体和 phase3 状态。
• list-populations — 全部 26 个群体及其超级群体和样本数（用于发现有效值）。
• list-superpopulations — 5 个超级群体及其样本数和所含群体。
• population-stats --populations YRI [--populations CHS …] — 每个群体的性别分布、phase3 计数和 trio 归属。为多个值重复 --populations（全名包含逗号，因此不以逗号分隔）。
• superpopulation-summary --superpopulations EAS [--superpopulations EUR …] — 每个超级群体的总数及按群体细分。
• select-samples-by-population --population YRI 和/或 --superpopulation AFR，可选 --skip/--limit（默认 0 / 50，最大 3202）— 某个群体和/或超级群体中的样本 ID；两者同时给出时取交集。将这些名称传入 select-variants-in-samples 即可查看其变异。

完整的参数表和 JSON 输出模式请参见 references/onekgpd_commands.md。

典型工作流

先确定哪些个体，再确定它们携带哪些变异

以下为示例模板；请替换所有尖括号占位符。

# Step 1: resolve gene -> verified GRCh38 region (authoritative source).
# Step 2: count individuals carrying a qualifying variant in the region.
uv run scripts/onekgpd_api.py count-samples \
  --chrom <chr> --start <start> --end <end> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/n.json
# Step 3: list those individuals.
uv run scripts/onekgpd_api.py select-samples \
  --chrom <chr> --start <start> --end <end> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/who.json
# Step 4: count variants for those individuals before selecting.
uv run scripts/onekgpd_api.py count-variants-in-samples \
  --chrom <chr> --start <start> --end <end> \
  --samples <name1,name2,...> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variant_count.json
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom <chr> --start <start> --end <end> \
  --samples <name1,name2,...> \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

感兴趣位点上的纯合参考基因型携带者

示例模板；请用经验证的坐标替换占位符。

# After identifying a position of interest (verified coordinate):
uv run scripts/onekgpd_api.py count-samples-hom-ref \
  --chrom <chr> --position <pos> --output /tmp/homref_n.json
uv run scripts/onekgpd_api.py select-samples-hom-ref \
  --chrom <chr> --position <pos> --output /tmp/homref.json

常见错误

• 错误： 使用未经验证的坐标进行查询。 修复： 始终先对照权威来源将基因/特征解析为 GRCh38。 位置放错会返回非预期位置的结果而不报错。
• 错误： 在计数命令之前调用选择命令。 修复： 先计数；选择结果集可能很大。
• 错误： 假设 GRCh37 坐标也能使用。 修复： 该数据集仅支持 GRCh38。

参考资料

• references/onekgpd_commands.md — 完整的 逐命令参数表和返回变异输出模式。
• references/annotation_vocabularies.md — CSV 过滤标志所接受的受控词汇术语 （后果、影响、生物类型、特征类型、ClinVar 显著性、 AlphaMissense 类别、变异类别）。
• 当前 API 契约和实时检查范围： 命令参考。
• 1000 Genomes Project / IGSR：https://www.internationalgenome.org/
• 1000 Genomes Project 数据集在线版：https://dnaerys.org/online/