alphagenome

AlphaGenome 与 AlphaGenome Atlas

AlphaGenome 是 DeepMind 的序列到功能模型：输入 1 Mb DNA，输出人类和小鼠数千条轨迹中 11 种检测类型的碱基对预测。AlphaGenome Atlas（于 2026-09-08 发布）是在 GRCh38 上对每一种可能的单核苷酸变化运行一次该模型，约 90 亿个变异；数据中包含一个排名数值——AlphaGenome Variant Impact (AVI) 分数、其全基因组百分位数，以及对其驱动因素的 18 路归因。两者均可通过一次 pip install alphagenome 和一个 API 密钥使用。

仅用于研究和理论建模。输出不得用于训练其他模型，也不得用于诊断程序或医疗决策。

何时使用哪种方式

你有	使用	原因
hg38 SNV（VCF、可信集合、最长约 1 kb 的区域）	通过 scripts/atlas_query.py 使用 Atlas	预计算、配额更高，包含 AVI 和归因
indel、小鼠变异、非参考背景、自定义评分器或窗口	通过 scripts/score_variants.py 或 Python 使用 model	Atlas 仅支持 SNV，且仅限 hg38
要解释的假设（哪种基序、哪种组织、REF 与 ALT 轨迹）	model predict_variant + 绘图、Atlas 轨迹分数、门户链接	探究作用机制，而不只是排名
GRCh37 坐标、rsID、未标准化的 indel	先使用 genomic-coordinates，然后再回来	基因组版本错误或 REF 颠倒会产生看似合理但错误的结果
ClinVar 断言、基因-疾病有效性、ACMG 框架	folklore-variant-evidence、database-lookup	AlphaGenome 只是证据之一，绝非最终结论
不使用 DeepMind 密钥的启动子／增强子／表达预测	genomic-intelligence	不同的提供方，无需密钥的演示层级

设置

uv pip install alphagenome                     # PyPI; tested on Python 3.12 and 3.13, alphagenome 0.9.0
export ALPHAGENOME_API_KEY="..."               # https://deepmind.google.com/science/alphagenome
cd skills/alphagenome/scripts
python atlas_query.py scorers                  # proves key + network in one call

切勿将密钥放在命令行或提交的文件中；脚本只会从环境中读取密钥。无效密钥会报错 ValueError: API key not valid，而不是权限错误。

坐标约定

• 变异采用 1-based 格式 chr:pos:ref>alt（chr22:36201698:A>C）。脚本和 genome.Variant.from_str 均接受 gnomAD（22-36201698-A-C）、GTEx（chr22_36201698_A_C_b38）和 Open Targets 的格式。
• 命令行中的区间采用 1-based 闭区间 chr:start-end；SDK 的 genome.Interval 采用 0-based 半开区间。脚本会进行转换。
• 人类基因组仅支持 GRCh38。Atlas 的键为 chr:pos:alt；REF 由参考基因组确定，因此如果 REF 和 ALT 颠倒，或使用 GRCh37，都会静默返回错误记录。使用 FASTA 检查 REF 后再信任查询结果。
• API 和门户均不接受 rsID。请先将其解析为坐标。
• 使用 chr 前缀；MT 会转换为 chrM。

Atlas 工作流

1. 使用 AVI 排序

python atlas_query.py avi --variant chr22:36201698:A>C chr9:128225994:G>A
python atlas_query.py avi --input candidates.vcf --min-phred 20 -o avi.tsv
python atlas_query.py avi --interval chr11:5225727-5226575 --top-k 25 -o hbb_window.tsv
python atlas_query.py avi --input credible_set.tsv --with-tracks -o avi_tracks.tsv

输出结果每个变体占一行：

列	含义
avi_raw	模型复合输出（18 个归因值的总和）
avi_cdf_quantile	与全基因组 SNV 相比的累积分位数（服务返回值）
avi_tail_quantile、avi_phred、avi_top_percent	tail = 1 - cdf，phred = -10 log10(tail)；Phred 20 = 前 1%，30 = 前 0.1%
top_feature、top_feature_value	绝对值最大的 SHAP 归因及其取值
fi_MERGED_SPLICING ... fi_IS_DELETION	全部 18 个归因值（键见 references/atlas.md）
top_track_*（使用 --with-tracks 时）	支撑排名最高特征的最强轨道：评分器、轨道、生物样本、ontology CURIE、基因、原始分数
atlas_url	门户网站上的变体深层链接
error	变体查询失败时的错误信息（indel、N 碱基、REF 错误），不会导致程序崩溃

Atlas 报告的建议是：排序，不要设阈值，并根据区域或应用选择阈值。致病性调控变体的 AVI 分档低于蛋白质截短或剪接基序变体，因此，使用单一的全基因组截断值，会漏掉本资源旨在发现的变体。

