tooluniverse-variant-to-mechanism

变异到机制分析技能

追溯从遗传变异到疾病机制的完整因果链：调控背景、靶基因、分子通路和表型后果。整合 3 个证据层级（调控、分子、疾病）中的 7 个以上数据库，构建按证据强度分级的机制模型。

重要：工具调用中始终使用英文术语。使用用户的语言作答。

---

查证，不要猜测

对任何不确定的科学事实，先查询数据库（PubMed、UniProt、ChEMBL、ClinVar 等），而不要凭记忆推理。经过数据库验证的答案始终比猜测更可靠。

---

何时使用此技能

适用于用户：

• 询问“rs7903146 如何导致 2 型糖尿病？”
• 希望追溯 GWAS 变异的生物学机制
• 需要将非编码变异与下游通路关联起来
• 询问“该变异会影响哪个基因，又是通过什么通路？”
• 希望了解调控变异的机制叙述
• 需要确定 GWAS 位点的因果基因
• 询问“这个内含子 SNP 有什么功能影响？”

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

• 编码变异致病性 / ACMG 分类 -> 使用 tooluniverse-variant-interpretation
• 纯粹的调控元件注释，不涉及机制 -> 使用 tooluniverse-regulatory-genomics
• 纯粹列出 GWAS 命中位点，不涉及机制 -> 使用 tooluniverse-gwas-snp-interpretation
• 药物基因组学变异注释 -> 使用 tooluniverse-pharmacogenomics
• 不涉及变异背景的基因-疾病关联 -> 使用 tooluniverse-gene-disease-association

---

输入参数

参数	必填	描述	示例
variant	是	rsID 或基因组坐标	"rs7903146" 或 "10:112998590:C:T"
trait	否	疾病 / 性状背景（有助于确定优先级）	"type 2 diabetes"
tissue	否	eQTL / 表达分析关注的组织	"pancreas"

---

工作流概览

阶段 1 变异表征（VEP、人群频率、CADD） -> 阶段 2 调控背景（GWAS、RegulomeDB、ENCODE、cCRE） -> 阶段 3 靶基因识别（GTEx eQTL、OpenTargets L2G） -> 阶段 4 基因功能与通路（STRING、Reactome、GO） -> 阶段 5 疾病关联（OpenTargets、GenCC、DisGeNET） -> 阶段 6 机制综合（因果链、证据分级、置信度评分）

---

阶段 1：变异表征

解析变异身份并获取基本注释。

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Step 1: VEP annotation
vep = tu.tools.EnsemblVEP_annotate_rsid(variant_id="rs7903146")
# NOTE: param is `variant_id`, NOT `rsid`
# Response format variable: list, {data, metadata}, or {error} -- handle all three
# Extract: consequence_type, gene, chromosome, position, alleles

# Step 2: Population frequency and pathogenicity scores
myvar = tu.tools.MyVariant_query_variants(
    query="rs7903146",  # NOTE: param is `query`, NOT `variant_id`
    fields="dbsnp,gnomad_genome,cadd,clinvar"
)
# Returns: {hits: [{_id, dbsnp, gnomad_genome: {af: {af, ...ancestry}}, cadd: {phred}, clinvar}]}
# gnomAD AF: frequency in general population
# CADD phred: >=20 = top 1% deleterious, >=30 = top 0.1%

# Step 3: Confirm gene context
gwas_snp = tu.tools.gwas_search_snps(rs_id="rs7903146")
# Returns: SNP location, mapped genes, functional class

# Optional one-call shortcut (when a GRCh38 coordinate is available):
favor = tu.tools.FAVOR_annotate_variant(variant="19-44908822-C-T")
# Returns freq (BRAVO/gnomAD-by-ancestry/1000G) + CADD/SIFT/PolyPhen/AlphaMissense
# + conservation + ClinVar + regulatory annotation in a single call — a fast way to
# populate most of Phase 1 (and the regulatory block of Phase 2) before drilling in.

---

阶段 2：调控背景

评估变异的调控环境。

2a：GWAS 关联

# All trait associations for this variant
gwas = tu.tools.gwas_search_associations(rs_id="rs7903146", size=50)
# Returns: {data: [{disease_trait, p_value, or_per_copy_number, beta, study_accession}]}
# NOTE: Use gwas_search_associations, NOT gwas_get_associations_for_trait (BROKEN)

2b：RegulomeDB 评分

regulome = tu.tools.RegulomeDB_query_variant(rsid="rs7903146")
# Returns: {status, data: {score/ranking, probability, features}}
# Score 1a-2a = strong regulatory evidence
# Uses GRCh38 (NOT hg19)

2c：ENCODE 染色质背景

