onekgpd

OneKGPd：1000 Genomes Project の個人レベルクエリ

対象範囲

このスキルは、GRCh38 アセンブリ上で全ゲノムシーケンスを実施した3,202人の拡張高カバレッジコホートである、1000 Genomes Project のデータセットをクエリします。すべての結果はこのコホートから取得されます。また、このスキルが返すサンプル名（たとえば、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 exome および gnomAD 4.1 genome の対立遺伝子頻度、AlphaMissense Score と AlphaMissense Class、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 に基づいて解決し、解決した座標でクエリしてください。アセンブリを明示する必要があります。また、遺伝子範囲は使用前に正確な位置へ解決する必要があります。これは構造上の必須事項であり、推奨ではありません。誤った領域を検出する情報源側のガードレールはないため、未検証の座標を指定すると、エラーにならず意図しない位置の結果が返されます。

# 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
• 名前を指定した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）

メモ

--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への存在を必須にするには、--gnomad-*-af-gt 0も併せて指定してください。

メモ

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、または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の集団があります。集団名とスーパー集団名は、短縮コードまたは正式名称で大文字・小文字を区別せず照合されます。サンプル 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 フィルターフラグで使用できる統制語彙の用語 （consequence、impact、biotype、feature type、ClinVar significance、 AlphaMissense class、variant class）。
• 1000 Genomes Project / IGSR：https://www.internationalgenome.org/
• 1000 Genomes Project データセット（オンライン）：https://dnaerys.org/online/

エージェントの作業手順

1. 環境を確認します。 ネットワークにアクセスできること、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問します。
3. まず小規模に実行します。 既知のレコードを1件取得し、一括クエリの前にレスポンス形式を確認します。
4. 上記の手順と参考情報を使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決できること、レコード数が報告されていること、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の点を明示します。

次のことが起きた場合	対応
HTTP 429 または 5xx エラー	バックオフを伴うレート制限を守り、リクエストをバッチ処理し、部分的な結果を正直に報告します。
これらの手順にある関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を決して捏造しません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に前提を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しません。実行または検証できないことがあれば、明確に伝えます。
• アクセッション番号、ID、レコードを決して捏造しません。見つからない場合は「見つかりません」と報告します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 金銭が発生する操作、共有 GPU またはクラウドクォータを消費する操作、個人データまたは患者データを扱う操作、元に戻せない操作の前には、確認を求めます。