使用 AlphaGenome 進行變異分析
先決條件
-
uv：閱讀uv技能並遵循其設定指示，以確保uv已安裝並在 PATH 中。 -
使用者通知：如果
.licenses/alphagenome_single_variant_analysis_LICENSE.txt尚未存在於工作區根目錄，則 (1) 顯著通知使用者查閱 https://deepmind.google.com/science/alphagenome/ 上的條款，然後 (2) 建立包含通知文字和時間戳記的檔案。 -
.env檔案：確保家目錄中存在.env檔案。如果不存在，請建立一個。 -
ALPHAGENOME_API_KEY：此技能需要 API 金鑰才能運作。您可以在 https://deepmind.google.com/science/alphagenome/ 註冊金鑰。 如果此技能與使用者的請求相關，您必須使用
credentials技能中的安全憑證協定來檢查並要求此金鑰。 -
ALPHAGENOME_GTF_PATH（可選）：透過指向本地 GTF feather 檔案的副本來加速基因/轉錄本查詢，而不是從 GCS 下載：echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
核心規則
- 絕對不要直接執行
python3或python3 -c。 系統的 Python 不一定有 pandas、numpy 和其他關鍵依賴項。始終使用uv run來執行所有 Python 程式碼 —— 包括腳本、臨時分析檔案和單行程式碼。不要嘗試pip install或建立新的虛擬環境——uv會自動管理隔離環境。 - 僅限離線：絕對不要使用外部 API（例如 MyGene.info、Ensembl REST）進行基因/轉錄本查詢。請使用
lookup_gene_info.py搭配本地 GTF。如果失敗，請修復環境/路徑，不要改用外部 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
[!NOTE] 第一次調用會解析並安裝依賴項（約 10 秒）。 後續執行使用快取的環境並立即啟動。快取位於
~/.cache/uv/。
常見問題
- 列名：
tidy_scores和中繼資料通常使用gene_name（而不是gene_symbol）和output_type（而不是modality）。在過濾之前，始終檢查df.columns。 - 大基因：大於 500kb 的基因（例如
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，請確保您使用的是uv run而不是單純的python/python3。 - NotImplementedError (pandas)：