alphagenome-variant-impact-score

AlphaGenome Variant Impact (AVI) 解析

scripts/alphagenome_atlas_avi.py を使用して、AlphaGenome Variant Impact（AVI）モデルで遺伝子バリアントの影響をスコアリングし、優先順位を付けます。

重要

研究目的でのみ使用し、臨床安全規則を遵守してください：AlphaGenome AVI Skill と、その基盤となる AlphaGenome モデル／Atlas は、厳密に研究用のツールです。出力にアクセスするには、臨床利用を禁じる利用規約が適用される AlphaGenome API キーが必要です。

1. 医療上の助言や臨床診断を行わないでください：このスキルまたは AlphaGenome Atlas の出力に基づき、医療上の助言、臨床診断、疾患管理戦略、治療の推奨を提供してはなりません。
2. 分子・機能の範囲に厳密に限定してください：AVI スコアが高いことは、分子／機能への影響が予測されることを示します（例：スプライシングの破綻、転写因子結合の変化、クロマチンアクセシビリティの変化、コード領域への影響）。すべての所見は分子メカニズムと生物学的アノテーションの観点から説明し、臨床診断や医学的結論として扱わないでください。
3. 診断に飛躍しないでください：機能への影響が大きいことから、臨床的な疾患の原因、浸透率、患者の予後を推測してはなりません。ユーザーが臨床または診断に関する質問をした場合は、AlphaGenome が研究用ツールであることを明確に伝え、回答を予測される分子的・機能的影響に限定してください。

重要

遺伝子アノテーションには必ず AlphaGenome GENCODE v46 GTF（scripts/alphagenome_atlas_avi.py gtf）を使用してください：遺伝子モデル、転写産物 ID、エクソン座標、CDS／UTR 領域、スプライスジャンクションのドナー／アクセプター境界を取得する場合は、必ず組み込みの scripts/alphagenome_atlas_avi.py gtf コマンドを使用してください。遺伝子アノテーションや転写産物座標の取得に、外部ソース（例：Ensembl REST API、UCSC、外部の GTF データベース、NCBI）を使用してはなりません。これにより、アノテーションがスコアおよびウェブサイトと一致します。

---

前提条件

scripts/alphagenome_atlas_avi.py は uv run を使用して実行します。

# Display CLI help:
uv run scripts/alphagenome_atlas_avi.py --help

ヒント

エージェントおよびプログラムによる実行形式：エージェントのワークフローで CLI を呼び出す場合は、標準出力の Markdown 表からフィールドを抽出するよりも、--format json またはファイルへの直接出力（-o <file>）を優先してください。これにより、構造化データを確定的に解析できます。

1. バリアントのクエリ（query）

スコアと 18 個の生物学的特徴の寄与度を確認するには、単一または複数のバリアントを 1-based の chr:pos:ref>alt 形式でクエリします。

# Query single variant with basic feature importances (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --format json

# Query variant with exact underlying Atlas track indices, biosamples, and target genes:
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --include_track_info --format json

# Query multiple variants and export full track info to a file (prevents stdout overflow):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" "chr22:36201698:A>C" \
  --include_track_info --format json -o query_results.json

• 出力サイズとリダイレクト：単一バリアントの表／JSON クエリはコンパクトです（約 1.0～1.5 KB）。$>3$ 個のバリアントをクエリする場合、または --include_track_info --format json（バリアントごとに約 3.9 KB を生成）を指定する場合は、コンテキストウィンドウの上限を超えないよう、必ず -o <file.json> または -o <file.tsv> を使ってファイルに直接出力してください。
• 一般的な実行時間：バリアント 1 個あたり約 0.5～1.0 秒（環境の起動を含めて合計約 12～15 秒）です。$>100$ 個のバリアントをまとめて呼び出すと、$>1$ 分かかります。

2. バリアントファイルのアノテーションと順位付け（annotate）

標準的な Ensembl VEP CSQ 形式の VCF（または CSV／TSV／Parquet）にアノテーションを付与します。

uv run scripts/alphagenome_atlas_avi.py annotate \
  --input test_data/example_variants.vcf \
  --output annotated_variants.vcf \
  --top_k 20 \
  --min_phred 15.0 \
  --top_output top_variants.json