# Check enhancer (H3K27ac), promoter (H3K4me3), and accessibility in disease-relevant tissue
encode_h3k27ac = tu.tools.ENCODE_search_histone_experiments(
    histone_mark="H3K27ac", biosample_term_name="pancreas", limit=10)
encode_h3k4me3 = tu.tools.ENCODE_search_histone_experiments(
    histone_mark="H3K4me3", biosample_term_name="pancreas", limit=10)
encode_atac = tu.tools.ENCODE_search_chromatin_accessibility(
    biosample_term_name="pancreas", limit=10)

2d：cCRE 重叠（已知坐标时）

# Check candidate cis-regulatory elements
ccres = tu.tools.UCSC_get_encode_cCREs(
    chrom="chr10",
    start=112998000,
    end=112999000
)
# Returns: cCRE type (PLS=promoter, pELS=proximal enhancer, dELS=distal enhancer, CTCF-only)

2e：OLS 性状解析（提供性状时）

# Resolve trait to ontology ID for downstream tools
ols = tu.tools.ols_search_terms(query="type 2 diabetes", ontology="efo")
# Returns: {status, data: [{iri, label, short_form, ontology_name}]}
# For OpenTargets: use MONDO_0005148 for T2D (NOT EFO_0001360)

---

阶段 3：靶基因识别

识别变异调控的基因。此环节至关重要。

3a：GTEx eQTL（主要证据）

# Find eQTL associations for the nearest gene
eqtls = tu.tools.GTEx_query_eqtl(gene_symbol="TCF7L2", size=100)
# Returns: {status, data: [{snpId, geneSymbol, tissueSiteDetailId, pValue, nes}]}
# Filter for the specific rsID in the results
# NES > 0: alt allele increases expression; NES < 0: decreases

# Check expression levels to prioritize tissues
expression = tu.tools.GTEx_get_median_gene_expression(gene_symbol="TCF7L2")
# Returns: median TPM across GTEx tissues
# IMPORTANT: GTEx uses v8 data (v10 endpoints may return empty)

3b：OpenTargets 位点到基因（L2G）

# Get credible sets and L2G predictions
credible = tu.tools.OpenTargets_get_variant_credible_sets(
    variantId="10_112998590_C_T"  # chr_pos_ref_alt format
)
# Returns: credible set membership, L2G scores for causal genes
# L2G > 0.5: high confidence causal gene
# L2G 0.1-0.5: moderate confidence

3c：最近基因映射

# Get gene details for the candidate target
gene_info = tu.tools.MyGene_query_genes(
    query="symbol:TCF7L2",
    species="human",
    fields="symbol,ensembl.gene,entrezgene,name,summary,go",
    size=5
)
# Extract Ensembl ID for OpenTargets queries
# Filter by exact symbol match (first hit may not be correct gene)

如何推断靶基因

对于非编码变异，最近的基因往往并非因果基因。调控元件的作用范围可达数百 kb，甚至会完全跳过中间基因。在查看工具之前，先推断哪个基因可能是靶基因：

• 疾病相关组织中的 eQTL 是最有力的证据。 如果某个变异在胰腺中是 Gene X 的 eQTL，而研究性状是糖尿病，那么两者之间就存在直接的机制联系。在无关组织中发现的 eQTL 证据较弱，但仍有参考价值。
• L2G 分数整合多种信号（距离、染色质互作、eQTL），生成单一预测。L2G > 0.5 表示置信度较高，但这只是计算预测，并非实验性证据。应结合 eQTL 数据；两者一致时，置信度较高。
• 仅凭距离判断并不可靠。 许多 GWAS 位点的因果基因与 lead SNP 相距 2-3 个基因。未经 eQTL 和 L2G 检查，切勿默认最近的基因就是因果基因。
• 当多个候选基因都有证据时， 应按证据强度对它们排序并全部列出。结论确实可能存在不确定性。

---

阶段 4：基因功能与通路

确定靶基因后，描述其分子功能。

# STRING PPI network — NOTE: param is `identifiers` (string), NOT `protein_ids`
ppi = tu.tools.STRING_get_interaction_partners(
    identifiers="TCF7L2", species=9606, required_score=700)

# STRING functional enrichment (GO, KEGG, Reactome) — needs a gene SET,
# newline-separated; results are in data["enrichments"]
enrichment = tu.tools.STRING_get_enrichment(
    identifiers="TCF7L2\nCTNNB1\nAPC\nLEF1", species=9606)

# Reactome pathway enrichment — space-separated STRING, NOT array
reactome = tu.tools.ReactomeAnalysis_pathway_enrichment(
    identifiers="TCF7L2 CTNNB1 APC")

