alphagenome-single-variant-analysis

AlphaGenome を使用したバリアント解析

前提条件

1. uv：uv スキルを読み、セットアップ手順に従って、uv がインストールされ、PATH に設定されていることを確認してください。

2. ユーザーへの通知：.licenses/alphagenome_single_variant_analysis_LICENSE.txt がワークスペースのルートディレクトリに存在しない場合は、（1）https://deepmind.google.com/science/alphagenome/ の利用条件を確認するようユーザーに目立つ形で通知し、次に（2）通知内容とタイムスタンプを記録したファイルを作成してください。

3. .env ファイル：ホームディレクトリに .env ファイルが存在することを確認してください。存在しない場合は作成してください。

4. ALPHAGENOME_API_KEY：このスキルを機能させるには API キーが必要です。

   https://deepmind.google.com/science/alphagenome/ でキーを登録できます。このスキルがユーザーのリクエストに関連すると思われる場合は、credentials スキルの安全な認証情報プロトコルを必ず使用して、このキーの有無を確認し、必要に応じて要求してください。

5. ALPHAGENOME_GTF_PATH（任意）：GCS からダウンロードする代わりに、GTF feather ファイルのローカルコピーを指定すると、遺伝子／転写産物の検索を高速化できます。

   echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
   

基本ルール

• python3 や python3 -c を直接実行しないでください。 システムの Python に pandas、numpy などの主要な依存関係が必ずしも含まれているとは限りません。スクリプト、アドホックな解析ファイル、ワンライナーを含む、すべての Python コードの実行には必ず uv run を使用してください。pip install を試したり、新しい仮想環境を作成したりしないでください。uv が隔離された環境を自動的に管理します。
• オフラインのみ：遺伝子／転写産物の検索に外部 API（MyGene.info、Ensembl REST など）を絶対に使用しないでください。ローカル GTF を使って lookup_gene_info.py を実行してください。失敗した場合は、環境やパスを修正し、外部 API に切り替えないでください。
• API キーが必要です：スクリプトを実行する前に、ALPHAGENOME_API_KEY を設定してください。
• 通知：このスキルを使用した場合は、その旨を出力に記載してください。
• レポート形式：解析レポートの生成には必ず docs/report-templates.md のテンプレートを使用し、ディスカバリースキャンの上位ヒットの表を含めてください。

環境のセットアップとトラブルシューティング

Python 環境

すべてのスクリプトは uv run を使って実行してください。uv が適切な依存関係を備えた隔離仮想環境を管理します。

uv run <script_name> [args...]

アドホックなスクリプト（一時ファイルに保存したインライン解析コードなど）では、短い名前ではなく、完全なパスを指定してください。

uv run --project $SKILL_DIR /tmp/my_analysis.py --arg1 val1

メモ

初回の呼び出しでは、依存関係の解決とインストールに約 10 秒かかります。 2 回目以降の実行では、キャッシュ済みの環境を使用するため、すぐに起動します。キャッシュは ~/.cache/uv/ に保存されます。

よくある問題

• 列名：tidy_scores とメタデータでは、gene_symbol ではなく gene_name、modality ではなく output_type が使われることがよくあります。フィルタリングの前に、必ず df.columns を確認してください。
• 大きな遺伝子：500 kb を超える遺伝子（例：USH2A）では、whole_gene ビューが正常に動作しません。代わりに --view detail または手動で指定した領域ウィンドウを使用してください。
• Sashimi のストランドエラー：plot_components.Sashimi は strand 引数を直接受け付けません。代わりに、入力トラックをフィルタリングしてください。
• KeyError: 'ontology_curie'：すべてのトラックに ontology_curie があるわけではありません。フィルタリングの前に、track.metadata.columns を確認してください。
• Python のパス：exec: "python": executable file not found が発生した場合は、単独の python／python3 ではなく uv run を使用していることを確認してください。
• NotImplementedError（pandas）：「iLocation based boolean indexing on an integer type is not available」。これは、新しい pandas バージョンで、整数インデックスの DataFrame に対して .iloc とブールマスクを使用すると発生します。解決方法：np.flatnonzero(mask) を使って、ブールマスクを整数インデックスに変換してください。
• GTF Feather の大文字と小文字の区別：AlphaGenome の GTF Feather ファイルでは、標準的な GTF ファイルとは異なり、列名が大文字で始まります（Feature、Start、End、Strand）。KeyError が発生した場合は、必ず df.columns を確認してください。
• score_variant のオントロジーフィルタリング：score_variant は引数として ontology_terms を受け付けません。返された AnnData オブジェクトの adata.var 列を確認し、手動でフィルタリングする必要があります。一方、predict_variant は ontology_terms を直接受け付けます。
• Sashimi のズームロジック：「スキップ」アークが見えるようにするには、ジャンクションとの重なりだけに頼らず、ズーム範囲に両側のエクソンを含めてください。
• ジャンクションスコア：prediction から取得した生の Junction オブジェクトは、単純な Interval の場合があります。.k（存在量／スコア）属性を持つオブジェクトを取得するには、junction_data.get_junctions_to_plot(predictions=..., name=...) を使用してください。
• uv が見つからない：exec: uv: not found が発生した場合は、前提条件のインストール手順に従ってください。
• レジストリの認証エラー（401）：プライベートレジストリに対して uv が 401 Unauthorized で失敗する場合は、スクリプトの実行前に UV_INDEX_URL=https://pypi.org/simple を設定してください。

