tooluniverse-regulatory-variant-analysis

计算，而非描述

如果分析需要计算（统计、数据处理、评分、数据丰富），请通过 Bash 编写并运行 Python 代码。不要描述你会怎么做——直接执行并报告实际结果。使用 ToolUniverse 工具检索数据，然后使用 Python（pandas、scipy、statsmodels、matplotlib）进行分析。

调控变异分析技能

系统性解读调控变异：从 GWAS 中发现性状关联，映射 eQTL 效应，注释染色质背景，评估与调控元件的重叠，使用 AlphaGenome/AlphaGenome Atlas 预测序列层面的直接效应，并为非编码变异提供按证据分级的功能影响预测。

适用场景

• “rs12913832 有哪些 GWAS 关联？”
• “查找脑组织中 APOE 位点的 eQTL”
• “有哪些调控元件与这个变异所在区域重叠？”
• “GWAS 中有哪些 SNP 与 2 型糖尿病相关？”
• “这个内含子变异是否位于活性增强子中？”
• “rs429358 的 RegulomeDB 评分是多少？”
• “查找 BRCA1 启动子区域的 ENCODE 组蛋白标记”
• “将‘血压’的性状本体术语映射到 EFO ID”
• “这个变异完全没有 GWAS/eQTL/ENCODE 命中——序列模型是否预测到任何效应？”
• “扫描这个候选调控区域，找出影响最大的单碱基变化”

不适用于（请改用其他技能）：

• 编码变异致病性 -> 使用 tooluniverse-variant-interpretation
• 完整的临床变异分类（ACMG）-> 使用 tooluniverse-variant-interpretation
• 基因-疾病关联（非特定变异）-> 使用 tooluniverse-gene-disease-association
• 药物基因组学变异注释 -> 使用 tooluniverse-pharmacogenomics
• 表观基因组学数据处理（BED/narrowPeak 文件）-> 使用 tooluniverse-epigenomics

---

非编码变异影响推理

评估非编码变异时，请围绕五个问题收集证据。前四个问题基于注释（该位置在这个群体中已知的信息）；第五个问题基于模型（序列本身预测的结果，无论该位置目前是否已有注释）。它们回答的是不同的问题，应相互印证，而不能彼此替代。

1. 该变异是否位于调控元件中？ 使用 RegulomeDB 评估该变异是否与 TF 结合位点、染色质可及性峰或已知调控注释重叠。RegulomeDB 得分较低（类别 1a-2a）表示有力证据表明该位置具有功能活性。使用 ENCODE 组蛋白标记进行确认：H3K27ac 表示活性增强子和活性启动子；单独的 H3K4me1 标记处于预备状态的增强子；H3K4me3 标记活性启动子；H3K27me3 标记沉默区域。

2. 它是否会改变转录因子结合位点？ 检查 RegulomeDB 中的 TF 结合证据以及 ENCODE TF ChIP-seq 实验。若变异位于 TF 足迹内，并破坏共识基序，则具有可作用的机制依据，尤其是在该 TF 已知与疾病组织相关时。

3. 是否有将其与某个基因关联起来的 eQTL 证据？ 查询 GTEx，确定该变异（或与其紧密连锁不平衡的变异）是否会以组织特异性或普遍性的方式调节附近基因的表达。组织特异性 eQTL 表明存在细胞类型特异性调控；普遍性 eQTL 则表明存在核心调控元件。NES 的方向（正值 = 替代等位基因增加表达，负值 = 降低表达）和效应大小都对解读很重要。

4. 是否有该性状关联的 GWAS 证据？ 在 GWAS Catalog 中搜索 rsID 或周边位点。相关性状中达到全基因组显著性（p < 5×10⁻⁸）的关联可确立该变异的生物学重要性。交叉参考 OpenTargets，获取多个 GWAS 研究中的位点到基因映射。

5. 基于序列的模型直接预测了什么？ 运行 AlphaGenome_atlas_lookup_variant，快速获取 AVI_SCORE（统一的 AlphaGenome + AlphaMissense 影响估计；该分数为预计算结果，因此成本低廉，可在下方注释阶段开始前对每个候选 SNV 进行检查）。如果 AVI_SCORE 高而没有其他证据，这正是“看不出明显作用的变异”这一情况——这意味着注释数据库尚未跟上，而不是该变异没有活性。AVI_SCORE 较高，或该位置属于 Atlas 无法覆盖的 indel/合成序列时，可升级到实时模型：使用 AlphaGenome_score_variant 获取逐轨道效应明细，或使用 AlphaGenome_score_ism_variants 扫描周边窗口，找出究竟是哪种碱基变化（以及哪种生物学读数——表达、剪接、染色质）驱动了效应。这是五个问题中唯一能给出机制性答案的一个（例如，“该替换产生了一个原本不存在的转录因子结合基序”），而不是相关性答案。