# UniProt function (returns list of strings, NOT dict)
uniprot_func = tu.tools.UniProt_get_function_by_accession(accession="Q9NQB0")

# PANTHER GO enrichment — GO:0008150=BP, GO:0003674=MF, GO:0005575=CC
panther = tu.tools.PANTHER_enrichment(
    gene_list="TCF7L2,CTNNB1,APC,LEF1", organism=9606,
    annotation_dataset="GO:0008150")

---

阶段 5：疾病关联

将分子机制与疾病表型联系起来。

# Disease associations for target gene (requires Ensembl ID)
ot_diseases = tu.tools.OpenTargets_get_diseases_phenotypes_by_target_ensembl(
    ensemblId="ENSG00000148737")

# Specific gene-disease evidence (both IDs must be pre-resolved)
ot_evidence = tu.tools.OpenTargets_target_disease_evidence(
    ensemblId="ENSG00000148737", efoId="MONDO_0005148")

# GenCC curated validity (Definitive/Strong/Moderate/Limited/Disputed/Refuted)
gencc = tu.tools.GenCC_search_gene(gene_symbol="TCF7L2")

# DisGeNET scored associations (requires DISGENET_API_KEY)
disgenet = tu.tools.DisGeNET_search_gene(gene="TCF7L2", limit=20)

# OpenTargets GWAS studies — use MONDO IDs, NOT EFO
ot_gwas = tu.tools.OpenTargets_search_gwas_studies_by_disease(
    diseaseIds=["MONDO_0005148"])

---

阶段 6：机制综合

如何构建和评估因果链

目标是建立一条明确的链条：变异 -> 蛋白质或表达发生变化 -> 通路改变 -> 疾病表型。 每个箭头都是一个需要证据支持的环节。所有环节都有证据支持的链条才有说服力。缺少任何环节的链条都只是一个假设，而不是结论。

从变异的位置入手。 它属于编码区还是非编码区？编码变异会直接改变蛋白质——错义变异会替换一个氨基酸，无义变异会截短蛋白质。非编码变异会改变调控——它们影响蛋白质的生成量，而不是生成哪种蛋白质。这一区别决定了你的整个分析路径。

对于编码变异，请思考：该位点在不同物种间是否保守？它是否位于功能结构域（活性位点、结合界面、跨膜螺旋）？保守活性位点残基上的变异，比无序环区中的变异更可能具有致病性。请查询 ClinVar 和 CADD，了解是否已有评估，但也要自行分析结构背景。

对于非编码变异，请思考：是否有 eQTL 将该变异与附近基因关联起来？该变异是否位于 TFBS、增强子或启动子中（根据 RegulomeDB 和 ENCODE）？位于开放染色质区域、且在疾病相关组织中存在 eQTL 的变异，具有明确的调控机制。位于基因荒漠且没有 eQTL 的变异则难以解释得多——请承认这一不确定性。

分别评估每个环节。 对于链条中的每个箭头，都要问：有什么证据？证据是否经过重复验证？是否来自正确的组织？然后评估整条链：

• 所有环节都有充分支持，且多个数据库提供了相互印证的证据 = 已确立的机制
• 大多数环节证据有力，但有一个环节仅依赖单一来源 = 强机制
• 各环节的证据相互矛盾或仅为中等程度 = 中等机制
• 一个或多个环节没有直接证据，仅有推断 = 初步机制
• 关联仅基于邻近关系或文本挖掘 = 推测性机制

证据层级很重要。 临床观察（有临床数据支持的 ClinVar 致病性结论）强于功能分析（eQTL、染色质标记），而功能分析又强于计算预测（CADD 评分、L2G 模型）。单独的 CADD 评分证据较弱。多个相互印证的计算预测属于中等证据。在疾病相关组织中经过多项研究重复验证的 eQTL 则属于强证据。

始终考虑其他可能的机制。 如果 eQTL 指向 Gene A，而 L2G 更支持 Gene B，请同时呈现这两种模型。如果该变异可能通过剪接而非表达发挥作用，也请注明。坦诚说明不确定性，比虚假的确信更有用。

---

证据评级

根据每项证据对机制链条的支持有多直接，对其进行评级：

• T1（最强）：经过重复验证的 GWAS 关联结合功能验证——在正确组织中存在 eQTL，且变异位置有调控性染色质标记。这是来自独立来源的相互印证证据。
• T2：经过整理的生物学知识——靶基因属于已知的疾病相关通路（Reactome、GenCC Definitive）。这不能证明变异是通过该通路发挥作用，但能说明这种机制在生物学上具有合理性。
• T3：计算预测——L2G 评分、PPI 网络富集、GO 术语富集。这些用于生成假设，而非证实假设。在 T1/T2 证据稀少时，这类信息很有用。
• T4：单一来源或间接证据——最近基因归属、文献共同提及、文本挖掘关联。这些绝不能成为提出机制性主张的唯一依据。

