alphagenome-atlas-website-links

AlphaGenome Atlas のディープリンクと URL 設定

AlphaGenome Atlas ウェブアプリケーション（https://deepmind.google.com/science/alphagenome/atlas）のディープリンクを作成し、検証します。

ベース URL：https://deepmind.google.com/science/alphagenome/atlas

重要

バリアントスコアを含む Atlas ディープリンクは必須です：遺伝的バリアントを提示、議論、またはスコアリングする際は、必ず AlphaGenome Atlas へのクリック可能なディープリンクを提示する必要があります。 scripts/alphagenome_atlas_links.py を使用して、リンクとテーブルの生成を自動化してください。

---

前提条件

# 1. Single Variant Exploration Link:
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. Genomic Locus / Interval Link:
uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 3. Format Candidate Variant Records Table (with embedded clickable links):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Construct Ref vs. Alt Track Predictions Link (/atlas/track-predictions):
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal"

---

2. URL クエリパラメーター

• q（文字列、必須）：主な検索対象です。1 始まりの両端を含む区間（chr11:5288500-5290500）、遺伝子シンボル（BRCA1）、Ensembl ID（ENSG00000012048）、または 1 始まりのバリアント（chr7:27170000:A>G）に対応しています。
• m（列挙型、任意）：表示モードです。遺伝子／バリアントの場合は entity、座標区間の場合は locus がデフォルトです。バリアントのクエリには variant を使用します。（指定可能な値：locus、entity、variant、motifs）。
• i（文字列、任意）：1 始まりで両端を含む chr:start-end 形式の、中央に配置するビューポートのズーム区間です（例：chr11:5289310-5289690）。モチーフの自動描画に必要です。
• f（文字列、任意）：KEY:VALUE 形式の、カンマ区切りのフィルター条件です（例： BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1）。 表示するヒートマップの行を制御します。
• lItems（文字列、任意）：レイアウト項目の並び、AVI スコアトラックの切り替え（avi）、セクションヒートマップ、固定トラックのリストです（例：avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>）。
• scores（文字列、任意）：/atlas/track-predictions ページで比較する ScoreId トークンのカンマ区切りリストです（例： <ScoreId1>,<ScoreId2>）。
• md（列挙型、任意）：トラック予測ビューで選択中のモダリティタブです（RNA_SEQ、SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、DNASE）。
• tpRenames（文字列、任意）：特定のスコア予測に対するカスタムタイトルの上書き指定です（ScoreId:CustomTitle）。
• tpLegendTitle（文字列、任意）：トラック予測チャートカードのカスタム凡例タイトルです（例：Predicted Gene Expression）。

重要

バリアントクエリの形式：q 内のバリアントは、必ず chr:pos_1_based:ref>alt 形式（例：chr7:27170000:A>G または URL エンコードされた chr7:27170000:A%3EG。位置は 1 始まり）を使用してください。コロン区切りのアレル（A:G）や dbSNP rsID は使用しないでください（rsID はサポートされていません）。

---

3. マルチモダリティのフィルタリングとアッセイグループの注意点（f）

フィルターグループとブール評価

f 内のフィルターは、主に次の 3 つの評価グループに対応します。

• Biosample グループ（BIOSAMPLE_NAME、BIOSAMPLE_TYPE）：AND ロジックで評価されます。
• Assay グループ（SCORER_MODALITY、ASSAY_TRANSCRIPTOR_FACTOR、 ASSAY_HISTONE_MARK）：OR ロジックで評価されます。
• Gene グループ（GENE_NAME）：OR ロジックで評価されます。

⚠️ マルチモダリティフィルターの必須ルール

RNA-seq トラックと DNase トラックには、転写因子コードがありません （transcriptionFactorCode === ""）。f に Assay グループの ASSAY_TRANSCRIPTOR_FACTOR フィルターのみが含まれている場合、RNA-seq と DNase のトラックは Assay の評価に失敗し、ヒートマップから非表示になります。

特定の ChIP-seq 転写因子と併せて RNA-seq と DNase のトラックを表示するには、f に SCORER_MODALITY:RNA-seq と SCORER_MODALITY:DNase を明示的に含めてください（scripts/alphagenome_atlas_links.py が自動的に処理します）。

f=BIOSAMPLE_NAME:<CellLine>,SCORER_MODALITY:RNA-seq,SCORER_MODALITY:DNase,ASSAY_TRANSCRIPTOR_FACTOR:<TF1>,ASSAY_TRANSCRIPTOR_FACTOR:<TF2>

---

4. レイアウト設定、AVI スコア、ピン留めトラック（lItems）

AVI スコアとモダリティセクションのプロット

• AVI バリアント影響トラック（avi）: lItems に avi を含めると、 区間またはバリアントのトップレベルの AlphaGenome Variant Impact スコアトラックが 表示されます。
• データベースのモダリティセクション（section:<MODALITY>）: セクションには、 該当するモダリティのすべてのトラックにわたる、ピン留めされていないヒートマップが 全体表示されます（例： section:RNA_SEQ、section:DNASE、section:CHIP_TF、section:ATAC、 section:CAGE）。

ピン留めトラックとモチーフインスタンス

メモ

