google-deepmind/science-skills

使用 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（可选）：通过指向本地 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)：“iLocation based boolean indexing on an integer type is not available”。当在较新版本的 pandas 中对整数索引的 DataFrame 使用布尔掩码与 .iloc 时，会出现此错误。修复：使用 np.flatnonzero(mask) 将布尔掩码转换为整数索引。
• GTF Feather 大小写敏感性：与标准 GTF 文件不同，AlphaGenome GTF Feather 文件使用大写列名（Feature、Start、End、Strand）。如果遇到 KeyErrors，请始终检查 df.columns。
• score_variant 本体过滤：score_variant 不接受 ontology_terms 作为参数。您必须通过检查 adata.var 列来手动过滤返回的 AnnData 对象。相比之下，predict_variant 确实直接接受 ontology_terms。
• Sashimi 缩放逻辑：为确保“跳跃”弧可见，请将缩放范围扩大到包括侧翼外显子，而不是仅仅依赖连接重叠。
• 连接分数：来自 prediction 的原始 Junction 对象可能是简单的 Intervals。使用 junction_data.get_junctions_to_plot(predictions=..., name=...) 来检索具有 .k（丰度/分数）属性的对象。
• 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

# 从 ~/.env 加载环境变量
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# 设置 API 密钥和客户端
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# 定义变异（示例）
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# 使用支持的序列长度（例如 2**20 以获得最佳性能）
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"评分变异 {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# 处理并显示结果
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("最佳显著命中：")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

疾病相关组织的扩展搜索

# 根据疾病上下文定义关键词
disease_keywords = ["liver", "hepatocyte"]

# 过滤任何匹配
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--- 扩展分析（关键词：{disease_keywords}） ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

工作流检查清单

变异分析进度：
- [ ] 步骤 0：审阅黄金示例（必需）
- [ ] 步骤 1：创建输出文件夹并设置
- [ ] 步骤 2：解析用户查询与研究
- [ ] 步骤 3：解析组织与模态
- [ ] 步骤 4：可视化并保存图表
- [ ] 步骤 5：分析预测（查看图表，无需编码）。必需：在解释结果之前阅读 [interpretation-guide.md](docs/interpretation-guide.md)。
- [ ] 步骤 6：编写报告，保存为 `report.md`（必需）
- [ ] 步骤 7：自我批评（查看 `report.md` 以验证链接和声明）
- [ ] 步骤 8：从 `report.md` 创建制品

---

多变异工作流

如果指定了多个变异，则生成子代理以运行每个变异分析，然后将每个 report.md 综合成一个报告。

脚本参考

脚本	目的
lookup_gene_info	使用 GTF 数据进行全面的基因和转录本查找
resolve_ontology_terms	生物学术语 → UBERON/CL/EFO ID
visualize_variant_effects	REF/ALT 可视化（表达、调控、剪接）
analyze_ism	原位诱变 SeqLogo 生成
interpret_splicing	定量剪接分析（delta 分数、连接）
visualize_genome_tracks	区域基因组轨道可视化