参考資料

• alphagenome-api.md — API リファレンスとコード パターン
• interpretation-guide.md — 解釈ガイド、 スコアの大きさのルール、ISM、チェックリスト。
• report-templates.md — レポートテンプレート一式
• scripts/visualize_variant_effects.py — 単一バリアントの可視化テンプレート（Ref/Alt 比較、スプライシング）。
  • スプライシングのズーム戦略：最適な視認性を得るため、ハイブリッドアプローチを使用します。
    1. 基本区間：バリアントの下流および上流にあるエクソンをそれぞれ 1 つ含めます（構造的コンテキスト）。
    2. ジャンクションの拡張：有意なスプライシングジャンクション（複数のエクソンにまたがるエクソンスキッピングイベントなど）の全範囲を含むように拡張します。
    3. アンカーの確保：これらの長いジャンクションをアンカーするエクソンが完全に表示されるようにします。教訓：単純な固定ウィンドウ（例：2kb）や最寄りのエクソンを使うロジックでは、スキッピングイベントをうまく捉えられないことがよくあります。ズームレベルは、必ず観測されたジャンクションデータに基づいて決定してください。
• examples/splicing/ — スプライシング解析の例
• examples/model_limitation_RNU4ATAC/ — ncRNA 構造の制約に関するケーススタディ
• examples/polyadenylation_HBA2/ — 3' UTR／ポリアデニル化に関するケーススタディ
• examples/regulatory/ — 調節バリアントの例
• examples/negative_result_GATA4/ — 否定的な結果（数学的アーティファクト）
• examples/negative_result_TGFB3/ — 否定的な結果（代理指標）
• scripts/lookup_gene_info.py — 遺伝子と 転写産物の検索
• scripts/resolve_ontology_terms.py — オントロジー用語の解決（UBERON/CL ID）

---

コードパターン

広範な探索スキャン

予期しない組織への影響を見つけるため、差分スコアラーのみを対象に score_variant を使用します。

from alphagenome.models import dna_client
from alphagenome.models import variant_scorers
from alphagenome.data import genome
import os
import pandas as pd
import dotenv

# Load environment variables from ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# Setup API Key and Client
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# Define Variant (example)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# Use supported sequence length (e.g., 2**20 for optimal performance)
SEQ_LENGTH = 2**20
interval = genome.Interval(chrom, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2)
variant = genome.Variant(chrom, pos, ref, alt)

scorers = [
    variant_scorers.RECOMMENDED_VARIANT_SCORERS[m]
    for m in variant_scorers.RECOMMENDED_VARIANT_SCORERS
    if "ACTIVE" not in m and "CAGE" not in m and "PROCAP" not in m
]

print(f"Scoring variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Process and Display Results
all_dfs = []
for score_adata in scores_list:
    df = variant_scorers.tidy_scores([score_adata], match_gene_strand=True)
    if df is not None:
        all_dfs.append(df)

if all_dfs:
    df = pd.concat(all_dfs)
    significant = df[df['quantile_score'].abs() > 0.995]
    ranked = significant.sort_values('raw_score', key=abs, ascending=False)
    print("Top Significant Hits:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

疾患関連組織の拡張検索

# Define keywords based on disease context
disease_keywords = ["liver", "hepatocyte"]

# Filter for any match
mask = df['biosample_name'].str.contains('|'.join(disease_keywords), case=False, na=False)

relevant_hits = df[mask].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Extended Analysis (Keywords: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

ワークフローチェックリスト

Variant Analysis Progress:
- [ ] Step 0: Review Golden Examples (MANDATORY)
- [ ] Step 1: Create Output Folder and Setup
- [ ] Step 2: Parse User Query & Research
- [ ] Step 3: Resolve Tissues & Modalities
- [ ] Step 4: Visualize & Save Plots
- [ ] Step 5: Analyze Predictions (view plots, no code). MANDATORY: Read [interpretation-guide.md](docs/interpretation-guide.md) before interpreting results.
- [ ] Step 6: Write Report, save it as `report.md` (MANDATORY)
- [ ] Step 7: Self-Critique (view `report.md` to verify links & claims)
- [ ] Step 8: Make artifact out of `report.md`

---

複数バリアントのワークフロー

複数のバリアントが指定されている場合は、サブエージェントを起動して各バリアントを 解析し、その後、それぞれの report.md をまとめて単一のレポートを作成します。

スクリプトリファレンス

スクリプト	用途
lookup_gene_info	GTF データを使った包括的な遺伝子と転写産物の検索
: : :
resolve_ontology_terms	生物学的用語 → UBERON/CL/EFO ID
visualize_variant_effects	REF/ALT の可視化（発現、調節、
: : スプライシング） :
analyze_ism	In-Silico Mutagenesis SeqLogo の生成
interpret_splicing	定量的なスプライシング解析（差分スコア、
: : ジャンクション） :
visualize_genome_tracks	領域のゲノムトラック可視化