onekgpd

OneKGPd: 1000 Genomes Project に対する個人単位のクエリ

スコープ

このスキルは、1000 Genomes Project データセット — GRCh38 アセンブリ上で全ゲノムシーケンスされた 3,202 人の拡張高カバレッジコホート — に対してクエリを実行します。すべての結果はこのコホートから取得され、スキルが返すサンプル名（たとえば HG00096 や NA21130）はその参加者を識別します。

クエリはコホートの個人ごとのジェノタイプデータに対して解決されます。これは相補的な 2 つのクラスの問いをサポートします。すなわち、ある領域内で保有されているバリアントを選択すること（コホート全体または指定した個人の集合内で）、および、与えられた条件に一致するバリアントを保有する個人を選択することです。バリアントの選択は、アレル頻度、予測される影響、臨床的意義、AlphaMissense 分類、および下記に挙げるその他のアノテーション軸でフィルタリングできます。名前を指定した 2 人の個人間の近縁度も利用できます。

バリアントが保有されているジェノタイプ状態 — ヘテロ接合またはホモ接合 — はクエリが指定できる条件です。結果はバリアントまたはサンプル名として返され、生のジェノタイプとしては返されません。

公開サービスは db.dnaerys.org:443 の TLS gRPC であり、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）。
• 名前を指定した 2 人の 1000 Genomes の個人間の近縁度 — 度数（一卵性双生児 / 1 親等 / 2 親等 / 3 親等 / 無関係）と KING 血縁係数の両方 — を判定する（kinship）。
• データセットの総計 — サンプル数、性別の内訳、バリアント数、アセンブリ — を取得する（dataset-info）。
• バリアントの選択は、KGP アレル頻度、gnomAD 4.1 エクソームおよび gnomAD 4.1 ゲノムのアレル頻度、AlphaMissense スコアおよび AlphaMissense クラス、ClinVar の意義（202502）、および VEP アノテーション（インパクト、バイオタイプ、フィーチャータイプ、バリアントクラス、コンシーケンス）によって指定できます。

このスキルを使用しない場合:

• 遺伝子シンボル、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. タイムアウト: ネットワークコマンドはデフォルトで RPC あたり --timeout 30 秒を使用します。正の有限値による上書きが可能です。ページネーションによって複数の RPC が実行され、再試行可能な失敗ではフェッチ全体が最大 3 回再試行されるため、これはコマンド全体のデッドラインではありません。

コアルール

• ラッパーを使用する: 独自のクライアント呼び出しやネットワークリクエストを構築するのではなく、常に提供されたヘルパースクリプトを実行してください。バリアント/サンプル/kinship クエリには scripts/onekgpd_api.py を使用し（接続、ストリーミング、ページネーション、JSON シリアライゼーションを処理します）、サンプル/集団メタデータには scripts/onekgpd_meta.py を使用してください（オフライン、サンプルと集団のメタデータを参照）。
• 座標は必ず最初に権威あるソースに対して解決する必要があります — 座標の出所を参照してください。これは必須であり、推奨ではありません。
• 選択する前にカウントする: すべてのバリアントおよびサンプルの選択には、対になるカウントコマンドがあります。まずカウントコマンドを呼び出して結果セットのサイズを把握し、カウントが扱いやすい場合にのみ選択してください。
• 接合性はデフォルトで両方: 選択およびカウントコマンドは、デフォルトでヘテロ接合とホモ接合の両方の保有を含みます。一方の状態に特化した質問の場合は、--het-only または --hom-only で絞り込んでください。（両方を取得するために何も渡す必要はありません。）
• 出力: スクリプトは完全な JSON をファイルに書き込み（--output、デフォルトは /tmp/ 以下）、簡潔なサマリーを stdout に出力します。大きな JSON ファイルをコンテキストに読み込まないでください — フィールドを抽出するには jq または小さな使い捨ての uv run python スニペットを使用してください。--page-size はすべてのページを取得しますが、すべてのバリアントを RAM に蓄積します。これはメモリが制限されたエクスポートではありません。まずクエリのサイズを見積もってください。
• 完全性を確認する: result_incomplete=true は、結果が決定的なゼロ/不在の主張を裏付けられないことを意味します。サービス復旧後に再実行してください。上限付きのバリアント選択では、truncated=true は制限に達し、クラスタ結果自体は完全であっても、さらに多くのレコードが存在する可能性があることを意味します。

座標の出所（必須の最初のステップ）