综合证据：构建多层次的证据链。若一个变异同时具有 GWAS 显著性、eQTL 证据、RegulomeDB 得分 1a-2a，以及相关组织中的活性染色质（H3K27ac），则代表其具有高可信度的调控影响；若 AVI_SCORE 或 ISM 结果与之吻合，则会进一步增强这一判断，因为这些结果来自独立的因果机制来源，而非更多相关性注释。两到三条相互印证的证据（例如 eQTL 加活性增强子）构成中等可信度。仅有一条证据，或变异仅处于预备状态而非活跃的调控环境中，则代表可信度较低——但在断定其“没有证据”之前，请先参阅下方仅有 AlphaGenome 证据的情况。

---

工作流概览

Input (rsID, genomic coordinates, trait/disease, gene)
  |
  v
Phase 0: Variant/Trait Resolution
  Resolve rsIDs, map trait names to EFO/MONDO IDs via OLS
  |
  v
Phase 0.5: Sequence-Based Triage (AlphaGenome Atlas)
  Instant AVI_SCORE per candidate SNV -- cheap, run before the annotation phases
  |
  v
Phase 1: GWAS Association Lookup
  GWAS Catalog associations, p-values, effect sizes, study metadata
  |
  v
Phase 2: eQTL Analysis
  GTEx tissue-specific eQTLs, target gene identification
  |
  v
Phase 3: Regulatory Element Annotation
  ENCODE histone marks, RegulomeDB scores, chromatin state
  |
  v
Phase 4: OpenTargets GWAS Integration
  OpenTargets GWAS study aggregation, locus-to-gene mapping
  |
  v
Phase 4.5: Sequence-Based Deep-Dive (if Phases 1-4 are silent, or the Phase 0.5
  AVI_SCORE was high and needs a mechanism) -- live AlphaGenome scan
  |
  v
Phase 5: Functional Impact Synthesis
  Integrate all evidence, assign regulatory impact level
  |
  v
Phase 6: Report
  Evidence-graded regulatory variant report

---

阶段 0：变异/性状解析

在查询 GWAS 之前，使用 ols_search_terms 将性状名称解析为本体 ID。对于 GWAS 性状，将范围限制为 ontology="efo"；OpenTargets 更倾向于使用 MONDO ID（例如，2 型糖尿病使用 MONDO_0005148，而非 EFO_0001360）。使用 EnsemblVEP_annotate_rsid（参数是 variant_id，不是 rsid）进行初步后果注释并识别最近的基因。

---

阶段 0.5：基于序列的初步筛选（AlphaGenome Atlas）

需要 ALPHA_GENOME_API_KEY。 如果未配置该密钥，AlphaGenome 工具将完全不会出现在你的工具集中——请跳过此阶段和阶段 4.5，直接执行阶段 1-4。这些阶段本身就是完整、自给自足的流程（在支持 AlphaGenome 之前，该技能就是这样工作的，且以下所有内容都不依赖于它是否运行）。

如果已知一个特定变异（染色体、位置、参考/替代碱基），请先运行 AlphaGenome_atlas_lookup_variant，再进行后续注释阶段的调用。这是一个预计算数据库查询，覆盖了几乎所有可能的人类 SNV，因此作为默认的第一步运行成本很低，而不必将它留作最后手段：它会返回 AVI_SCORE，这是一个融合 AlphaGenome 调控预测与 AlphaMissense 编码影响模型的单一分数，可用于比较编码变异和非编码变异。

如果你掌握的是一组候选变异，而非一个已知变异——例如，阶段 1 的 gwas_get_variants_for_trait 为某种性状返回了数十个 SNP，或者你正在对一个位点进行精细定位——请使用 AlphaGenome_atlas_scan_interval 扫描该区域，而不是对每个候选变异逐一调用 atlas_lookup_variant。一次调用即可按 AVI_SCORE 对最多 10 kb 窗口内的所有可能 SNV 进行排序。这正是“先根据预测的分子效应对候选变异分组，再进行成本高昂的后续分析”这一模式；与将每个候选变异视为同等值得调查相比，它在大型队列分析中发现了更多实质性的性状关联。