• 出力サイズとリダイレクト：annotate は --output を使って、コールセット全体をディスクにストリーミング出力します（.vcf、.vcf.gz、.parquet、.tsv、.csv）。標準出力には、サイズに上限を設けた要約（候補上位の表と、モダリティ別の内訳上位 3 件、約 4.0～5.5 KB）が表示されます。後続のツールで候補上位のデータを機械可読形式で扱う必要がある場合は、--top_output <file.json> を使用してください。
• 一般的な実行時間とコールセットの規模：処理速度は毎秒約 10 バリアント（デフォルト）、トラック情報ありでは毎秒約 5 バリアントです。小規模なコールセット（$\le 100$ 個のバリアント）は約 15 秒かかります。$\ge 500$ 個のバリアントを含むコールセットでは、$>1$ 分間、出力なしで実行されます（例：1,000 個のバリアントは約 2～3 分、10,000 個のバリアントは約 20 分かかります）。

3. 飽和突然変異導入ウィンドウスキャン（region）

1-based の閉区間ゲノムウィンドウ（chr:start-end）をスキャンし、可能なすべての一塩基置換をスコアリングします（N bp のウィンドウでは $3 \times N$ 個のバリアント）。

uv run scripts/alphagenome_atlas_avi.py region \
  --region chr9:128225990-128226000 \
  --min_phred 15.0 \
  --top_k 20 \
  --output region_hotspots.tsv

• 出力サイズとリダイレクト：100 bp のウィンドウをスキャンすると 300 個の SNV（約 42 KB の TSV／約 105 KB の JSON）が生成され、1,000 bp のウィンドウでは 3,000 個の SNV（約 421 KB の TSV／約 1.06 MB の JSON）が生成されます。完全なデータセットを保存するには、必ず --output <file.tsv|parquet> を指定してください。標準出力に表示されるのは、上位 20 件の候補プレビューのみです。
• 一般的な実行時間：最大 1,000 bp（デフォルトの --max_window_size）について、gRPC 経由で事前計算済みの高密度スコアを照会する場合、1.5～3.0 秒です。

4. Atlas データベースのメタデータを調べる（metadata）

登録済みのスコアラー、生物学的特徴の定義 18 件、または実験トラックのカタログを出力または検索します。

# List all registered scorers:
uv run scripts/alphagenome_atlas_avi.py metadata --scorers --format json

# List the 18 biological feature attribution modalities:
uv run scripts/alphagenome_atlas_avi.py metadata --features --format json

# Search experimental tracks by query keyword with a controlled preview (top 20):
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --query "GATA1" --top_n 20

# Dump complete 9,440-track catalog to Parquet or TSV for offline search:
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --output atlas_tracks.parquet

• 出力サイズとリダイレクト：--features（約 1.3 KB）と --scorers の表（約 1.7 KB）は、いずれも 4 KB 未満です。実験トラックのカタログには 9,440 件のトラック（表で約 972 KB／JSON で約 2.55 MB）が含まれています。フィルタリングされていないトラックを標準出力に出力しないでください。絞り込んだ --query を指定するか、--top_n 20 を指定するか、--output atlas_tracks.parquet にエクスポートしてください。
• 一般的な実行時間：約 1.5～2.5 秒です。

5. 遺伝子構造とスプライスジャンクションを調べる（gtf）

GENCODE v46 の遺伝子アノテーションを照会し、ドナー／アクセプター座標を含む 1-based のエクソン境界を抽出して、標準的なスプライスジャンクションとエクソンスキッピングのスプライスジャンクション座標を計算します。

# Query MANE Select exon boundaries for a gene (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py gtf --gene CAPN3 --exons --format json

# Query canonical and exon-skipping splice junctions for a variant locus:
uv run scripts/alphagenome_atlas_avi.py gtf --variant "chr15:42387805:C>G" --junctions --format json

# Extract CDS and UTR segments for an Ensembl transcript ID:
uv run scripts/alphagenome_atlas_avi.py gtf --transcript_id ENST00000397163.8 --cds --utr --format json

• 出力サイズとリダイレクト：単一遺伝子の MANE Select クエリで --exons を指定した場合、出力はコンパクトです（2.5 KB 未満）。--all_transcripts（30～500 KB）、--region（$>50\text{ kb}$）、--format json を指定する場合や、エクソンが $>30$ 個ある遺伝子（例：TTN、DMD）を照会する場合は、必ず --output <file.tsv|parquet> にエクスポートするか、リダイレクト（> gtf_out.json）してください。
• 一般的な実行時間とメモリ使用量：318 MB の GENCODE v46 feather データセットを取り込みます（約 4.37 GB の RAM）。キャッシュ済みのクエリは 約 4～6 秒で実行されます。GCS からファイルをダウンロードするコールドスタートの実行は、社内／Cloudtop ネットワークでは 約 5～10 秒ですが、外部ネットワークでは 最大 60～90 秒かかることがあります。初回のダウンロード中にプロセスを早まって終了しないでください。