領域ベースのクエリの前に、遺伝子または特徴を権威あるソース（たとえば Ensembl や NCBI）に対して GRCh38 座標に解決し、それらの解決された座標でクエリしてください。入力は 1 ベース、両端を含む です。BED 区間 [start0, end0) は start=start0+1, end=end0 になります。ソースのアクセッション、アノテーションリリース、取得日を記録してください。遺伝子の境界は同じアセンブリ上でもアノテーションリリースによって異なる場合があります。アセンブリは明示されている必要があり、遺伝子範囲は使用前に正確な位置に解決されなければなりません。これは構造的なものであり、推奨ではありません。位置を誤った領域を検出するソース側のガードレールは存在しないため、検証されていない座標はエラーなしに意図しない位置の結果を生成します。

# 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,502 サンプルのパネルを拡張したものです。したがって、キャリア数は独立した観測数ではなく、コホート AF は集団の有病率の推定値ではありません。関連解析や頻度比較では、選択した集団と血縁関係の方針を文書化してください。解析セットを選択または監査する際には、同梱の家系メタデータと kinship を使用してください。詳細は IGSR コホートの発表をご覧ください。

アノテーションフィルター（バリアントおよびサンプルの選択／カウントで共通）

すべてのバリアント選択およびサンプル選択コマンド（count-variants、 select-variants、それらの -in-samples 形式、count-samples、select-samples） は、同じアノテーションフィルターを受け付けます。異なるフィルターフィールドは AND で結合され、1 つのフィールド内の複数の値は 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 impact、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 にも同じくスコア欠落時の注意を適用してください。

カテゴリカルなアノテーションはトランスクリプトをまたいで保持されます。consequence フィルターと impact フィルターを組み合わせても、それらが同じトランスクリプトを 記述していることにはなりません。amino_acids には複数の HGVSp エントリが含まれる ことがあります。汎用 gRPC サービスは正規のアノテーションを先頭に配置しますが、別個の MCP レイヤーはその出力を切り詰めます。トランスクリプト識別子を保持し、モデルの likely-pathogenic クラスを臨床診断や参加者の表現型として扱わないでください。

クイックスタート

# 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、または 1 回以上繰り返す --region CHR:START-END）、接合性フラグ （--het-only/--hom-only、デフォルトは両方）、および上記のアノテーションフィルターを 共有します。フラグごとの完全な表は references/onekgpd_commands.mdにあります。

バリアントを返すコマンド

select-* は一致するバリアントを返し、count-* は整数の件数を返します。

• count-variants — リージョン内のバリアントをコホート全体でカウントします。
• select-variants — リージョン内のバリアントをコホート全体で選択します。--limit N (ハードキャップ、デフォルト 200) または --page-size N (全件を ページ単位で取得) を使用します。この 2 つは同時に指定できません。サマリーは キャップに達すると 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 = ホモ接合リファレンスの個人数。これらの解釈には result_incomplete=false が必要です。そうでなければ variant_present は null になります。バリアント レコードがないことは、3,202 人の個人すべてがコール可能な 0/0 ジェノタイプを持つ証拠にはなりません。
• select-samples-hom-ref — そのポジションで 0/0 コールを持つ個人を一覧表示します。

血縁関係のコマンド

• kinship --sample1 NAME --sample2 NAME — 名前を指定した 2 人の個人間の 血縁関係: 度合い (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) と KING 血縁 係数 (phi_bwf)。

データセットメタデータのコマンド

• dataset-info — データセットの合計: samples_total (3,202)、女性/男性の内訳、 variants_total、assembly (GRCh38)、およびコホートの内訳。リージョンは 不要で、接続チェックも兼ねます。

サンプルと集団のメタデータ（オフライン）

集団、性別、家系、スーパー集団に関する質問には、2 つ目のスクリプト scripts/onekgpd_meta.py が、スキルにバンドルされたデータファイルから回答します — ネットワークも認証情報も座標も不要です。サンプル ID はバリアントコマンドが使用するものと同じ名前なので、2 つのレイヤーは連携します（たとえば、集団でコホートを選び、そのバリアントを照会する）。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: 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 フィルターフラグが受け入れる統制語彙の用語（consequence、impact、biotype、feature type、ClinVar significance、AlphaMissense class、variant class）。
• 現在の API 契約とライブチェックの範囲：コマンドリファレンス。
• 1000 Genomes Project / IGSR: https://www.internationalgenome.org/
• 1000 Genomes Project データセット オンライン: https://dnaerys.org/online/