先查看归因值，再看分数。排名最高的是 MERGED_SPLICING 或 ALPHAMISSENSE，意味着机制与剪接或编码有关；排名最高的是 MAX_ABS_DNASE、MAX_ABS_CHIP_TF、MAX_ABS_RNA_SEQ，意味着可以通过轨道解析调控机制；排名最高的是 CACTUS_241_WAY 或 PHASTCONS_470_WAY，意味着分数主要由保守性决定，分子机制尚未解析。

2. 通过轨道解析机制

python atlas_query.py scorers                                   # what the server serves right now
python atlas_query.py tracks --scorer RNA_SEQ --query colon     # find ontology CURIEs
python atlas_query.py scores --variant chr22:36201698:A>C \
    --scorers RNA_SEQ DNASE SPLICE_SITE_USAGE --ontology UBERON:0001157 -o colon.tsv
python atlas_query.py scores --interval chr11:5225727-5226575 --scorers CHIP_TF --gene HBB -o hbb_tf.tsv

每个变体 × 轨道（RNA_SEQ、POLYADENYLATION、SPLICE_* 还包括基因）占一行，包含 raw_score，以及服务提供时的 quantile_score。轨道级评分器名称：ATAC、DNASE、CHIP_TF、CHIP_HISTONE、CAGE、PROCAP、RNA_SEQ、POLYADENYLATION、SPLICE_SITES、SPLICE_SITE_USAGE、SPLICE_JUNCTIONS、CONTACT_MAPS，以及 *_ACTIVE 变体；实时列表以 scorers 为准。应根据问题涉及的组织筛选，而不是按全基因组最大值筛选：9,440 条轨道意味着总有某处会出现极值。

3. 引导读者访问门户网站

python atlas_link.py variant chr22:36201698:A>C --biosample "colon" --modalities RNA_SEQ,DNASE,CHIP_TF
python atlas_link.py locus chr11:5225727-5226575 --tf GATA1
python atlas_link.py gene HBB --markdown

无需密钥，也无需网络。网站展示 AVI 轨道、所有生物样本的各模态热图、REF 与 ALT 的预测轨道，以及基序实例。请为报告中的每个变体附上链接。

在 Python 中

import os
from alphagenome.atlas import atlas
from alphagenome.data import genome

client = atlas.create(os.environ["ALPHAGENOME_API_KEY"], timeout=30)
scores = client.query_variant(
    genome.Variant.from_str("chr22:36201698:A>C"),
    requested_scorers=["AVI_SCORE", "AVI_SCORE_FEATURE_IMPORTANCE", "RNA_SEQ"],
    ontology_terms=["UBERON:0001157"],          # optional; ignored for scorers without ontology metadata
)
avi = scores["AVI_SCORE"]                        # AnnData: X (1,1) raw; layers['quantiles'] (1,1) cdf
fi = scores["AVI_SCORE_FEATURE_IMPORTANCE"]      # AnnData: X (1,18); var['name'] = feature keys
rna = scores["RNA_SEQ"]                          # AnnData: obs = variant x gene, var = tracks, X = log2 FC
client.query_interval(genome.Interval("chr11", 5225726, 5226575), requested_scorers=["AVI_SCORE"])

query_interval 会以 32 bp 为一块，返回每个位点的全部 3 个 SNV。窗口长度控制在约 1 kb（3,000 个变体）；若要查询更大的窗口，atlas_query.py 会拒绝，除非提高 --max-window。query_variants 会在首次查询失败时停止；该脚本一次查询一个变体，因此未命中的查询会成为 error 单元格。

模型工作流

为 Atlas 未收录的变体评分

python score_variants.py --variant chr22:36201698:A>C -o scores.tsv                   # 12 recommended scorers, 1 Mb
python score_variants.py --input indels.vcf --scorers RNA_SEQ SPLICE_SITE_USAGE \
    --ontology UBERON:0001157 --min-abs-quantile 0.99 -o colon.tsv
python score_variants.py --organism mouse --variant chr7:45000000:A>G --sequence-length 500KB
python score_variants.py --list-scorers
python score_variants.py --list-tracks --output-type RNA_SEQ --query liver -o tracks.tsv

输出是来自 variant_scorers.tidy_scores 的官方整洁表：每个变体 × 评分器 × 轨道（× 基因）占一行，包含 raw_score 和 quantile_score，并按 |raw| 排序。默认评分器为推荐的 12 个差异评分器；--include-active 会添加 7 个 *_ACTIVE 活性评分器。每个请求最多使用 20 个评分器。

from alphagenome.models import dna_client, variant_scorers
model = dna_client.create(os.environ["ALPHAGENOME_API_KEY"])
variant = genome.Variant.from_str("chr22:36201698:A>C")
interval = variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)
adatas = model.score_variant(interval, variant, variant_scorers=[variant_scorers.RECOMMENDED_VARIANT_SCORERS["RNA_SEQ"]])
df = variant_scorers.tidy_scores(adatas)         # filter df.ontology_curie afterwards; score_variant takes no ontology_terms

预测轨道并进行诱变分析

