alphagenome-variant-impact-score

AlphaGenome 变异影响（AVI）分析

通过 scripts/alphagenome_atlas_avi.py 使用 AlphaGenome 变异影响（AVI）模型对遗传变异进行评分和优先级排序。

重要

仅供研究使用与临床安全规则：AlphaGenome AVI Skill 及其底层的 AlphaGenome 模型/Atlas 严格限于研究用途。访问输出需要 AlphaGenome API 密钥，且服务条款禁止将其用于临床。

1. 不得提供医疗建议或临床诊断：严禁根据此 Skill 或 AlphaGenome Atlas 的输出提供医疗建议、临床诊断、疾病管理策略或治疗建议。
2. 严格限定分子与功能层面的表述：AVI 高分反映的是预测的分子/功能影响（例如剪接受损、转录因子结合改变、染色质可及性变化或编码后果）。所有发现都应围绕分子机制和生物学注释进行表述，绝不能将其作为临床诊断或医学结论。
3. 不得作出诊断性推断：绝不能将较高的功能影响推断为临床疾病致因、外显率或患者预后。如果用户询问临床或诊断问题，请明确说明 AlphaGenome 是一种研究工具，并将回答限制在预测的分子和功能效应范围内。

重要

基因注释始终使用 AlphaGenome GENCODE v46 GTF（scripts/alphagenome_atlas_avi.py gtf）：检索基因模型、转录本 ID、外显子坐标、CDS/UTR 区域或剪接连接的供体/受体边界时，始终使用内置的 scripts/alphagenome_atlas_avi.py gtf 命令。不要查询外部来源（例如 Ensembl REST API、UCSC、外部 GTF 数据库或 NCBI）获取基因注释或转录本坐标。这可确保注释与评分及网站一致。

---

前提条件

使用 uv run 运行 scripts/alphagenome_atlas_avi.py：

# Display CLI help:
uv run scripts/alphagenome_atlas_avi.py --help

提示

Agent 与程序化执行格式：在 Agent 工作流中调用 CLI 时，优先使用 --format json 或直接导出文件（-o <file>），以便确定性地进行结构化解析，而不是从标准输出的 Markdown 表格中提取字段。

1. 查询变异（query）

以 1-based chr:pos:ref>alt 格式查询单个或多个变异，查看评分和 18 项生物学特征归因权重：

# Query single variant with basic feature importances (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --format json

# Query variant with exact underlying Atlas track indices, biosamples, and target genes:
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --include_track_info --format json

# Query multiple variants and export full track info to a file (prevents stdout overflow):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" "chr22:36201698:A>C" \
  --include_track_info --format json -o query_results.json

• 输出大小与重定向：单个变异的表格/JSON 查询内容较少（约 1.0–1.5 KB）。查询超过 3 个变异，或传入 --include_track_info --format json（每个变异会生成约 3.9 KB）时，始终使用 -o <file.json> 或 -o <file.tsv> 直接导出到文件，以免超出上下文窗口限制。
• 典型运行时间：每个变异约 0.5–1.0 s（包括环境启动在内总计约 12–15 s）。单次调用查询超过 100 个变异时，耗时超过 1 分钟。

2. 注释并对变异文件排序（annotate）

以标准 Ensembl VEP CSQ 格式注释 VCF（或 CSV/TSV/Parquet）：

uv run scripts/alphagenome_atlas_avi.py annotate \
  --input test_data/example_variants.vcf \
  --output annotated_variants.vcf \
  --top_k 20 \
  --min_phred 15.0 \
  --top_output top_variants.json

• 输出大小与重定向：annotate 会通过 --output 将完整变异集流式写入磁盘（.vcf、.vcf.gz、.parquet、.tsv、.csv）。标准输出会显示有界摘要（顶部候选表格和前 3 项模态细分，约 4.0–5.5 KB）。如果下游工具需要机器可读的顶部候选数据，请使用 --top_output <file.json>。
• 典型运行时间与变异集规模：处理速度约为每秒 10 个变异（默认）或每秒 5 个变异（包含 track info 时）。小型变异集（不超过 100 个变异）耗时约 15 s。包含至少 500 个变异的变异集运行超过 1 分钟时不会输出进度信息（例如，1,000 个变异耗时约 2–3 min；10,000 个变异耗时约 20 min）。