将任一结果都视为先验，而非定论：如果 AVI_SCORE 高但注释证据薄弱，意味着“在这里深入调查，数据库还未跟上”（见阶段 4.5）；如果 AVI_SCORE 低但 GWAS/eQTL 证据强，则值得再次确认因果变异是否其实是 LD 中的另一个变异。Atlas 仅覆盖单核苷酸替换；对于插入缺失变异，请直接使用 AlphaGenome_score_variant（实时模型）。

---

阶段 1：GWAS 关联查询

gwas_search_associations 是主要工具：接受 disease_trait（自由文本）、efo_id（精度更高）、rs_id 和 p_value 阈值。全基因组显著性请使用 p_value=5e-8。若要发现位点层面的关联，可使用 gwas_get_variants_for_trait 获取某种性状的所有 SNP。gwas_get_snps_for_gene 可查找 GWAS Catalog 中映射到特定基因的 SNP。

推理提示：当 GWAS Catalog 对自由文本性状返回空结果时，请改用 efo_id 参数——该目录使用受控词汇，自由文本匹配并不精确。

---

阶段 2：eQTL 分析

GTEx_query_eqtl 接受基因符号（自动解析为 GENCODE ID）或 Ensembl 基因 ID。它会返回组织特异性的 SNP-基因关联，以及每个组织的 NES（标准化效应大小）和 p 值。

解读结果时，请思考：eQTL 效应是否出现在与该疾病最相关的组织中？对于神经退行性疾病变异，脑组织特异性的 eQTL 比普遍存在的 eQTL 更有说服力。在为 eQTL 证据赋予权重之前，使用 GTEx_get_median_gene_expression 确认目标基因确实在相关组织中表达。

注意：GTEx API 使用 v8 数据；gtex_v10 端点在某些查询中可能返回空结果。

---

阶段 3：调控元件注释

RegulomeDB_query_variant（参数：rsid）会返回调控评分和特征注释。1a–2a 类别的评分表示有强有力的调控证据（eQTL 重叠 + TF 结合 + 染色质可及性）。3a–6 类别的评分表示证据强度依次减弱。

ENCODE_search_histone_experiments 接受 histone_mark（例如，“H3K27ac”）和 biosample_term_name（组织或细胞系名称——不是疾病名称；ENCODE 使用“liver”或“breast epithelium”等生物样本名称）。查询 TF 结合数据时，请使用 assay_title="TF ChIP-seq"（而不是仅使用 "ChIP-seq"）。

推理提示：RegulomeDB 汇总了 ENCODE、Roadmap 和其他数据。如果 ENCODE 中没有特定的生物样本，RegulomeDB 仍可能包含来自相关细胞类型的汇总证据。

如果已知变异的 GRCh38 坐标，FAVOR_annotate_variant(variant="chr-pos-ref-alt") 一次调用即可返回调控注释块（以及保守性、频率和 CADD），可用于快速确认该位置是否落在已注释的调控元件中，然后再深入查询 RegulomeDB/ENCODE。

---

阶段 4：OpenTargets GWAS 整合

OpenTargets_search_gwas_studies_by_disease 将 diseaseIds 作为 MONDO ID 数组。它会提供多个 GWAS 研究的位点到基因（L2G）评分；这些评分不止考虑简单的距离，还纳入了共定位、eQTL 和染色质数据。请先使用 OpenTargets_multi_entity_search_by_query_string 或 OpenTargets_get_disease_id_description_by_name，将疾病名称解析为 MONDO/EFO ID。

---

阶段 4.5：基于序列的深入分析（条件执行）

满足以下任一条件时执行此阶段：（a）阶段 1–4 的结果为空或较弱——这是典型的“没有明显功能”的变异；或（b）阶段 0.5 的 AVI_SCORE 较高，报告需要给出实际机制，而不只是一个数字。

• AlphaGenome_score_variant：已知重要模态（表达、剪接、可及性或特定组蛋白标记）时，推荐使用此工具评估变异在各轨道上的参考与替代等位基因效应。
• AlphaGenome_score_ism_variants：扫描变异周围的短窗口（≤500 bp）内所有可能的替换，并按效应排序。如果尚不清楚具体哪个碱基起作用，只知道该区域中有因素起作用，可使用此工具——例如，通过检查相邻位置是否呈现相同的破坏模式，确认变异是否位于基序内。
• AlphaGenome_predict_interval：需要了解更广泛的调控图谱，而不只是单个变异的效应差值时，可使用此工具获取较宽窗口（最长 1 Mb）的完整轨道概况。