トラック固有のモチーフに関するガイドライン: モチーフインスタンスと Contribution Weight Matrix（CWM）ロゴを含むピン留めされた Active-ISM トラックは、 個別のトラックについて明示的にリクエストされた場合にのみ追加してください。 モチーフオーバーレイに対応し、その効果が得られるトラックは限られています （該当する遺伝子座に関連する主要な ChIP-TF または RNA-seq トラックなど）。 標準的な探索用リンクでは、ピン留めトラックを使わず、デフォルトのセクション ヒートマップ（avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF）を 使用することを推奨します。

モチーフインスタンスと CWM ロゴは、塩基対解像度のピン留めトラックにのみ表示されます。 通常のセクションヒートマップでは、モチーフフットプリントは表示されません。

ピン留めトラックのキーのスキーマ

pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:heatmap:HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES:<TilesetId>

• <TrackMetadataName>：本番メタデータ proto の正確なトラック名を URL エンコードしたもの （スペースには %20 を使用）。
• <StrandNumber>：1（STRAND_POSITIVE）、2（STRAND_NEGATIVE）、3 （STRAND_UNSTRANDED）。
• <ScorerShortName>：RNA_SEQ、CHIP_TF、DNASE、ATAC、CAGE、 PROCAP、CHIP_HISTONE。
• HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES：Active-ISM モチーフレイヤーに必要な ソース識別子。
• <TilesetId>：サーバーが割り当てるタイルセット識別子（現在の本番環境では 17354278441953531756）。

読み込み時にモチーフを自動表示する手順

1. 対象となる特定のトラックにのみ、pinned:<PinnedKey> エントリーを lItems に追加します。
2. ビューポートの区間 i を塩基対解像度に設定します（$\le 1\text{ bp/px}$、 ウィンドウ幅 $\le 380\text{ bp}$）。
3. 細胞株と転写因子を指定して f を設定します。

---

5. トラック予測と Ref 対 Alt の比較（/atlas/track-predictions）

専用の /atlas/track-predictions ページでは、ゲノム領域における選択したスコアについて、 Reference アレルと Alternate アレルの機能プロファイル予測を比較できます。

• ルート： https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• 可視化：展開可能な折れ線グラフ（発現、クロマチンアクセシビリティ、 TF 結合）と Sashimi アークチャート（スプライスジャンクション）。

予測リンクの自動生成（scripts/alphagenome_atlas_links.py track-predictions）

トラック予測の URL は、必ず scripts/alphagenome_atlas_links.py track-predictions を使って生成してください。ドナー／アクセプターのスキップ座標、 鎖の向き（+/-）、遺伝子領域内外のサフィックス規則があるため、ScoreId 文字列を手動で 整形すると間違いが生じやすくなります。このスクリプトは、GENCODE v46 からの座標抽出、 トラックカタログの解決、URL の生成を自動で行います。

# Variant & Gene:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF \
  --tf CTCF

# Interval/Locus query:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --interval "chr15:41869312-42917888" \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF

track-predictions でサポートされる CLI オプション

• --variant、-v (string、デフォルト: None): chr:pos_1_based:ref>alt 形式のバリアント文字列。
• --gene、-g (string、デフォルト: None): 対象遺伝子シンボル（i= ビューポートを境界設定し、スプライスジャンクションを計算します）。
• --gene_id (string、デフォルト: None): 対象 Ensembl 遺伝子 ID（例: ENSG00000092529.26）。
• --interval、-i (string、デフォルト: None): chr:start-end 形式のゲノム区間ビューポート。
• --biosample、-b (string、デフォルト: Muscle_Skeletal): 対象バイオサンプルまたは組織のクエリ（例: Muscle_Skeletal、K562、Whole_Blood）。
• --modalities、-m (string、デフォルト: SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF): モダリティのカンマ区切りリスト（SPLICE_JUNCTIONS、RNA_SEQ、DNASE、ATAC、CHIP_TF）。
• --tf (string、デフォルト: CTCF): ChIP-TF トラックの転写因子名（例: CTCF、GATA1）。
• --rename (string、デフォルト: None): チャートカードにおけるカスタムトラック名の上書き。
• --legend_title (string、デフォルト: None): チャートカードのカスタム凡例ヘッダー。
• --format (enum、デフォルト: table): 出力形式（table、url、json）。

重要

スプライシングと RNA-seq の同時プロットに関する必須ルール: スプライシングバリアントの /atlas/track-predictions ディープリンクを生成する場合、プロットする場合、またはバリアント影響データを可視化する場合は、常に連続的な RNA-seq 発現をスプライシングトラック（SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、SPLICE_SITES）と並べてプロットしてください。スプライシング変異はしばしばクリプティックスプライスジャンクションを活性化し、ナンセンス媒介分解（NMD）を引き起こしたり、全体的な転写産物の産出量を変化させたりします。構造的なスプライス欠陥と、それに起因する全体的な転写産物量の変化の両方を観察するには、スプライスジャンクション（サシミアーク）と連続的な RNA-seq リードカバレッジを併せて評価する必要があります。

重要

トラック予測 URL には常に境界付きの i= を指定してください: scores= を省略したり、ゲノム区間（i=）を境界なしのままにしたりすると、Web アプリケーションがより広い遺伝子座全体にわたって一致するすべてのトラックをクエリしようとし、深刻なレイテンシやページのハングを引き起こします。alphagenome_atlas_links.py track-predictions は、i= を対象遺伝子または要求された区間に自動的に境界設定します。