用 AlphaGenome API…

当需要评估非编码遗传变异对基因表达、染色质可及性、组蛋白修饰、转录因子结合或剪接的功能影响时，可用 AlphaGenome API 进行打分、可视化并生成报告。

适用场景

解决思路

1. 前置准备：阅读 uv 技能并按其说明安装 uv 并确保其在 PATH 中；若工作区根目录不存在 .licenses/alphagenome_single_variant_analysis_LICENSE.txt，则先显著提醒用户查看 https://deepmind.google.com/science/alphagenome/ 的条款，再创建该文件记录通知文本与时间戳；确保家目录存在 .env 文件（不存在则创建）；通过 credentials 技能安全地检查并请求 ALPHAGENOME_API_KEY（可在上述网址注册）；可选地设置 ALPHAGENOME_GTF_PATH 指向本地 GTF feather 文件以加速基因/转录本查询，例如：echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env。
2. 核心规则：绝不要直接运行 python3 或 python3 -c，系统 Python 不一定有 pandas、numpy 等依赖，所有 Python 代码（脚本、临时分析文件、单行命令）都必须用 uv run 执行；不要 pip install 或新建 venv，uv 会自动管理隔离环境；基因/转录本查询必须离线，禁止使用 MyGene.info、Ensembl REST 等外部 API，改用 lookup_gene_info.py 配合本地 GTF，若失败则修复环境/路径而非切换外部 API；运行任何脚本前必须设置 ALPHAGENOME_API_KEY；若使用了本技能，需在输出中说明；生成分析报告时始终使用 docs/report-templates.md 中的模板，并包含发现扫描的 top hits 表格。
3. 环境与排错：所有脚本用 uv run <script_name> [args...] 执行；临时脚本用 uv run --project $SKILL_DIR /tmp/my_analysis.py --arg1 val1；首次运行会解析并安装依赖（约 10 秒），之后使用 ~/.cache/uv/ 缓存即时启动。常见问题处理：列名常为 gene_name（非 gene_symbol）和 output_type（非 modality），过滤前先检查 df.columns；大于 500kb 的基因（如 USH2A）会破坏 whole_gene 视图，改用 --view detail 或手动区域窗口；plot_components.Sashimi 不接受 strand 参数，应改为过滤输入 tracks；并非所有 tracks 都有 ontology_curie，过滤前检查 track.metadata.columns；若出现 exec: "python": executable file not found，确保使用 uv run 而非裸 python/python3；若 pandas 报 NotImplementedError（整数类型上不支持基于 iLocation 的布尔索引），用 np.flatnonzero(mask) 把布尔掩码转为整数索引；GTF Feather 文件列名为首字母大写（Feature、Start、End、Strand），与标准 GTF 不同，遇 KeyError 先检查 df.columns；score_variant 不接受 ontology_terms 参数，需手动检查返回的 AnnData 的 adata.var 列来过滤，而 predict_variant 可直接接受 ontology_terms；Sashimi 缩放要包含侧翼外显子以确保 skipping 弧线可见，不能只依赖 junction 重叠；prediction 返回的原始 Junction 对象可能只是简单 Interval，需用 junction_data.get_junctions_to_plot(predictions=..., name=...) 获取带 .k（丰度/分数）属性的对象；若 exec: uv: not found，按前置准备中的安装说明操作；若 uv 因私有 registry 报 401 Unauthorized，运行前设置 UV_INDEX_URL=https://pypi.org/simple。
4. 参考文档：docs/alphagenome-api.md（API 参考与代码模式）、docs/interpretation-guide.md（解读指南、分数幅度规则、ISM 与检查清单）、docs/report-templates.md（完整报告模板）、scripts/visualize_variant_effects.py（单变异可视化模板，含 Ref/Alt 对比与剪接）、docs/examples/splicing/（剪接分析示例）、docs/examples/model_limitation_RNU4ATAC/（ncRNA 结构限制案例）、docs/examples/polyadenylation_HBA2/（3' UTR/多聚腺苷化案例）、docs/examples/regulatory/（调控变异示例）、docs/examples/negative_result_GATA4/（阴性结果：数学伪影）、docs/examples/negative_result_TGFB3/（阴性结果：代理）、scripts/lookup_gene_info.py（基因与转录本查询）、scripts/resolve_ontology_terms.py（本体术语解析 UBERON/CL ID）。
5. 剪接缩放策略（混合方法）：基础区间为变异 +/- 1 个下游和上游外显子（结构上下文）；连接扩展为包含任何显著剪接连接（如跨多个外显子的外显子跳跃事件）的完整跨度；锚定强制确保锚定这些长连接的外显子完全可见。教训：简单固定窗口（如 2kb）或最近外显子逻辑常对跳跃事件失效，应始终用观察到的连接数据驱动缩放级别。
6. 广谱发现扫描：仅对 differential scorers 使用 score_variant 以发现意外的组织效应。代码模式：从 alphagenome.models 导入 dna_client、variant_scorers，从 alphagenome.data 导入 genome，导入 os、pandas、dotenv；用 dotenv.load_dotenv(os.path.expanduser('~/.env')) 加载环境变量；用 dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'), address='dns:///gdmscience.googleapis.com:443') 创建客户端；解析变异字符串如 "chr2:1234:A>C" 为 chrom、pos、ref、alt；使用支持的序列长度（如 2**20 以获得最佳性能）构造 genome.Interval(chrom, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2) 和 genome.Variant(chrom, pos, ref, alt)；scorers 取 variant_scorers.RECOMMENDED_VARIANT_SCORERS 中排除名称含 ACTIVE、CAGE、PROCAP 的项；调用 dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)；对每个返回的 score_adata 用 variant_scorers.tidy_scores([score_adata], match_gene_strand=True) 转为 DataFrame 并 concat；筛选 df['quantile_score'].abs() > 0.995 为显著，按 raw_score 绝对值降序排列，打印 biosample_name、gene_name、output_type、quantile_score、raw_score。
7. 疾病相关组织的扩展搜索：根据疾病上下文定义关键词（如 disease_keywords = ["liver", "hepatocyte"]），用 df['biosample_name'].str.contains('|'.join(disease_keywords), case=False, na=False) 过滤，按 raw_score 绝对值降序排列并打印前 20 行（biosample_name、output_type、raw_score、quantile_score）。
8. 工作流检查清单：Step 0 查看 Golden Examples（强制）；Step 1 创建输出文件夹并设置；Step 2 解析用户查询并调研；Step 3 解析组织与模态；Step 4 可视化并保存图表；Step 5 分析预测（查看图表，不写代码），强制先阅读 docs/interpretation-guide.md 再解读结果；Step 6 撰写报告并保存为 report.md（强制）；Step 7 自我批判（查看 report.md 验证链接与论断）；Step 8 将 report.md 制作成 artifact。
9. 多变异工作流：若指定多个变异，为每个变异分析生成子代理，然后将各自的 report.md 综合为单一报告。
10. 脚本参考：lookup_gene_info 用 GTF 数据做全面基因与转录本查询；resolve_ontology_terms 将生物学术语转为 UBERON/CL/EFO ID；visualize_variant_effects 做 REF/ALT 可视化（表达、调控、剪接）；analyze_ism 生成 In-Silico 诱变 SeqLogo；interpret_splicing 做定量剪接分析（delta 分数、连接）；visualize_genome_tracks 做区域基因组 track 可视化。

适用边界 · 注意事项

• 没有 ALPHAGENOME_API_KEY 或无法访问 AlphaGenome 服务时无法使用。
• 需要联网使用 MyGene.info、Ensembl REST 等外部 API 做基因查询的场景不适用（本技能要求离线查询）。
• 系统未安装 uv 且无法安装时无法按本技能方式运行 Python 代码。