两个或三个轨道上的结果一致（例如，表示增强子活性的组蛋白标记与表达均朝同一方向变化），比单轨道命中更能构成有力证据——阶段 5 已将相同逻辑用于注释证据。

AlphaGenome 并不是 ToolUniverse 中唯一的序列预测模型，只是覆盖面最广、也是此阶段默认使用的模型。如果它不可用（没有密钥），或者特定情况需要其他模型——例如，需要使用已发表且可自托管的模型，而不是托管 API；或者问题专门关注染色质可及性，而不是广泛的多模态读数——请参阅 tooluniverse-regulatory-genomics，其中介绍了 Enformer、Borzoi、ChromBPNet 和 Evo 2。它们覆盖了相同领域，但各有不同的权衡。

---

第 5 阶段：功能影响综合评估

收集证据后，分层分析：

• 高影响：GWAS 达到全基因组显著性 + eQTL 具有有意义的 NES + RegulomeDB 评分 ≤ 2 + 相关组织中存在活跃染色质（H3K27ac）。多条独立证据指向同一位点和基因——一致的 AlphaGenome/AVI_SCORE 结果可在此基础上提供一条机制证据，但如果注释证据已相互印证，则高置信度评估并不要求这一结果。
• 中等影响：有两到三条证据（例如，eQTL + 与活跃增强子的重叠，或 GWAS 显著 + RegulomeDB ≤ 3），但未完全相互印证。
• 低影响：只有一条证据，或只有计算注释（VEP 后果类别），没有功能数据。
• 序列模型支持、注释未检出：没有 GWAS/eQTL/ENCODE/RegulomeDB 证据，但第 4.5 阶段显示 AVI_SCORE 较高和／或存在明确的多轨迹机制（例如，形成了转录因子基序、破坏了剪接位点）。应将其视为独立层级，而不是“没有证据”——这意味着该变异可能具有功能，但过于新颖或罕见，现有数据库尚未收录，并非没有发生任何作用。应如实说明置信度：这是一个来自独立且经过充分验证的模型的强假设，并非上述层级中的多来源证据相互印证。
• 没有证据：所有来源中都没有调控注释，且第 4.5 阶段（如果运行）也显示 AVI_SCORE 较低／没有显著序列效应。该变异可能位于非功能区域。

---

后备策略

• GWAS Catalog 返回空结果：将自由文本 disease_trait 改为 efo_id；扩大性状词的范围。
• 该基因的 GTEx eQTL 为空：确认基因符号拼写正确；尝试使用 Ensembl ID；增大 size 参数。
• RegulomeDB 未返回数据：直接查询 ENCODE，或运行 FAVOR_annotate_variant（GRCh38 坐标）获取其调控与保守性注释；该变异可能缺少可用数据中的调控注释。
• OpenTargets GWAS 返回 None：确认 MONDO/EFO ID 格式；先尝试 OpenTargets_multi_entity_search_by_query_string，以确认正确的 ID。
• 未找到 ENCODE 组织：ENCODE 使用特定的生物样本名称；RegulomeDB 汇总了多种细胞类型的数据，可能涵盖缺失的信息。
• 第 1 至第 4 阶段全部返回空结果／证据薄弱：先别断定“没有证据”——运行第 4.5 阶段。AlphaGenome 直接根据序列进行预测，不依赖该变异（或其附近的任何区域）曾被研究过，因此当数据库中没有任何数据时，它仍是可用的证据来源。
• 变异是插入缺失，而非单核苷酸替换：AlphaGenome_atlas_lookup_variant/AlphaGenome_atlas_scan_interval 仅支持 SNV；请改用实时工具 AlphaGenome_score_variant。
• 工具集中没有 AlphaGenome 工具：未配置 ALPHA_GENOME_API_KEY。跳过第 0.5 和第 4.5 阶段，将第 1 至第 4 阶段作为独立流程运行——不要因为等待一个可能永远不会提供的密钥而阻碍分析。如果该案例仍需要序列模型预测，tooluniverse-regulatory-genomics 提供了可自托管的替代方案（Enformer、Borzoi、ChromBPNet），无需使用这个特定密钥。

---

示例工作流

GWAS 变异功能注释（rs429358 / APOE）

