AlphaGenome Atlas 深層連結與 URL 配置

為 AlphaGenome Atlas 網頁應用程式（https://deepmind.google.com/science/alphagenome/atlas）建構並驗證深層連結。

基礎 URL：https://deepmind.google.com/science/alphagenome/atlas

[!IMPORTANT] 強制性 Atlas 深層連結與變異評分：每當呈現、討論或評分基因變異時，你必須同時提供可點擊的深層連結至 AlphaGenome Atlas。使用 scripts/alphagenome_atlas_links.py 來自動產生連結與表格。

必要條件

# 1. 單一變異探索連結：
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. 基因組位點 / 區間連結：
uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 3. 格式化候選變異記錄表格（含內嵌可點擊連結）：
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. 建構參考序列 vs 替代序列軌道預測連結 (/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-based 封閉式區間（chr11:5288500-5290500）、基因符號（BRCA1）、Ensembl ID（ENSG00000012048）或 1-based 變異（chr7:27170000:A>G）。
m (列舉, 選用)：檢視模式。基因/變異預設為 entity，座標區間預設為 locus。變異查詢請使用 variant。（允許值：locus、entity、variant、motifs）。
i (字串, 選用)：以 1-based 封閉式 chr:start-end 格式（例如 chr11:5289310-5289690）定義的置中視窗縮放區間。自動化 motif 渲染時為必要參數。
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 token 逗號分隔列表（例如 <ScoreId1>,<ScoreId2>）。
md (列舉, 選用)：軌道預測檢視上的活躍模態分頁選擇器（RNA_SEQ、SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、DNASE）。
tpRenames (字串, 選用)：特定分數預測的自訂標題覆寫（ScoreId:CustomTitle）。
tpLegendTitle (字串, 選用)：軌道預測圖表卡片的自訂圖例標題（例如 Predicted Gene Expression）。

[!IMPORTANT] 變異查詢格式：q 中的變異必須嚴格使用 chr:pos_1_based:ref>alt 格式（例如 chr7:27170000:A>G 或 URL 編碼後的 chr7:27170000:A%3EG，其中位置為 1-based）。請勿使用冒號分隔的等位基因（A:G）或 dbSNP rsID（不支援 rsID）。

3. 多模態過濾與檢測分組陷阱 (`f`)

過濾分組與布林評估

f 中的過濾器映射到三個主要評估組：

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_TRANSCRIPTOR_FACTOR 過濾器，則 RNA-seq 和 DNase 軌道會無法通過檢測評估，並從熱圖中隱藏。

要在特定 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 變異影響分數軌道。
資料庫模態章節 (section:<MODALITY>)：章節會渲染該模態下所有匹配軌道的完整未固定熱圖（例如 section:RNA_SEQ、section:DNASE、section:CHIP_TF、section:ATAC、section:CAGE）。

固定軌道與 Motif 實例

[!NOTE] 特定軌道的 Motif 指南：具有 motif 實例和貢獻權重矩陣 (CWM) 標誌的固定 Active-ISM 軌道，僅應在針對個別軌道特別要求時才加入。只有有限的軌道子集（例如與該位點相關的關鍵 ChIP-TF 或 RNA-seq 軌道）支援並受益於固定的 motif 疊加。對於標準探索連結，預設使用不帶固定軌道的章節熱圖（avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF）是較佳做法。

Motif 實例和 CWM 標誌僅在固定的序列軌道（ACTIVE_ISM 或 RAW_SCORES，而非 REF_SCORES）上以鹼基對解析度渲染。一般的章節熱圖不會觸發 motif 足跡渲染。

固定軌道鍵結構

pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source>

原始 URL 查詢字串中的 lItems 項目範例：

pinned:EFO:0002067%20TF%20ChIP-seq%20GATA1:3:CHIP_TF:ACTIVE_ISM

<TrackMetadataName>：來自 metadata proto 的精確軌道名稱（例如 EFO:0002067 TF ChIP-seq GATA1），在原始 URL 查詢字串中需要百分比編碼（%20 代表空格）（或透過 urllib.parse.urlencode 傳遞時不編碼）。
<StrandNumber>：1（STRAND_POSITIVE）、2（STRAND_NEGATIVE）、3（STRAND_UNSTRANDED）。
<ScorerShortName>：RNA_SEQ、CHIP_TF、DNASE、ATAC、CAGE、PROCAP、CHIP_HISTONE（或僅限 RAW_SCORES 的模態：SPLICE_SITES、SPLICE_SITE_USAGE、SPLICE_JUNCTIONS、POLYADENYLATION、CONTACT_MAPS）。
<Source>：熱圖 tileset 來源識別碼：ACTIVE_ISM（活性加權 _TIMES_ACTIVE motif 足跡和 CWM 序列標誌）、RAW_SCORES（原始 ISM 變異分數軌道，也會在所有模態中渲染原始 ISM motif 足跡和 CWM 序列標誌）或 REF_SCORES（連續參考訊號線圖，不含序列字母或 motif）。校準和 AVI 軌道無法固定，且傳統的 :heatmap:...:<TilesetId> 後綴會導致軌道查詢失敗並被忽略。

載入時自動顯示 Motif 的配方

僅針對特定的目標軌道，將格式為 pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source> 的項目（使用 ACTIVE_ISM 代表活性加權 motif，或 RAW_SCORES 代表原始 ISM motif）直接附加到 lItems。
將視窗區間 i 設定為鹼基對解析度（$\ge 2\text{ px/bp}$，視窗 $\le 380\text{ bp}$）。
使用細胞株和轉錄因子配置 f。

5. 軌道預測與參考序列 vs 替代序列比較 (`/atlas/track-predictions`)

專用的 /atlas/track-predictions 頁面比較基因組視窗中選定分數的 Reference 和 Alternate 等位基因之間的預測功能譜：

路徑： https://deepmind.google.com/science/alphagenome/atlas/track-predictions
視覺化：展開的線圖（表現量、染色質可及性、轉錄因子結合）和 Sashimi 弧線圖（剪接點）。

自動化預測連結產生（`scripts/alphagenome_atlas_links.py track-predictions`）

始終使用 scripts/alphagenome_atlas_links.py track-predictions 建構軌道預測 URL。由於受質體/受質體跳過座標、鏈方向（+/-）以及基因/非基因後綴規則的影響，手動 ScoreId 字串格式化容易出錯。該腳本會自動處理 GENCODE v46 的座標提取、軌道目錄解析和 URL 合成。

# 變異與基因：
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

# 區間/位點查詢：
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 (字串, 預設值：None)：以 chr:pos_1_based:ref>alt 格式指定的變異字串。
--gene, -g (字串, 預設值：None)：目標基因符號（會界定 i= 視窗範圍並計算剪接點）。
--gene_id (字串, 預設值：None)：目標 Ensembl 基因 ID（例如 ENSG00000092529.26）。
--interval, -i (字串, 預設值：None)：以 chr:start-end 格式指定的基因組區間視窗。
--biosample, -b (字串, 預設值：Muscle_Skeletal)：目標生物樣本或組織查詢（例如 Muscle_Skeletal、K562、Whole_Blood）。
--modalities, -m (字串, 預設值：SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF)：以逗號分隔的模態列表（SPLICE_JUNCTIONS、RNA_SEQ、DNASE、ATAC、CHIP_TF）。
--tf (字串, 預設值：CTCF)：ChIP-TF 軌道的轉錄因子名稱（例如 CTCF、GATA1）。
--rename (字串, 預設值：None)：圖表卡片中的自訂軌道重新命名覆寫。
--legend_title (字串, 預設值：None)：圖表卡片的自訂圖例標題。
--format (列舉, 預設值：table)：輸出格式（table、url、json）。

[!IMPORTANT] 強制性剪接與 RNA-seq 共同繪製規則：當產生 /atlas/track-predictions 深層連結、繪製或視覺化剪接變異的變異影響資料時，始終將連續的 RNA-seq 表現量與剪接軌道（SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、SPLICE_SITES）一起繪製。剪接突變經常會活化隱蔽的剪接點並引發無意義介導的衰減 (NMD) 或改變總轉錄產出量；需要同時評估剪接點（sashimi 弧線圖）和連續的 RNA-seq 讀取覆蓋度，才能觀察到結構性剪接缺陷以及由此產生的整體轉錄豐度變化。

[!IMPORTANT] 在軌道預測 URL 中始終提供有邊界的 i=：省略 scores= 或讓基因組區間（i=）無邊界會導致網頁應用程式嘗試查詢更廣泛位點中的所有匹配軌道，從而導致嚴重延遲或頁面掛起。alphagenome_atlas_links.py track-predictions 會自動將 i= 邊界設定為目標基因或請求的區間。

google-deepmind/science-skills

science-skills 是什麼？

在你喜歡的 AI 中提問

說明文件