alphagenome-atlas-website-links

AlphaGenome Atlas 深度链接与 URL 配置

为 AlphaGenome Atlas Web 应用构建并验证深度链接 （https://deepmind.google.com/science/alphagenome/atlas）。

基础 URL：https://deepmind.google.com/science/alphagenome/atlas

重要

必须使用带变体评分的 Atlas 深度链接：在展示、讨论或评分遗传变体时，必须始终提供指向 AlphaGenome Atlas 的可点击深度链接。 使用 scripts/alphagenome_atlas_links.py 自动生成链接和表格。

---

前置条件

# 1. Single Variant Exploration Link:
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. Genomic Locus / Interval Link:
uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 3. Format Candidate Variant Records Table (with embedded clickable links):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Construct Ref vs. Alt Track Predictions Link (/atlas/track-predictions):
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal"

---

2. URL 查询参数

• q（字符串，必填）：主要搜索目标。支持 1-based 闭区间（chr11:5288500-5290500）、基因符号（BRCA1）、Ensembl ID（ENSG00000012048）或 1-based 变体（chr7:27170000:A>G）。
• m（枚举，可选）：视图模式。基因/变体默认为 entity，坐标区间默认为 locus。变体查询使用 variant。（可选值：locus、entity、variant、motifs）。
• i（字符串，可选）：居中视口缩放区间，采用 1-based 闭区间 chr:start-end 格式（例如 chr11:5289310-5289690）。自动渲染 motif 时必填。
• f（字符串，可选）：以逗号分隔的筛选谓词，采用 KEY:VALUE 格式（例如 BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1）。 控制热图中显示的行。
• lItems（字符串，可选）：布局项目序列、AVI 评分轨道开关（avi）、分区热图和固定轨道列表（例如 avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>）。
• scores（字符串，可选）：用于 /atlas/track-predictions 页面比较的 ScoreId 令牌列表，以逗号分隔（例如 <ScoreId1>,<ScoreId2>）。
• md（枚举，可选）：轨道预测视图中的活动模态标签选择器（RNA_SEQ、SPLICE_JUNCTIONS、SPLICE_SITE_USAGE、DNASE）。
• tpRenames（字符串，可选）：特定评分预测的自定义标题覆盖项（ScoreId:CustomTitle）。
• tpLegendTitle（字符串，可选）：轨道预测图表卡片的自定义图例标题（例如 Predicted Gene Expression）。

重要

变体查询格式：q 中的变体必须严格采用 chr:pos_1_based:ref>alt 格式（例如 chr7:27170000:A>G 或 URL 编码后的 chr7:27170000:A%3EG，其中位置为 1-based）。不要使用 以冒号分隔的等位基因（A:G）或 dbSNP rsID（不支持 rsID）。

---

3. 多模态筛选与实验组注意事项（f）

筛选组与布尔求值

f 中的筛选条件映射到三个主要求值组：

• Biosample 组（BIOSAMPLE_NAME、BIOSAMPLE_TYPE）：采用 AND 逻辑求值。
• Assay 组（SCORER_MODALITY、ASSAY_TRANSCRIPTOR_FACTOR、 ASSAY_HISTONE_MARK）：采用 OR 逻辑求值。
• Gene 组（GENE_NAME）：采用 OR 逻辑求值。

⚠️ 多模态筛选强制规则

RNA-seq 和 DNase 轨道没有转录因子代码 （transcriptionFactorCode === ""）。如果 f 中的 Assay 组仅包含 ASSAY_TRANSCRIPTOR_FACTOR 筛选条件，那么 RNA-seq 和 DNase 轨道将无法通过 Assay 求值，并从热图中隐藏。

若要在显示特定 ChIP-seq 转录因子的同时显示 RNA-seq 和 DNase 轨道，必须在 f 中明确加入 SCORER_MODALITY:RNA-seq 和 SCORER_MODALITY:DNase（由 scripts/alphagenome_atlas_links.py 自动处理）：

f=BIOSAMPLE_NAME:<CellLine>,SCORER_MODALITY:RNA-seq,SCORER_MODALITY:DNase,ASSAY_TRANSCRIPTOR_FACTOR:<TF1>,ASSAY_TRANSCRIPTOR_FACTOR:<TF2>

---

4. 布局配置、AVI 分数与固定轨道（lItems）

绘制 AVI 分数和模态分区

• AVI 变异影响轨道（avi）：在 lItems 中加入 avi，即可为该区间或变异渲染顶层 AlphaGenome 变异影响分数轨道。
• 数据库模态分区（section:<MODALITY>）：分区会渲染该模态所有匹配轨道的完整未固定热图（例如 section:RNA_SEQ、section:DNASE、section:CHIP_TF、section:ATAC、 section:CAGE）。

固定轨道与基序实例

说明

特定轨道的基序指南：只有在针对单个轨道提出明确要求时，才应添加包含基序实例和贡献权重矩阵（CWM）标志的固定 Active-ISM 轨道。只有有限的一部分轨道（例如与该基因组位点相关的关键 ChIP-TF 或 RNA-seq 轨道）支持固定基序叠加，并能从中受益。对于标准探索链接，建议使用默认分区热图 （avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF），不添加固定轨道。

基序实例和 CWM 标志仅会在固定的序列轨道（ACTIVE_ISM 或 RAW_SCORES，而非 REF_SCORES）上以碱基对分辨率渲染。常规分区热图不会触发基序足迹渲染。