---

常见错误和回退方案

参数陷阱（正确的参数名称见上方代码块）：

• EnsemblVEP_annotate_rsid 使用 variant_id，而不是 rsid
• MyVariant_query_variants 使用 query，而不是 variant_id
• ReactomeAnalysis_pathway_enrichment 接受以空格分隔的 STRING，而不是数组
• OpenTargets 疾病搜索使用 queryString，而不是 query
• 在 OpenTargets 中使用 MONDO ID（例如，T2D 使用 MONDO_0005148），而不是 EFO ID
• gwas_get_associations_for_trait 已损坏；请使用 gwas_search_associations
• ENCODE 生物样本名称是组织或细胞系，而不是疾病名称

缺少数据时，调整分析方式：

• 没有 eQTL：检查其他组织，仅使用 L2G，并说明置信度有所降低
• 没有 GWAS 命中：变异可能未达到阈值，或与真正的信号处于 LD
• 没有 RegulomeDB 数据：直接检查 ENCODE 中该位置的染色质标记
• 没有 L2G 数据：回退到 eQTL + 最近基因，并适当说明注意事项
• STRING/Reactome 中没有该基因：使用 UniProt 功能 + GO 注释
• 有多个候选基因：按证据排序并列出所有基因，不要强行给出单一答案

---

常见场景推理

场景 1：具有明确调控信号的非编码变异

当 VEP 显示变异位于内含子或基因间区、GWAS 显示与性状存在强关联，且 RegulomeDB 返回高分（1a-2a）时，分析路径很直接：该变异会破坏一个调控元件。关键问题是它调控的是哪个基因。首先检查疾病相关组织中的 eQTL，然后检查 L2G。当两者都指向同一个基因时，继续通过通路分析追踪到疾病。这是“理想路径”，置信度为已确立。

场景 2：靶基因不明确的非编码变异

当变异位于基因间区，附近有多个基因，且 eQTL/L2G 证据较弱或相互矛盾时，不要急于选择最近的基因。相反，应检查该基因座中所有候选基因的 eQTL，比较 L2G 分数，并考虑某个候选基因是否已知具有与疾病相关的生物学功能。按证据强度对多个模型排序并列出。报告为初步或中等置信度。

场景 3：完全没有功能信号

当没有 eQTL、没有 L2G 支持，且调控注释极少时，应如实说明这一缺口。该变异可能通过当前数据库未涵盖的机制发挥作用（细胞类型特异性调控、剪接 QTL、3D 基因组相互作用）。说明检查了哪些内容、哪些结果为阴性，以及哪些实验可以解答这一问题。这是有效且有用的发现。

---

程序化访问（工具之外）

当 ToolUniverse 工具返回的注释不完整时，可直接从多个来源汇总：

import requests, pandas as pd

rsid = "rs12345"

# Ensembl VEP REST — functional consequence prediction
vep = requests.get(f"https://rest.ensembl.org/vep/human/id/{rsid}?content-type=application/json").json()

# GTEx eQTL — tissue-specific expression effects
eqtl = requests.get(f"https://gtexportal.org/api/v2/association/singleTissueEqtl",
    params={"snpId": rsid, "datasetId": "gtex_v8"}).json()

# ClinVar bulk (variant_summary.txt.gz, ~200MB, all variants)
# Download once, filter locally:
# df = pd.read_csv("https://ftp.ncbi.nlm.nih.gov/pub/clinvar/tab_delimited/variant_summary.txt.gz", sep="\t")
# hits = df[df["RS# (dbSNP)"] == int(rsid.replace("rs",""))]

# Combine into unified annotation DataFrame
annotations = {"rsid": rsid, "vep_consequence": vep[0]["most_severe_consequence"] if vep else None,
    "eqtl_tissues": len(eqtl.get("singleTissueEqtl", [])),
    "sources_checked": ["VEP", "GTEx", "ClinVar"]}

API 模式和错误处理请参阅 tooluniverse-data-wrangling skill。

---

局限性

• GTEx eQTL 来自混合组织（v8 数据）；可能无法发现细胞类型特异性效应和剪接效应。
• L2G 和 CADD 是计算预测，并非实验验证。
• GWAS 关联是相关性证据；LD 标记意味着 lead SNP 可能并非因果变异。
• 当前工具难以捕获长距离调控效应（>1Mb）和 3D 基因组相互作用。
• OpenTargets 变异可信集需要 chr_pos_ref_alt 格式；请先从 VEP 获取等位基因。