用途
onekgpd 用于在参与者个体层面查询 1000 Genomes Project 数据集。该数据集包含扩展的高覆盖度队列，共 3,202 名全基因组测序个体，基于 GRCh38 组装。所有结果均来自该队列，返回的样本名（如 HG00096、NA21130）即该队列的参与者标识。
主要能力
技能支持两类互补的查询：一是选取某区域内（全队列或指定个体集合）携带的变异；二是选取携带符合给定条件变异的个体。可以按以下注释维度过滤：1000 Genomes 等位基因频率、gnomAD 4.1 外显子组与基因组等位基因频率、AlphaMissense 评分与分类、ClinVar 意义（202502）、VEP 注释（影响、生物类型、特征类型、变异类别、后果）等。还可限定杂合或纯合携带状态（默认两者兼含）。此外支持：查询单一位点上的纯合参考个体；查询两个指定个体之间的亲缘关系（等级：同卵双生/一级/二级/三级/无关，以及 KING 亲缘系数）；获取数据集总量（样本数、性别分布、变异数、组装版本）。
结果以变异或样本名形式返回，不返回原始基因型。
适用场景
- 查找某区域或区域内符合条件、在全队列中携带的变异（select-variants）。
- 查找指定个体集合中携带的符合条件的变异（select-variants-in-samples）。
- 查找某区域中携带符合条件的变异的 1000 Genomes 个体（select-samples）。
- 统计携带特定变异的个体数量（count-samples）。
- 限定仅杂合、仅纯合，或两者兼含地查询变异。
- 识别在某单一位点上为纯合参考的个体（select-samples-hom-ref）。
- 判断两个指定个体间的亲缘等级与 KING 亲缘系数（kinship）。
- 获取数据集总量信息（dataset-info）。
使用方式
脚本通过 uv run 运行，需确保 uv 已安装并在 PATH 中。数据为开放数据，无需 API 密钥、.env 文件或速率限制令牌。
核心规则：始终使用提供的辅助脚本而非自行构造网络请求；scripts/onekgpd_api.py 处理变异/样本/亲缘查询（负责连接、流式传输、分页与 JSON 序列化），scripts/onekgpd_meta.py 处理样本与群体元数据（离线）。区域查询前必须先对照权威来源（如 Ensembl）将基因或特征解析为 GRCh38 坐标，并明确组装版本。每个选择操作都有配套的计数命令，应先计数以评估结果集大小，再执行选择。输出为完整 JSON 文件（--output 指定，默认存于 /tmp/），stdout 打印简要摘要；不要将大型 JSON 读入上下文，可用 jq 或小型 Python 片段提取字段。
快速开始示例：
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
命令概览
返回变异的命令：count-variants（区域内全队列变异计数）、select-variants（区域内全队列选取变异，支持 --limit 或 --page-size）、count-variants-in-samples 与 select-variants-in-samples（限定 --samples 的对应版本）。每个返回变异包含 22 个键：chr、start、end、ref、alt、af、ac、an、hom_samples、het_samples、mis_samples 及其 fx/mxy 分性别版本、gnomad_exomes_af、gnomad_genomes_af、am_score、amino_acids、biallelic。ClinVar 意义与 VEP 后果仅作过滤条件，不在结果中返回。
返回样本的命令：count-samples、select-samples（支持 --skip/--limit）。纯合参考命令：count-samples-hom-ref（-1 表示该位点无变异，0 表示有变异但无纯合参考个体，>0 为纯合参考人数）、select-samples-hom-ref。亲缘命令：kinship --sample1 NAME --sample2 NAME。元数据命令：dataset-info。
离线元数据脚本 scripts/onekgpd_meta.py 提供：sample-metadata、list-populations（26 个群体）、list-superpopulations（5 个超级群体 AFR/AMR/EAS/EUR/SAS）、population-stats、superpopulation-summary、select-samples-by-population（可与 select-variants-in-samples 组合使用）。
限制
该技能仅服务 1000 Genomes Project 数据集，不适用于其他队列。技能不负责将基因符号、rsID 或转录本解析为坐标，也不获取参考序列，需自行先解析坐标。数据集仅为 GRCh38，使用 GRCh37 坐标或错误区域会在不报错的情况下返回非预期位置的结果。--alpha-missense-class 与 --alpha-missense-score-* 互斥；--biallelic-only 与 --multiallelic-only 互斥；--exclude-males 与 --exclude-females 互斥；*-gt 大于等于对应 *-lt 会定义空范围。等位基因频率字段中 0.0 表示在该来源中不存在；am_score 为 0.0 表示未被 AlphaMissense 评分或注释，并非良性。