onekgpd

OneKGPd: 1000 Genomes Project に対する個人レベルクエリ

スコープ

このスキルは、1000 Genomes Project データセット（GRCh38アセンブリ上の高深度シーケンスコホート、3,202人の全ゲノムシーケンス個人）をクエリします。すべての結果はこのコホートから導出され、スキルが返すサンプル名（例：HG00096 や NA21130）はその参加者を識別します。

クエリは、コホートの個人ごとのジェノタイプデータに対して解決されます。これにより、2つの補完的な質問クラスをサポートします。すなわち、領域内で保有されるバリアントの選択（コホート全体または指定された個人セット内）、および、特定の基準に一致するバリアントを保有する個人の選択です。バリアント選択は、アレル頻度、予測される影響、臨床的意義、AlphaMissense分類、および以下にリストするその他のアノテーション軸でフィルタリングできます。2人の名前付き個人間の血縁関係も利用可能です。

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

使用するタイミング

このスキルは以下の場合に使用してください:

• コホート全体で、何らかの基準に一致する領域または複数の領域内で保有されるバリアントを見つける（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. 認証情報は不要

コアルール

• ラッパーを使用する: 常に提供されているヘルパースクリプトを実行し、独自のクライアント呼び出しやネットワークリクエストを構築しないでください。バリアント/サンプル/血縁関係クエリには 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
• 2人の名前付き個人間の血縁関係（程度 + 係数） → kinship
• データセットの合計（サンプル数、性別内訳、バリアント総数、アセンブリ） → dataset-info

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

すべてのバリアントおよびサンプル選択コマンド（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 インパクト、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）

[!NOTE] --alpha-missense-class と --alpha-missense-score-* は相互に排他的です（スコア範囲が設定されるとエンジンはクラスを無視します）。--biallelic-only と --multiallelic-only は相互に排他的です。--exclude-males と --exclude-females は相互に排他的です。*-gt 範囲を対応する *-lt 範囲以上に設定すると、空の範囲が定義され、何も返されません。

[!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 範囲は、アノテーションなしのバリアントを含みます: 「gnomAD で AF < X」は、gnomAD AF = 0 のバリアント、すなわちアノテーションなしのバリアントを含みます。gnomAD での存在を必須にするには、--gnomad-*-af-gt 0 と組み合わせてください。

[!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、または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 = ホモ接合リファレンスの個人の数。サマリーはどのケースかを示します。
• 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の集団があります。

[truncated for translation]