3. 饱和诱变窗口扫描（region）

扫描一个以 1 为起始的闭合基因组窗口（chr:start-end），为所有可能的单核苷酸替换评分（对于一个 $N$ bp 的窗口，共有 $3 \times N$ 个变体）：

uv run scripts/alphagenome_atlas_avi.py region \
  --region chr9:128225990-128226000 \
  --min_phred 15.0 \
  --top_k 20 \
  --output region_hotspots.tsv

• 输出大小与重定向：扫描一个 100 bp 的窗口会生成 300 个 SNV（约 42 KB TSV / 约 105 KB JSON），而扫描一个 1,000 bp 的窗口会生成 3,000 个 SNV（约 421 KB TSV / 约 1.06 MB JSON）。始终指定 --output <file.tsv|parquet> 以保存完整数据集；标准输出仅显示排名前 20 的候选项预览。
• 典型运行时间：通过 gRPC 查询预计算的密集评分，窗口长度不超过 1,000 bp 时（默认 --max_window_size）耗时 1.5–3.0 秒。

4. 查看 Atlas 数据库元数据（metadata）

导出或搜索已注册的评分器、18 种生物学特征定义或实验轨道目录：

# List all registered scorers:
uv run scripts/alphagenome_atlas_avi.py metadata --scorers --format json

# List the 18 biological feature attribution modalities:
uv run scripts/alphagenome_atlas_avi.py metadata --features --format json

# Search experimental tracks by query keyword with a controlled preview (top 20):
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --query "GATA1" --top_n 20

# Dump complete 9,440-track catalog to Parquet or TSV for offline search:
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --output atlas_tracks.parquet

• 输出大小与重定向：--features（约 1.3 KB）和 --scorers 表（约 1.7 KB）都小于 4 KB，可以安全输出。实验轨道目录包含 9,440 条轨道（表格约 972 KB / JSON 约 2.55 MB）。切勿将未筛选的轨道转储到标准输出；始终提供范围较窄的 --query、指定 --top_n 20，或导出到 --output atlas_tracks.parquet。
• 典型运行时间：约 1.5–2.5 秒。

5. 查看基因结构与剪接连接位点（gtf）

查询 GENCODE v46 基因注释，提取以 1 为起始的外显子边界及供体／受体坐标，并计算规范剪接和外显子跳跃剪接连接位点的坐标：

# Query MANE Select exon boundaries for a gene (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py gtf --gene CAPN3 --exons --format json

# Query canonical and exon-skipping splice junctions for a variant locus:
uv run scripts/alphagenome_atlas_avi.py gtf --variant "chr15:42387805:C>G" --junctions --format json

# Extract CDS and UTR segments for an Ensembl transcript ID:
uv run scripts/alphagenome_atlas_avi.py gtf --transcript_id ENST00000397163.8 --cds --utr --format json

• 输出大小与重定向：使用 --exons 查询单个基因的 MANE Select 信息时，输出内容较少（小于 2.5 KB）。使用 --all_transcripts（30–500 KB）、--region（$>50\text{ kb}$）、--format json，或查询外显子数超过 $30$ 个的基因（例如 TTN、DMD）时，始终导出到 --output <file.tsv|parquet> 或重定向（> gtf_out.json）。
• 典型运行时间与内存：载入 318 MB 的 GENCODE v46 feather 数据集（约占用 4.37 GB RAM）。缓存查询耗时 约 4–6 秒。冷启动时从 GCS 下载文件，在 corp/Cloudtop 网络上耗时 约 5–10 秒，但在外部网络上可能需要 60–90 秒。首次下载期间请勿过早终止进程。

---

以编程方式使用 Python SDK