固定轨道键架构

pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source>

原始 URL 查询字符串中的 lItems 条目示例：

pinned:EFO:0002067%20TF%20ChIP-seq%20GATA1:3:CHIP_TF:ACTIVE_ISM

• <TrackMetadataName>：元数据 proto 中的精确轨道名称（例如 EFO:0002067 TF ChIP-seq GATA1）；在原始 URL 查询字符串中需进行百分号编码（空格编码为 %20），（或通过 urllib.parse.urlencode 传递时无需编码）。
• <StrandNumber>：1（STRAND_POSITIVE）、2（STRAND_NEGATIVE）、3 （STRAND_UNSTRANDED）。
• <ScorerShortName>：RNA_SEQ、CHIP_TF、DNASE、ATAC、CAGE、 PROCAP、CHIP_HISTONE（或仅限 RAW_SCORES 的模态：SPLICE_SITES、 SPLICE_SITE_USAGE、SPLICE_JUNCTIONS、POLYADENYLATION、CONTACT_MAPS）。
• <Source>：热图图块集源标识符：ACTIVE_ISM （按活性加权的 _TIMES_ACTIVE 基序足迹和 CWM 序列标志）、 RAW_SCORES（原始 ISM 变异分数轨道，也会渲染所有模态的原始 ISM 基序 足迹和 CWM 序列标志），或 REF_SCORES（连续的参考信号折线图，不含序列字母或 基序）。校准轨道和 AVI 轨道无法固定；旧版 :heatmap:...:<TilesetId> 后缀会导致轨道查找失败，并被忽略。

自动加载时显示基序的步骤

1. 将以下格式的条目 pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source> （按活性加权的基序使用 ACTIVE_ISM，原始 ISM 基序使用 RAW_SCORES）直接追加到 lItems，且仅针对特定目标轨道添加。
2. 将视口区间 i 设为碱基对分辨率（$\ge 2\text{ px/bp}$， 窗口 $\le 380\text{ bp}$）。
3. 使用细胞系和转录因子配置 f。

---

5. 轨道预测与参考等位基因和替代等位基因对比（/atlas/track-predictions）

专用的 /atlas/track-predictions 页面会对比选定分数在基因组窗口中参考等位基因和替代等位基因的预测功能特征：

• 路由： https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• 可视化：展开的折线图（表达、染色质可及性、TF 结合）和 Sashimi 弧形图（剪接连接）。

自动生成预测轨道链接（scripts/alphagenome_atlas_links.py track-predictions）

始终使用 scripts/alphagenome_atlas_links.py track-predictions 构建轨道预测 URL。手动格式化 ScoreId 字符串容易出错，因为涉及供体／受体跳过坐标、链方向（+/-）以及基因内与非基因内的后缀规则。该脚本会自动处理从 GENCODE v46 提取坐标、解析轨道目录以及合成 URL。

# Variant & Gene:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF \
  --tf CTCF

# Interval/Locus query:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --interval "chr15:41869312-42917888" \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF

track-predictions 支持的 CLI 选项

• --variant、-v（字符串，默认值：None）：采用 chr:pos_1_based:ref>alt 格式的变异字符串。
• --gene、-g（字符串，默认值：None）：目标基因符号（用于限定 i= 视口并计算剪接连接位点）。
• --gene_id（字符串，默认值：None）：目标 Ensembl 基因 ID（例如 ENSG00000092529.26）。
• --interval、-i（字符串，默认值：None）：采用 chr:start-end 格式的基因组区间视口。
• --biosample、-b（字符串，默认值：Muscle_Skeletal）：目标 生物样本或组织查询（例如 Muscle_Skeletal、K562、Whole_Blood）。
• --modalities、-m（字符串，默认值： SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF）：以逗号分隔的模态列表 （SPLICE_JUNCTIONS、RNA_SEQ、DNASE、ATAC、CHIP_TF）。
• --tf（字符串，默认值：CTCF）：ChIP-TF 轨道的转录因子名称 （例如 CTCF、GATA1）。
• --rename（字符串，默认值：None）：图表卡片中的自定义轨道名称覆盖项。
• --legend_title（字符串，默认值：None）：图表卡片的自定义图例标题。
• --format（枚举，默认值：table）：输出格式（table、url、 json）。

重要

剪接与 RNA-seq 必须共同绘制的规则：生成 /atlas/track-predictions 深层链接、绘图或可视化剪接变异的影响数据时， 始终要在剪接轨道旁绘制连续的 RNA-seq 表达数据（SPLICE_JUNCTIONS、 SPLICE_SITE_USAGE、SPLICE_SITES）。剪接突变经常会激活隐蔽剪接连接位点， 并触发无义介导的 mRNA 降解（NMD），或改变转录本总产量；必须同时查看剪接 连接位点（sashimi 弧线）和连续的 RNA-seq 读段覆盖度，才能观察到结构性剪接 缺陷及其导致的整体转录本丰度变化。

重要

轨道预测 URL 中始终要提供有界的 i=： 省略 scores= 或不限定基因组区间（i=），会导致 Web 应用尝试查询更大基因座内 所有匹配的轨道，造成严重延迟或页面卡住。alphagenome_atlas_links.py track-predictions 会自动将 i= 限定在目标基因或指定区间内。