onekgpd

OneKGPd：千人基因组计划的个体级查询

范围

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

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

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

何时使用

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

• 在某个区域或区域集合中，寻找跨整个队列的、符合某些条件的变异（select-variants）。
• 在某个区域或区域集合中，寻找特定个体集合中符合某些条件的变异（select-variants-in-samples）。
• 寻找在某个区域或区域集合中携带符合某些条件的变异的千人基因组个体（select-samples）。
• 统计携带特定变异的个体数量（count-samples）。
• 将任何变异查询限制为仅杂合或仅纯合携带，或同时查询两者（默认）。
• 识别在单个位置上为纯合参考型的个体（select-samples-hom-ref）。
• 确定两个指定的千人基因组个体之间的亲缘关系——包括程度（双胞胎/一级/二级/三级/无关）和 KING 亲缘系数（kinship）。
• 获取数据集总数——样本数、性别分布、变异数、组装版本（dataset-info）。
• 变异选择可以通过 KGP 等位基因频率、gnomAD 4.1 外显子组和 gnomAD 4.1 基因组等位基因频率、AlphaMissense 分数和 AlphaMissense 类别、ClinVar 意义（202502）以及 VEP 注释（影响、生物类型、特征类型、变异类别、后果）来指定。

不要将此技能用于：

• 将基因符号、rsID 或转录本解析为坐标，或获取参考序列。请先解析坐标（参见下方的坐标溯源），然后使用解析后的 GRCh38 区域查询此技能。
• 除千人基因组计划外的任何其他队列——此技能仅服务于该数据集。

先决条件

1. uv：此技能的脚本使用 uv run 运行，该命令读取脚本的内联依赖元数据并配置一个临时环境。确保已安装 uv 并将其添加到 PATH 中（https://docs.astral.sh/uv/）。
2. 数据使用条款：千人基因组计划数据是开放的；用户应了解千人基因组计划 / IGSR 的数据使用条款（https://www.internationalgenome.org/data）。
3. 访问限制：无需 API 密钥、无需 .env 文件、也无需配置速率限制令牌。
4. 无需凭证

核心规则

• 使用包装器：始终执行提供的辅助脚本，而不是构建自己的客户端调用或网络请求。使用 scripts/onekgpd_api.py 进行变异/样本/亲缘关系查询（它处理连接、流式传输、分页和 JSON 序列化），使用 scripts/onekgpd_meta.py 进行样本/群体元数据查询（离线，参见 样本与群体元数据）。
• 坐标必须首先通过权威来源解析——参见坐标溯源。这是强制性的，而非建议性的。
• 先计数再选择：每个变异和样本选择都有一个配对的计数命令。首先调用计数命令以确定结果集的大小，然后仅在计数可控时进行选择。
• 合子型默认为两者：默认情况下，选择和计数命令包括杂合和纯合携带。当问题专门针对一种状态时，使用 --het-only 或 --hom-only 进行限制。（您无需传递任何参数即可获得两者。）
• 输出：脚本将完整的 JSON 写入文件（--output，默认为 /tmp/ 下），并将简洁的摘要打印到标准输出。不要将大型 JSON 文件读入上下文——使用 jq 或一个小的可弃用的 uv run python 片段来提取字段。

坐标溯源（强制步骤）

在任何基于区域的查询之前，请针对权威来源（例如 Ensembl）将基因或特征解析为 GRCh38 坐标，并使用这些解析后的坐标进行查询。组装版本必须明确，基因范围必须在使用前解析为精确位置。这是结构性的，而非建议性的：服务器端没有护栏来捕获错位的区域，因此未经验证的坐标将针对非预期位置返回结果，且不会报错。

# 首先使用权威来源将基因符号解析为 GRCh38 区域，
# 然后将验证后的坐标传递给下面的 OneKGPd 查询。

[!CAUTION] 该数据集是 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

注释过滤器（跨变异和样本选择/计数共享）

所有变异和样本选择命令（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 外显子组等位基因频率范围
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt：gnomAD v4.1 基因组等位基因频率范围
• --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：替代等位基因长度范围（碱基对）

[!NOTE] --alpha-missense-class 和 --alpha-missense-score-* 互斥（当设置了分数范围时，引擎会忽略类别）。--biallelic-only 和 --multiallelic-only 互斥。--exclude-males 和 --exclude-females 互斥。设置大于或等于其匹配 *-lt 范围的 *-gt 范围将定义一个空范围并将返回无结果。

[!NOTE] 等位基因频率字段使用 0.0 表示“该来源中不存在”。因此 --gnomad-exomes-af-gt 0 选择 存在于 gnomAD 外显子组中的变异；返回的 gnomad_exomes_af 为 0.0 表示变异不在 gnomAD 外显子组中。对于 gnomAD 基因组 AF 也是如此。 相反，--gnomad-exomes-af-lt / --gnomad-genomes-af-lt 边界 包括 未注释的变异：“AF < X in gnomAD” 包括 gnomAD AF = 0 的变异，即未注释的；将其与 --gnomad-*-af-gt 0 配对以要求在 gnomAD 中存在。

[!NOTE] am_score 为 0.0 表示未被 AlphaMissense 评分或注释——并不表示“良性”。真实的 AlphaMissense 分数总是大于 0。

快速开始

# 步骤 1. 通过权威来源解析坐标——参见坐标溯源。
#    示例：BRCA1: chr17:43044292-43170245
# 步骤 2. 评估结果集大小：有多少个体在此区域携带预测的可能致病的错义变异？
uv run scripts/onekgpd_api.py count-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/count.json
# 步骤 3. 如果计数可控，列出这些个体。
uv run scripts/onekgpd_api.py select-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/samples.json
# 步骤 4：对于这组个体，查看他们携带的实际变异。
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --samples HG03169,NA20506 \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

命令

每个命令将完整的 JSON 写入文件（--output PATH，默认为临时文件）并打印简洁的标准输出摘要。所有区域/样本命令共享：区域输入（--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 后果仅是过滤条件，不会返回。完整模式： 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 = 纯合参考型个体的数量。摘要会说明是哪种情况。
• 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 个群体。