Step 1: gwas_search_associations(rs_id="rs429358")
  -> All trait associations (Alzheimer's disease, LDL cholesterol, etc.)

Step 2: GTEx_query_eqtl(gene_symbol="APOE")
  -> Tissue-specific eQTL evidence; note effect in brain vs liver

Step 3: RegulomeDB_query_variant(rsid="rs429358")
  -> Regulatory score and TF binding annotations

Step 4: ENCODE_search_histone_experiments(histone_mark="H3K27ac", biosample_term_name="brain")
  -> Active enhancer context near the variant

Step 5: Synthesize: does GWAS significance + eQTL + active chromatin converge on one gene?

非编码变异评估（内含子／UTR 变异）

Step 1: EnsemblVEP_annotate_rsid(variant_id="rs12345678")
  -> Confirm non-coding consequence, identify nearest gene

Step 2: RegulomeDB_query_variant(rsid="rs12345678")
  -> Is this position in a regulatory context?

Step 3: gwas_search_associations(rs_id="rs12345678")
  -> Any GWAS associations in relevant traits?

Step 4: GTEx_query_eqtl(gene_symbol=nearest_gene)
  -> Does this variant or nearby variants modulate expression?

Step 5: ENCODE_search_histone_experiments(histone_mark="H3K27ac", biosample_term_name=relevant_tissue)
  -> Active chromatin confirmation

Step 6: Classify impact based on convergence of evidence lines

通过序列预测解析注释未检出的变异

真实案例中有一个典型例子：GREGoR Consortium 使用 AlphaGenome Atlas，通过深部内含子 DNM1 变异解决了一例未确诊的癫痫病例。没有外显子命中，没有 GWAS 关联，注释阶段也找不到任何线索——直到直接使用序列模型进行预测。

Step 1: AlphaGenome_atlas_lookup_variant(chromosome=..., position=..., reference_bases=..., alternate_bases=...)
  -> High AVI_SCORE despite the variant being deep intronic

Step 2: gwas_search_associations, GTEx_query_eqtl, RegulomeDB_query_variant, ENCODE_search_histone_experiments
  -> All empty or weak -- nothing here for standard annotation to catch

Step 3: AlphaGenome_score_ism_variants(chromosome=..., start=..., end=..., output_type="SPLICE_SITES")
  -> Scan the surrounding window; identify that this substitution creates a cryptic splice site

Step 4: Synthesize: high AVI_SCORE + a concrete, mechanistic splice-site prediction, despite zero
  annotation-database hits -> classify as "sequence-model-supported, annotation-silent", not
  "no evidence". Recommend experimental validation (e.g., a minigene splicing assay) rather than
  treating the model output as a final answer.

对 GWAS 位点的多个候选变异进行优先级筛选

GWAS 命中很少只涉及一个变异——由于连锁不平衡，一个位点通常包含数十个候选变异。对每个候选变异运行完整的注释流程（第 1–4 阶段）成本高昂；请先进行优先级筛选。

Step 1: gwas_get_variants_for_trait(trait/efo_id=...)
  -> Dozens of candidate SNPs at the associated locus

Step 2: AlphaGenome_atlas_scan_interval(chromosome=..., start=..., end=...)
  -> One call, AVI_SCORE for every SNV across the locus (<=10 kb per call; tile larger loci)

Step 3: Rank candidates by AVI_SCORE; take the top handful (not just the GWAS lead SNP --
  a variant in tight LD with a stronger predicted effect is often the better causal candidate)

Step 4: Run Phases 1-4 (GWAS, eQTL, RegulomeDB/ENCODE, OpenTargets) only on those top candidates,
  not the full list -- the expensive annotation calls are now spent where they're likely to pay off

---

局限性

• GWAS Catalog 仅涵盖已发表的 GWAS；未发表的研究不在其中。
• GTEx eQTL 数据来自 v8；v10 端点可能返回空结果。
• RegulomeDB 注释取决于特定细胞类型是否有可用的 ENCODE/Roadmap 数据。
• eQTL 分析识别的是相关性，而非因果关系；需要精细定位才能识别因果变异。
• RegulomeDB 评分是启发式指标；1a 分数并不保证存在功能影响。
• GWAS 关联是群体层面的；单个变异的影响取决于遗传背景。
• AlphaGenome/AVI_SCORE 预测是模型估算值，而非实验测量结果——它们可用于佐证注释证据，或提出值得验证的假设，但单凭高分并不等同于确认存在功能影响。AlphaGenome_score_ism_variants 的窗口上限为 500 bp，AlphaGenome_atlas_scan_interval 每次调用的上限为 10,000 bp——调用任一工具前，请先确定区域范围。