vo = model.predict_variant(interval, variant,
                           requested_outputs=[dna_client.OutputType.RNA_SEQ, dna_client.OutputType.DNASE],
                           ontology_terms=["UBERON:0001157"])
vo.reference.rna_seq.values, vo.alternate.rna_seq.values      # (1048576, n_tracks)

window = genome.Interval("chr20", 3_753_000, 3_753_400).resize(dna_client.SEQUENCE_LENGTH_16KB)
ism = model.score_ism_variants(interval=window, ism_interval=window.resize(256),
                               variant_scorers=[variant_scorers.CenterMaskScorer(
                                   requested_output=dna_client.OutputType.DNASE, width=501,
                                   aggregation_type=variant_scorers.AggregationType.DIFF_MEAN)])

支持的窗口长度：16 kb、100 kb、500 kb、1 Mb（2**14 至 2**20）；默认值为 1 Mb，远端增强子和接触图必须使用此长度。Ontology 术语为 CURIE（UBERON:0002048 表示肺，CL:0000084 表示 T 细胞）；可使用 --list-tracks 或 model.output_metadata(...).concatenate() 查找。绘图、基因注释（GCS 上的 GENCODE v46 Feather）、剪接和单倍型配方见：references/model-api.md。

解读数值

始终同时报告原始分数和分位数或 Phred 值，并注明评分器、track、生物样本 CURIE 和基因。raw_score 是评分器尺度上的效应大小（RNA_SEQ 是 log2 倍数变化：-1 表示减半）；quantile_score 是相对于常见变异的排名，并会在接近 0.99999 时饱和。分位数高于 0.99，但 |raw| < 0.1，是安静区域的标准伪象，意味着没有效应。无符号评分器（SPLICE_*、POLYADENYLATION、CONTACT_MAPS、*_ACTIVE）没有方向性。大多数变异都是良性的；“AlphaGenome 预测没有分子效应”就是完整的答案，而位于峰内、REF 和 ALT track 完全相同的变异并没有“破坏”任何东西。完整规则、组织匹配和报告清单：references/interpretation.md。

模型无法看到的内容：反式效应、非多聚腺苷酸化 RNA（如 RNU4-2 等 snRNA 基因）、训练数据中缺失的细胞类型、蛋白质层面的后果（AlphaMissense 会为此并入 AVI）、RNA 结构和 miRNA 生物学、二倍体剂量、发育时间，以及人和小鼠以外的物种。

限制、配额与条款

• Atlas：目前仅支持 GRCh38 SNV；论文中曾对 indel 评分，后续将提供。参考序列中的 N 碱基从未进行评分。
• 配额按密钥计算，未公开；文档说明 Atlas 的查询速率上限高于按需预测。客户端会重试暂时性的 RESOURCE_EXHAUSTED 和 UNAVAILABLE 错误（5 次尝试，退避时间最长为 60 s）。
• 访问层级（Atlas 报告）：AVI 分数也可通过 https://alphagenome.google/downloads 以宽松许可的 Tabix 文件下载；特征归因和剪接分数可通过非商业用途下载；所有其他原始 track 分数仅可通过 API 获取，且仅限非商业用途。商业 API 访问将“即将推出”，通过 Google Cloud Model Garden 提供。
• alphagenome 客户端采用 Apache-2.0 许可；模型权重和输出遵循 DeepMind 的条款。引用 Avsec 等人，Nature 649:1206（2026）及 Atlas 报告（Cheng、Taylor、Nicolaisen、Pan、Bycroft、Perino、Ward 等人，2026）。

参考资料

• references/atlas.md - Atlas 的内容、19 种评分器配置及其 track 数量、AVI 训练和 18 项特征、分位数到 Phred 的转换、客户端 API 和 AnnData 布局、错误映射、访问层级、门户 URL 语法、GTF 和下载位置。
• references/model-api.md - dna_client 速查表：坐标、序列长度、输出类型和 track 数量、本体元数据、预测和评分调用、推荐的评分器配置、ISM、基因注释、绘图。
• references/interpretation.md - 原始分数与分位数、AVI 阈值、组织匹配、阴性结果、模型盲点、坐标规范、报告清单。
• 脚本：scripts/atlas_query.py（Atlas：avi、scores、scorers、tracks）、scripts/score_variants.py（模型评分，--list-scorers、--list-tracks）、scripts/atlas_link.py（门户深层链接，离线）。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。凡是会改变结果的值，都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一个染色体或几千个细胞）上运行工作流。
4. 按照上述说明和参考资料 执行完整任务。
5. 验证结果。 解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并统一（lift over、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装版本中缺失	查阅已安装版本自身的文档（help()、--help、官方文档），进行适配，并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿捏造结果、参数、标识符、引用或统计数据。若无法运行或验证某项内容，请如实说明。
• 不要对超出统计数据支持范围的生物学意义作出解读；报告多重检验校正情况。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得同意。

相关技能

• shap：使用 SHAP 解释和审查机器学习预测。