onekgpd

OneKGPd：1000 Genomes Project 的个体级查询

范围

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

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

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

适用场景

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

• 在整个队列中，查找某个区域或一组区域内符合特定条件的变异（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 分数和 AlphaMissense 类别、ClinVar 临床意义（202502）以及 VEP 注释（影响、biotype、feature type、变异类别、后果）作为条件。

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

• 解析基因符号、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 密钥、.env 文件或速率限制令牌。
4. 无需凭据

核心规则

• 使用封装脚本：始终执行提供的辅助脚本，不要自行构造客户端调用或网络请求。变异、样本和亲缘关系查询请使用 scripts/onekgpd_api.py（它会处理连接、流式传输、分页和 JSON 序列化），样本和人群元数据请使用 scripts/onekgpd_meta.py（离线运行，参见样本和人群元数据（离线））。
• 必须先对照权威来源解析坐标——请参见 坐标溯源。这是强制要求，而非建议。
• 先计数，再筛选：每种变异和样本筛选都有对应的计数命令。先调用计数命令以了解结果集大小，只有计数结果在可处理范围内时才进行筛选。
• 合子性默认包括两种状态：筛选和计数命令默认同时包含杂合和纯合携带者。若问题只涉及其中一种状态，请使用 --het-only 或 --hom-only 缩小范围。（若要同时包含两种状态，无需传入任何选项。）
• 输出：脚本会将完整 JSON 写入文件（使用 --output，默认写入 /tmp/ 下），并向 stdout 打印简要摘要。不要将大型 JSON 文件读入上下文——请使用 jq 或简短的一次性 uv run python 代码片段提取字段。

坐标溯源（必须首先执行）

在进行任何基于区域的查询前，先通过权威来源（例如 Ensembl）将基因或特征解析为 GRCh38 坐标，并使用解析后的坐标进行查询。必须明确指定基因组组装版本，并在使用前将基因范围解析为精确位置。这是结构性要求，而非建议：数据源端没有防护措施来检测区域位置错误，因此未经验证的坐标会返回非预期位置的结果，且不会报错。

# 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

注释筛选器（适用于变异和样本的筛选与计数）

所有变异和样本筛选命令（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 范围， 则范围为空，不会返回任何结果。

说明

等位基因频率字段用 0.0 表示“该来源中不存在”。因此， --gnomad-exomes-af-gt 0 会筛选出 gnomAD 外显子组中存在的变异；返回的 gnomad_exomes_af 为 0.0 表示该变异不存在于 gnomAD 外显子组中。 gnomAD 基因组 AF 也遵循相同规则。相反，--gnomad-exomes-af-lt / --gnomad-genomes-af-lt 范围会包含 未注释变异：“gnomAD 中 AF < X”会包含 gnomAD AF = 0 的变异， 即未注释变异；可搭配 --gnomad-*-af-gt 0，要求变异在 gnomAD 中存在。

说明

am_score 为 0.0 表示未经 AlphaMissense 评分或注释，不代表 benign。 AlphaMissense 的实际分数始终大于 0。

快速入门

# Step 1. Resolve coordinates against an authoritative source — see Coordinate Provenance.
#    example: BRCA1: chr17:43044292-43170245
# 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 43044292 --end 43170245 \
  --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 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/samples.json
# Step 4: For that set of individuals, see the actual variants they carry.
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 标记为 true。
• 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 解答，数据文件已随 skill 一并提供——无需网络、无需凭据、无需坐标。样本 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 数量和三人组成员关系。多个值可重复使用 --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: for that set of individuals, see the actual variants they carry.
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 类别、变异类别）。
• 1000 Genomes Project / IGSR：https://www.internationalgenome.org/
• 1000 Genomes Project 数据集在线版：https://dnaerys.org/online/

Agent 操作流程

1. 检查环境。 确认网络访问、API 密钥（如需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，而不是猜测。
3. 先运行小规模版本。 获取一条已知记录，并在批量查询前检查响应格式。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数量，并记录数据库版本或访问日期。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	采用退避策略、批量发送请求并遵守速率限制，如实报告部分结果。
这些说明中的函数、标志或端点在已安装版本中缺失	查看已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿虚构 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直说。
• 切勿编造登录号、ID 或记录；如未找到，请报告“未找到”。
• 将此处与版本相关的细节视为可能已过时：请根据已安装版本的官方文档进行确认。
• 涉及付费、消耗共享 GPU 或云配额、访问个人或患者数据，或无法撤销的操作前，请先征求许可。