使用 Python 以编程方式查询 AlphaGenome 时：

1. 客户端工厂：始终使用 atlas.create(api_key) 实例化客户端——不要直接实例化 atlas.AtlasClient()（它需要内部 gRPC stub）。
2. 坐标系统：genome.Interval 使用以 0 为起始的半开区间索引（[start, end)）。查询以 1 为起始的闭合区间 chr:start_1_based-end_1_based 时，传入 start = start_1_based - 1 和 end = end_1_based。
3. 单个变体：genome.Variant.from_str("chr:pos:ref>alt") 使用以 1 为起始的位置坐标。

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

dotenv.load_dotenv(os.path.expanduser('~/.env'))
client = atlas.create(os.environ['ALPHAGENOME_API_KEY'])

# Query 1-based closed interval chr11:5225727-5226575 using 0-based half-open [5225726, 5226575)
interval = genome.Interval(chromosome='chr11', start=5225726, end=5226575)
results = client.query_interval(
    interval,
    requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)

# Query single variant with 1-based coordinate
variant = genome.Variant.from_str('chr11:5225488:A>T')
variant_scores = client.query_variant(
    variant,
    requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)

---

输出模式与响应结构

1. VCF CSQ 和 INFO 标签架构（annotate）

写入已注释的 VCF 文件时，会注入以下注释：

• Ensembl VEP CSQ 格式字符串： Allele|AVI_PHRED|AVI_RAW|AVI_QUANTILE|AVI_TOP_PERCENTILE|AVI_TOP_FEATURE
• 子字段定义：
  • Allele（字符串）：替代等位基因碱基（例如 A）。
  • AVI_PHRED（浮点数）：经过校准的 Phred 影响分数（$\text{Phred} = -10 \cdot \log_{10}(1.0 - \text{quantile})$）。范围：[0.0, ~70.0]。 数值越高 = 功能影响越大。
  • AVI_RAW（浮点数）：模型预测的原始连续值。
  • AVI_QUANTILE（浮点数）：经过校准的尾部分位数（$1 - \text{CDF}$）。 范围：(0.0, 1.0]。
  • AVI_TOP_PERCENTILE（浮点数）：在全基因组 SNV 中所处的最高百分位 （$10^{-\text{Phred}/10} \times 100%$，例如 Top 0.038% 对应 0.0380）。
  • AVI_TOP_FEATURE（字符串）：贡献度最高的生物学模态的显示名称 （例如 Splicing、AlphaMissense、ChIP-TF、DNASE-seq、Cactus）。
• 独立 INFO 标签（除非指定 --vep_csq_only）：AVI_PHRED=Float、 AVI_RAW=Float、AVI_QUANTILE=Float、AVI_TOP_PERCENTILE=Float、 AVI_TOP_FEATURE=String。

2. 表格和 JSON 记录架构（query、region、--top_output）

导出为 JSON、TSV、CSV 或 Parquet 的输出记录包含以下字段：

• rank（整数，存在于 --top_output 和 region 的表格导出中）： 按 Phred 分数降序排列的候选项排名，从 1 开始。
• variant（字符串）：基因组变异字符串，格式为 chr:pos_1_based:ref>alt （例如 chr9:128225994:G>A，坐标从 1 开始）。
• chromosome（字符串）：带 chr 前缀的 contig 名称（例如 chr9）。
• position（整数）：从 1 开始的基因组坐标。
• ref（字符串）：参考等位基因碱基。
• alt（字符串）：替代等位基因碱基。
• avi_phred（浮点数）：经过校准的 Phred 标度分数。
• avi_raw（浮点数）：模型分数的原始连续值。
• avi_quantile（浮点数）：尾部分位数（$1 - \text{CDF}$）。
• top_percentile（浮点数）：精确的最高百分位值（例如 Top 0.34% 对应 0.3421）。
• top_modality（字符串）：贡献度最高的生物学模态的显示名称 （例如 Splicing、AlphaMissense、ChIP-TF）。
• top_feature_importance（浮点数）：最高模态的归因权重（SHAP 值）。
• 可选归因权重（--include_features）：18 个列 fi_<MODALITY>（例如 fi_MERGED_SPLICING、fi_ALPHAMISSENSE、 fi_MAX_ABS_RNA_SEQ、fi_CACTUS_241_WAY）。
• 可选轨道来源信息（--include_track_info）： track_idx_<MODALITY>、track_name_<MODALITY>、 track_biosample_<MODALITY>、track_gene_<MODALITY>。

