findscripter 何时使用
适用：
- 判断某变异（rsID / HGVS / 基因组位置）在 ClinVar 是否有临床意义（ClinSig）分类。
- 拉取某基因全部 致病/疑似致病（Pathogenic / Likely Pathogenic）变异。
- 找出提交实验室之间的冲突解读（Conflicting interpretations）。
- 提取变异关联的疾病/表型（OMIM/MIM、MeSH、HPO、trait_name）。
- 构建优先筛选「临床可操作」变异的过滤管线。
不该用（负边界）：
- GWAS 群体层面 SNP-性状关联 → 用
gwas-database。 - 变异功能后果预测（无需先有临床策展）→ 用 Ensembl VEP /
ensembl-database。 - 体细胞肿瘤变异 → 用
cosmic-database（ClinVar 以胚系为主）。
步骤 / 指令
ClinVar 是 NCBI 公共变异解读归档，免认证、免费，经 E-utilities 访问。所有调用须带 email（NCBI 政策）。限速：未认证 3 req/s，带 API key 10 req/s（key 免费注册 https://www.ncbi.nlm.nih.gov/account/）。
依赖：pip install requests pandas（xml.etree 属标准库）。
- ESearch 按结构化查询拿 ClinVar Variation ID 列表。查询字段：
基因[gene]、rsID[rs]、疾病[dis]、OMIM[MIM]、致病性[clinsig]、"审阅状态"[review status]。 - ESummary 按 ID 拿结构化摘要（JSON）。注意 2024 schema 改版：
clinical_significance已被germline_classification取代，trait_set嵌套其下。 - EFetch 拿完整 XML（提交者级断言）。必须
rettype="vcv"+is_variationid="true"；旧rettype="clinvarset"自 2024 起返回空壳。 - 大批量（>~1000 变异）改用 FTP 全量
variant_summary.txt.gz，避免逐条 EFetch 触发限速。
审阅星级（review status，证据质量）：0=无断言标准；1=单提交者有标准；2=多提交者无冲突；3=专家组（ENIGMA/ClinGen）；4=实践指南。自动化管线建议筛 ≥2 星 去噪。
示例
ESearch + ESummary 查某基因致病变异：
import requests, time
EMAIL = "your@email.com" # NCBI 政策必填
BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
def esearch(query, retmax=200):
r = requests.get(f"{BASE}/esearch.fcgi",
params={"db": "clinvar", "term": query, "retmax": retmax,
"retmode": "json", "email": EMAIL})
r.raise_for_status()
res = r.json()["esearchresult"]
return res["idlist"], int(res["count"])
# 致病/疑似致病 BRCA2 变异
ids, total = esearch("BRCA2[gene] AND (pathogenic[clinsig] OR likely pathogenic[clinsig])")
# 按 rsID： esearch("rs80357906[rs]") ；按疾病： esearch("breast cancer[dis] AND pathogenic[clinsig]")
def esummary(ids):
r = requests.post(f"{BASE}/esummary.fcgi",
data={"db": "clinvar", "id": ",".join(ids),
"retmode": "json", "email": EMAIL})
r.raise_for_status()
return r.json()["result"]
result = esummary(ids[:50])
for vid in result.get("uids", []):
rec = result[vid]
gc = rec.get("germline_classification", {}) # 2024 新字段
print(vid, rec.get("title"),
"| ClinSig:", gc.get("description"),
"| Review:", gc.get("review_status"),
"| 疾病:", "; ".join(t.get("trait_name","") for t in gc.get("trait_set", [])))
time.sleep(0.15)
EFetch 拿提交者级断言（XML，vcv）：
import xml.etree.ElementTree as ET
def efetch_xml(variation_ids):
r = requests.post(f"{BASE}/efetch.fcgi",
data={"db": "clinvar", "id": ",".join(variation_ids),
"rettype": "vcv", "is_variationid": "true",
"retmode": "xml", "email": EMAIL}, timeout=30)
r.raise_for_status()
return ET.fromstring(r.text)
root = efetch_xml(["17677"]) # BRCA1 c.5266dupC (rs80357906)
for va in root.iter("VariationArchive"):
gc = va.find("./ClassifiedRecord/Classifications/GermlineClassification")
desc = gc.find("Description") if gc is not None else None
print(va.get("VariationName"), "->", desc.text if desc is not None else "n/a")
for ca in va.iter("ClinicalAssertion"): # 每个提交者一条
acc, cls = ca.find("ClinVarAccession"), ca.find("Classification/GermlineClassification")
if acc is not None and cls is not None:
print(" ", acc.get("SubmitterName","?"), ":", cls.text)
FTP 全量过滤（pandas）：
import pandas as pd
url = "https://ftp.ncbi.nlm.nih.gov/pub/clinvar/tab_delimited/variant_summary.txt.gz"
df = pd.read_csv(url, sep="\t", compression="gzip",
usecols=["Name","GeneSymbol","ClinicalSignificance","ReviewStatus",
"PhenotypeList","Assembly","RS# (dbSNP)"])
df = df[(df["Assembly"]=="GRCh38") &
(df["ClinicalSignificance"].str.contains("Pathogenic", na=False))]
注意事项
- email 必填：所有 E-utility 调用都要带，否则可能被封；生产环境注册 API key 把限速 3→10 req/s。
- 2024 JSON 改版：
KeyError: clinical_significance→ 改用rec["germline_classification"]（另有clinical_impact_classification、oncogenicity_classification，形状相同常为空）；trait_set已移入其内。 - XML 空壳：返回
<ClinVarResult-Set><set/></ClinVarResult-Set>说明用了废弃的rettype="clinvarset"，换vcv+is_variationid="true"，解析根节点<VariationArchive>。 - Variation ID ≠ rsID：ClinVar 给每条解读记录分配稳定整数 Variation ID；一个 rsID 可对应多个 Variation ID（不同等位/解读分别提交）。
- VUS 与冲突解读分开：「Conflicting interpretations of pathogenicity」是独立 ClinSig 类别，勿与 VUS 合并筛选，二者临床含义不同。
- rsID 查空：rsID 未被 ClinVar 索引时
idlist为空，改用 HGVS 或 基因+位置 查询。 - 限速/超时：HTTP 429 → 加
time.sleep(0.35)；EFetch XML 解析错误多因超时，设timeout=30并重试一次。同一 rsID 多结果时按review_status分组，优先高星条目。
互见
gwas-database— GWAS Catalog 群体层面 SNP-性状关联（与 ClinVar 临床断言互补）。ensembl-database— Ensembl VEP 预测变异功能后果，无需先有临床策展。cosmic-database— 体细胞肿瘤变异库（与 ClinVar 胚系侧重互补）。pubmed-database— 检索 ClinVar 提交中引用的支持文献。
采编自 jaechang-hits/SciAgent-Skills（原 license CC0-1.0），按本仓库规范适配重写；本条目以 CC-BY-4.0 发布。