---

プログラムからの Python SDK の使用

Python からプログラムで AlphaGenome を照会する場合：

1. クライアントファクトリー：クライアントは必ず atlas.create(api_key) を使ってインスタンス化してください。atlas.AtlasClient() を直接インスタンス化しないでください（内部の gRPC スタブが必要です）。
2. 座標系：genome.Interval は 0-based の半開区間インデックス（[start, end)）を使用します。1-based の閉区間 chr:start_1_based-end_1_based を照会する場合は、start = start_1_based - 1、end = end_1_based を渡してください。
3. 単一バリアント：genome.Variant.from_str("chr:pos:ref>alt") は 1-based の位置座標を想定します。

import os
from alphagenome.atlas import atlas
from alphagenome.data import genome
import dotenv

dotenv.load_dotenv(os.path.expanduser('~/.env'))
client = atlas.create(os.environ['ALPHAGENOME_API_KEY'])

# Query 1-based closed interval chr11:5225727-5226575 using 0-based half-open [5225726, 5226575)
interval = genome.Interval(chromosome='chr11', start=5225726, end=5226575)
results = client.query_interval(
    interval,
    requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)

# Query single variant with 1-based coordinate
variant = genome.Variant.from_str('chr11:5225488:A>T')
variant_scores = client.query_variant(
    variant,
    requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)

---

出力スキーマとレスポンス構造

1. VCF CSQ および INFO タグスキーマ（annotate）

注釈付き VCF ファイルを書き込む際、以下の注釈が追加されます。

• Ensembl VEP CSQ フォーマット文字列： Allele|AVI_PHRED|AVI_RAW|AVI_QUANTILE|AVI_TOP_PERCENTILE|AVI_TOP_FEATURE
• サブフィールドの定義：
  • Allele（string）：代替アレルの塩基（例：A）。
  • AVI_PHRED（float）：キャリブレーション済みの Phred 影響スコア（$\text{Phred} = -10 \cdot \log_{10}(1.0 - \text{quantile})$）。範囲：[0.0, ~70.0]。 値が高いほど機能的影響が大きくなります。
  • AVI_RAW（float）：モデルによる連続値の生予測値。
  • AVI_QUANTILE（float）：キャリブレーション済みの上側分位点（$1 - \text{CDF}$）。 範囲：(0.0, 1.0]。
  • AVI_TOP_PERCENTILE（float）：ゲノム全体の SNV における上位パーセンタイル （$10^{-\text{Phred}/10} \times 100%$、例：上位 0.038% の場合は 0.0380）。
  • AVI_TOP_FEATURE（string）：寄与度が最も高い生物学的モダリティの表示名 （例：Splicing、AlphaMissense、ChIP-TF、 DNASE-seq、Cactus）。
• 単独の INFO タグ（--vep_csq_only を指定しない場合）：AVI_PHRED=Float、 AVI_RAW=Float、AVI_QUANTILE=Float、AVI_TOP_PERCENTILE=Float、 AVI_TOP_FEATURE=String。

2. 表形式および JSON レコードのスキーマ（query、region、--top_output）

JSON、TSV、CSV、または Parquet にエクスポートされる出力レコードには、以下のフィールドが含まれます。

• rank（integer、--top_output および region の表形式エクスポートに含まれます）： Phred の降順で並べた候補の順位（1 始まり）。
• variant（string）：chr:pos_1_based:ref>alt 形式のゲノムバリアント文字列 （例：chr9:128225994:G>A。座標は 1 始まりです）。
• chromosome（string）：chr 接頭辞付きのコンティグ名（例：chr9）。
• position（integer）：1 始まりのゲノム座標。
• ref（string）：参照アレルの塩基。
• alt（string）：代替アレルの塩基。
• avi_phred（float）：キャリブレーション済みの Phred スケールスコア。
• avi_raw（float）：モデルによる連続値の生スコア。
• avi_quantile（float）：上側分位点（$1 - \text{CDF}$）。
• top_percentile（float）：正確な上位パーセンタイル値（例：上位 0.34% の場合は 0.3421）。
• top_modality（string）：寄与度が最も高い生物学的モダリティの表示名 （例：Splicing、AlphaMissense、ChIP-TF）。
• top_feature_importance（float）：最上位モダリティの帰属重み（SHAP 値）。
• 任意の帰属重み（--include_features）：18 個の列 fi_<MODALITY>（例：fi_MERGED_SPLICING、fi_ALPHAMISSENSE、 fi_MAX_ABS_RNA_SEQ、fi_CACTUS_241_WAY）。
• 任意のトラックの由来情報（--include_track_info）： track_idx_<MODALITY>、track_name_<MODALITY>、 track_biosample_<MODALITY>、track_gene_<MODALITY>。