3. GTF 查询架构（gtf）

使用 gtf --format json 查询基因结构时，每个转录本对象包含：

• 基因和转录本元数据：gene_name、gene_id、transcript_id、 transcript_type、chromosome、start、end、strand、is_mane_select、 num_exons（坐标为从 1 开始的闭区间）。
• 外显子数组（--exons）：
  • exon_number（int）：按转录本 5' 至 3' 顺序排列、从 1 开始计数的外显子索引。
  • start、end、width（int）：从 1 开始的闭区间外显子坐标及长度（bp）。
  • acceptor、donor（int）：从 1 开始的 5' 剪接受体和 3' 剪接供体坐标。
  • overlaps_variant（bool）：若与查询突变位点重叠，则为 True。
• 连接位点数组（--junctions）：
  • type（string）：Canonical Intron {i} 或 Exon {k} Skipping。
  • upstream_exon、downstream_exon（int）：按转录本 5' 至 3' 顺序排列的上游和下游侧翼外显子编号（从 1 开始）。
  • junction_start、junction_end（int）：从 1 开始的基因组供体和受体坐标。
  • intron_length（int）：内含子长度（bp）。
  • score_id（string）：构造的 Atlas 轨道比较令牌。
  • atlas_url（string）：指向 Atlas 轨道预测的可点击深层链接。
• CDS 和 UTR 数组（--cds、--utr）：从 1 开始的闭区间 start、end、width（int）。

---

分数指标与解读

• AVI Phred：校准后的分数（Phred = -10 * log10(1.0 - quantile)）：
  • Phred >= 40：所有全基因组 SNV 预测影响中的前 0.01%。
  • Phred >= 30：所有全基因组 SNV 预测影响中的前 0.10%。
  • Phred >= 20：所有全基因组 SNV 预测影响中的前 1.0%。
  • Phred >= 15：所有全基因组 SNV 预测影响中的前 3.16%。
  • Phred >= 10：所有全基因组 SNV 预测影响中的前 10.0%。
  • Phred < 10：所有全基因组 SNV 中的后 90%。
• 前百分位：影响相同或更大的全基因组 SNV 的精确百分比：前百分位 = 10^(-Phred/10) * 100%（例如，Phred 29.7 $\implies$ 前 0.11%）。
• 主要模态：排名最高的生物学特征归因（metadata --features）。

---

可视化与 Atlas 深层链接

重要

AVI 深层链接的强制要求：每当报告、讨论或展示某个变异的 AVI 分数时（无论是单个变异查询、候选变异排名表还是基因组区域扫描），对于每个变异，都必须始终提供指向 AlphaGenome Atlas 的可点击深层链接。

1. 优先考虑用户上下文：始终优先考虑用户提供的上下文（例如疾病、组织或相关细胞类型）。若未提供上下文，使用 query 搭配 --include_track_info，以发现驱动因素生物样本、细胞系、本体 CURIE 和轨道索引。
2. 剪接与 RNA-seq 强制共同绘图规则：每当绘制或可视化剪接变异时，始终在剪接轨道旁绘制连续的 RNA-seq 表达量（SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、SPLICE_SITES），以评估剪接结构破坏及由此导致的转录本丰度变化。
3. Atlas 链接构建：所有 URL 生成、布局配置（lItems）、生物样本筛选（f）及 /atlas/track-predictions 比较图表链接，都使用 alphagenome-atlas-website-links 技能（scripts/alphagenome_atlas_links.py）。