alphagenome-single-variant-analysis

使用 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 或创建新的 venv——uv 会自动管理隔离环境。
• 仅限离线：绝不要使用外部 API（例如 MyGene.info、Ensembl REST）查询基因／转录本。使用本地 GTF 和 lookup_gene_info.py。如果失败，请修复环境／路径问题，不要改用外部 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

说明

首次调用时会解析并安装依赖项（约 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 大小写敏感：AlphaGenome GTF Feather 文件使用首字母大写的列名 （Feature、Start、End、Strand），与标准 GTF 文件不同。如果遇到 KeyError， 请务必检查 df.columns。
• score_variant 本体筛选：score_variant 不接受 ontology_terms 参数。你必须检查 adata.var 列，并手动筛选返回的 AnnData 对象。相比之下，predict_variant 可以直接接受 ontology_terms。
• Sashimi 缩放逻辑：为了确保能看到“跳过”弧线，请将缩放范围扩展至包含 两侧的外显子，而不要只依赖剪接位点的重叠。
• 剪接位点评分：来自 prediction 的原始 Junction 对象可能只是简单的区间。 使用 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. 基础区间：变体上下游各一个外显子 （结构背景）。
    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

# Load environment variables from ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# Setup API Key and Client
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# Define Variant (example)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# Use supported sequence length (e.g., 2**20 for optimal performance)
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"Scoring variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Process and Display Results
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("Top Significant Hits:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

针对疾病相关组织的扩展搜索

# Define keywords based on disease context
disease_keywords = ["liver", "hepatocyte"]

# Filter for any match
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--- Extended Analysis (Keywords: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

工作流检查清单

Variant Analysis Progress:
- [ ] Step 0: Review Golden Examples (MANDATORY)
- [ ] Step 1: Create Output Folder and Setup
- [ ] Step 2: Parse User Query & Research
- [ ] Step 3: Resolve Tissues & Modalities
- [ ] Step 4: Visualize & Save Plots
- [ ] Step 5: Analyze Predictions (view plots, no code). MANDATORY: Read [interpretation-guide.md](docs/interpretation-guide.md) before interpreting results.
- [ ] Step 6: Write Report, save it as `report.md` (MANDATORY)
- [ ] Step 7: Self-Critique (view `report.md` to verify links & claims)
- [ ] Step 8: Make artifact out of `report.md`

---

多变体工作流

如果指定了多个变体，则启动子 Agent 分别运行每个变体 分析，然后将每个 report.md 综合为一份报告。

脚本参考

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