3. GTF クエリスキーマ（gtf）

gtf --format json で遺伝子構造をクエリすると、各転写産物オブジェクトには次の情報が含まれます。

• 遺伝子と転写産物のメタデータ：gene_name、gene_id、transcript_id、 transcript_type、chromosome、start、end、strand、is_mane_select、 num_exons（座標は1ベースの閉区間です）。
• エクソン配列（--exons）：
  • exon_number（int）：5' から 3' への転写産物の順序における、1ベースのエクソン番号。
  • start、end、width（int）：1ベースの閉区間で表したエクソンの座標と bp 単位の長さ。
  • acceptor、donor（int）：1ベースの5'スプライスアクセプターおよび3'スプライス ドナーの座標。
  • overlaps_variant（bool）：クエリ対象の変異部位と重複する場合は True です。
• ジャンクション配列（--junctions）：
  • type（string）：Canonical Intron {i} または Exon {k} Skipping。
  • upstream_exon、downstream_exon（int）：5' から 3' への転写産物の順序における、 1ベースの隣接エクソン番号。
  • junction_start、junction_end（int）：1ベースのゲノム上のドナーおよび アクセプターの座標。
  • intron_length（int）：イントロンの長さ（bp）。
  • score_id（string）：Atlas トラック比較用に構成されたトークン。
  • atlas_url（string）：Atlas トラック予測へのクリック可能なディープリンク。
• CDS および UTR 配列（--cds、--utr）：1ベースの閉区間で表した start、end、 width（int）。

---

スコア指標と解釈

• AVI Phred：キャリブレーション済みスコア（Phred = -10 * log10(1.0 - quantile)）：
  • Phred >= 40：ゲノム全体のすべての SNV のうち、予測される影響が上位 0.01%。
  • Phred >= 30：ゲノム全体のすべての SNV のうち、予測される影響が上位 0.10%。
  • Phred >= 20：ゲノム全体のすべての SNV のうち、予測される影響が上位 1.0%。
  • Phred >= 15：ゲノム全体のすべての SNV のうち、予測される影響が上位 3.16%。
  • Phred >= 10：ゲノム全体のすべての SNV のうち、予測される影響が上位 10.0%。
  • Phred < 10：ゲノム全体のすべての SNV のうち、下位 90%。
• 上位パーセンタイル：影響が同等以上のゲノム全体の SNV の正確な割合： Top Percentile = 10^(-Phred/10) * 100%（例：Phred 29.7 $\implies$ 上位 0.11%）。
• 上位モダリティ：最も寄与する生物学的特徴の帰属（metadata --features）。

---

可視化と Atlas ディープリンク

重要

変異スコアには Atlas ディープリンクが必須です：単一変異のクエリ、候補の順位付けテーブル、ゲノム領域スキャンのいずれであっても、変異の AVI スコアを報告、議論、または表示する場合は、各変異についてクリック可能な AlphaGenome Atlas へのディープリンクを必ず提示してください。

1. ユーザーコンテキストの優先：必ず最初にユーザーのコンテキスト（疾患、組織、関連する細胞種など）を優先してください。コンテキストがない場合は、query で --include_track_info を使用して、影響を与えているバイオサンプル、細胞株、オントロジー CURIE、トラックインデックスを特定してください。
2. スプライシングと RNA-seq の同時プロット必須ルール：スプライシング変異をプロットまたは可視化する場合は、構造的なスプライス破壊と、その結果生じる転写産物量の変化の両方を評価できるよう、スプライシングトラック（SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、 SPLICE_SITES）とあわせて、連続的な RNA-seq 発現量を必ずプロットしてください。
3. Atlas リンクの構築：URL の生成、レイアウト設定（lItems）、バイオサンプルのフィルタリング（f）、および /atlas/track-predictions の比較チャートリンクには、すべて alphagenome-atlas-website-links スキル（scripts/alphagenome_atlas_links.py）を使用してください。