OpenMed 变体注释实战VEP 注释 VCF、HGVS 规范化、gnomAD 频率与临床上下文联动【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed本文基于 OpenMed 仓库中 annotating-variants 技能 完整展开如何用免费、许可宽松的公开工具Ensembl VEP REST、离线 VEP/SnpEff/ANNOVAR把 VCF 行、rsID 或 HGVS 字符串注释为带后果预测missense、stop-gain、splice 等的记录并关联 gnomAD 群体等位基因频率与 OpenMed 从临床文本中提取的基因/变异/肿瘤学上下文。读完本文你可以独立完成单变体 REST 注释、批量区域注释、群体频率查询以及分子发现 表型上下文的可解释记录拼装。技能定位与许可边界OpenMed 是一个本地优先local-first的临床/生物医学 NLP 库其 skills 目录 为 Claude Code、Codex、OpenCode 等编码 Agent 提供 73 个可移植技能包annotating-variants属于其中Research genomics类别配对关系为↔ adjacent相邻任务双向交接。该技能的许可边界非常明确所用的注释工具免费且许可宽松Ensembl、gnomAD、ClinVar 等开放资源受限的临床解读数据库如商业授权的 HGMD由用户自行提供技能本身不捆绑任何受限数据技能只产生注释annotation不产生诊断或致病性判断——致病性分类ACMG/AMP依赖用户自行提供的 curated 证据与许可数据库。适用场景当你处于以下任一情形时应选用该技能手上有一份 VCF / HGVS 字符串 / rsID需要后果预测missense、stop-gain、splice 后果、受影响的转录本和蛋白质变化需要在已知基因组版本默认 GRCh38GRCh37 走专用端点上把HGVS 规范化为基因组坐标以及反向映射需要gnomAD 群体等位基因频率来区分常见变异与罕见变异需要把分子发现与 OpenMed 从病历或文献中提取的表型/肿瘤学上下文配对。快速开始Ensembl VEP REST 实际调用默认 Base URL 为https://rest.ensembl.orgGRCh38GRCh37 数据必须使用https://grch37.rest.ensembl.org。默认物种为human/homo_sapiens。单变体 HGVS 注释GETimport requests REST https://rest.ensembl.org HEADERS {Content-Type: application/json, Accept: application/json} def vep_hgvs(hgvs: str) - list[dict]: Annotate a single HGVS variant (GET). r requests.get(f{REST}/vep/human/hgvs/{hgvs}, headersHEADERS, timeout30) r.raise_for_status() return r.json() # Transcript-level HGVS (coding) — note the build-aware default transcript set ann vep_hgvs(ENST00000269305.9:c.215CG) # TP53 example v ann[0] print(v[most_severe_consequence]) # e.g. missense_variant for tc in v.get(transcript_consequences, []): print(tc[gene_symbol], tc.get(hgvsp), tc.get(sift_prediction), tc.get(polyphen_prediction))等价 cURLcurl https://rest.ensembl.org/vep/human/hgvs/ENST00000269305.9:c.215CG \ -H Content-Type:application/json批量区域注释POST每请求最多 200 条变体列表使用region格式CHROM POS ID REF ALT . . .1-based 坐标def vep_region_batch(variants: list[str]) - list[dict]: body {variants: variants} # [17 7676154 . C G . . ., ...] 1-based r requests.post(f{REST}/vep/human/region, headersHEADERS, jsonbody, timeout60) r.raise_for_status() return r.json()响应关键字段每个变体的响应中需要重点消费most_severe_consequence—— 该变体的最严重后果等级如missense_varianttranscript_consequences[]—— 按转录本展开gene_symbol、hgvsc、hgvsp、sift_prediction、polyphen_prediction、impactcolocated_variants[]—— 共定位的 rsID 及群体频率。如需 gnomAD 频率与 ClinVar 信息通过 VEP 的 options/plugins 请求REST 默认返回不含完整频率字段。群体频率查询gnomAD GraphQL要拿到权威等位基因频率用 gnomAD GraphQL APIhttps://gnomad.broadinstitute.org/api。变体 ID 使用chrom-pos-ref-alt形式如17-7676154-C-G。关键细节子群体频率要从ac/anallele count / allele number推导而不是请求子群体上不存在的af字段。GNOMAD https://gnomad.broadinstitute.org/api QUERY query Variant($id: String!, $ds: DatasetId!) { variant(variantId: $id, dataset: $ds) { variant_id rsids genome { ac an af homozygote_count } exome { ac an af homozygote_count } } } def gnomad_freq(variant_id: str, dataset: str gnomad_r4) - dict: r requests.post(GNOMAD, json{query: QUERY, variables: {id: variant_id, ds: dataset}}, timeout30) r.raise_for_status() return r.json()[data][variant] # gnomad_freq(17-7676154-C-G) - ac/an/af for exome and genome注意 gnomAD 的 schema 在版本之间会变化跟踪当前 schema 版本后再定稿查询语句。规模化离线注释VEP / SnpEff / ANNOVAR 选型整 VCF 作业不要走逐变体 REST应改用本地注释器工具优势备注Ensembl VEP离线注释最丰富插件生态gnomAD、CADD、SpliceAI支持 HGVS每个基因组构建需下载对应 cacheSnpEff快自带基因组数据库、自包含适合大批量后果判定ANNOVAR可挂接多种注释数据库需要注册许可条款适用三者都能输出逐变体的基因、后果以及配好数据库后频率与临床字段。全程保持参考构建版本GRCh38端到端一致是硬性要求。标准五步工作流规范化输入VCF 等位基因先 left-align/trimHGVS 输入需确认参考转录本与基因组构建版本注释少量变体走 REST/vep/human/hgws的 GET 或/vep/human/region的 POST整份 VCF 走离线 VEP/SnpEff挂频率从 gnomAD 取频率标记常见变体例如 AF 1%过滤/优先级排序按most_severe_consequence、impact 等级与罕见程度排序与 OpenMed 临床上下文合并用 OpenMed 提取的基因/变异提及、肿瘤学与表型信息拼装出可解释的记录。与 OpenMed 的双向交接技能文档明确了两条数据通路OpenMed → 变体上下文调用openmed.analyze_text(report, model_nameGenomics 或 Oncology 模型)从病理或分子报告中提取基因符号、变异提及如 EGFR L858R和肿瘤学发现用于 (a) 筛选 VCF 中哪些变体值得关注(b) 为每条注释附加表型上下文。变体 → OpenMed报告自由文本中的变异描述先在本技能侧规范化为 HGVS再由 OpenMed 结构化周围临床叙述——把基因型链接到提取出的表型/诊断。隐私底线基因组数据与临床数据保持本地。REST/GraphQL 调用只携带变体坐标公开的等位基因数据绝不携带患者标识符任何叙述文本先用openmed.deidentify脱敏再出网。这两条通路在仓库源码中均有对应实现analyze_text是 OpenMed 的核心公开 API定义于 openmed/init.py接受text、model_name注册表 key、完整 HF 模型 ID 或本地路径、output_formatdict/json/html/csv、confidence_threshold等参数并支持句级检测与实体分组deidentify通过惰性导入导出实现位于openmed/core/pii.py见 openmed/init.py 中的deidentify: .core.pii映射技能要求的先脱敏再交接正是调用它肿瘤学上下文提取可落到仓库模型注册表中的真实模型models.jsonl 收录了OpenMed-NER-OncologyDetect-*系列如 278M/560M 的 BigMed、108M 的 BioClinical 及对应 MLX、ONNX-Android 运行时格式其 canonical labels 包含GENE_OR_GENE_PRODUCT、CANCER、CELL等——这与技能里EGFR L858R 这类变异提及 肿瘤学发现的提取目标一一对应说明该技能的模型选择建议选 Genomics/Oncology 模型在当前仓库的注册表中是可直接落地的。边界情况与常见陷阱技能文档列出的六条陷阱按严重度排序值得逐条落实构建版本错配是第一号错误。GRCh38 坐标打到 GRCh37 端点或 GRCh37 cache上会得到错误的基因归属。grch37.rest.ensembl.org只能用于 GRCh37 数据默认 REST 是 GRCh38。转录本选择会改变 HGVS。c./p.记法依赖参考转录本MANE Select vs 其他必须显式固定转录本。先规范化再注释。未 left-align 的 indel 和多等位 VCF 行会产生不一致的注释——先分解decompose并规范化如bcftools norm。REST 有速率限制。Ensembl REST 约 15 req/s、每次 POST 200 个变体大 VCF 切换到离线 VEP遇到 429 遵守Retry-After。gnomAD 子群体字段陷阱。子群体查询ac/an后自行计算 AF部分 schema 路径直接拒绝af——gnomAD 每次发布都可能变 schema务必跟踪当前版本。这里不做临床解读。后果consequence≠ 致病性pathogenicity。ACMG/AMP 分类需要 curated 证据与用户自供的许可数据库本技能产出的是注释不是诊断。相关标准与规范涉及的数据与记法规范仓库技能文档中给出了对应规范出处此处列出以便对照VCF 规范VCFv4.4 规范文档hts-specsHGVS 命名法HGVS Nomenclature 官方规范站Ensembl VEP RESTvep_hgvs_get、vep_region_post两个端点的官方文档与 VEP 离线版SnpEff工具文档gnomAD APIhttps://gnomad.broadinstitute.org/api与ClinVar。上述资源均为公开、免费或用户自备许可与 OpenMed 技能体系仅使用开放资源、受限数据库用户自供的边界一致。小结annotating-variants技能把从原始变体到可解释记录这条链路拆成了清晰可复用的环节输入规范化 → VEP REST/离线注释 → gnomAD 频率挂载 → 后果与罕见度过滤 → 与 OpenMed 提取的临床上下文合并并始终守住两条红线坐标一致构建/转录本、数据本地只把公共变体坐标出网叙述文本先经openmed.deidentify脱敏。配合仓库中真实的analyze_textAPI、OncologyDetect 系列模型与deidentify实现这条从基因型到表型的本地优先工作流在 OpenMed 生态内可以直接落地运行。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMed 变体注释实战：VEP 注释 VCF、HGVS 规范化、gnomAD 频率与临床上下文联动
OpenMed 变体注释实战VEP 注释 VCF、HGVS 规范化、gnomAD 频率与临床上下文联动【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed本文基于 OpenMed 仓库中 annotating-variants 技能 完整展开如何用免费、许可宽松的公开工具Ensembl VEP REST、离线 VEP/SnpEff/ANNOVAR把 VCF 行、rsID 或 HGVS 字符串注释为带后果预测missense、stop-gain、splice 等的记录并关联 gnomAD 群体等位基因频率与 OpenMed 从临床文本中提取的基因/变异/肿瘤学上下文。读完本文你可以独立完成单变体 REST 注释、批量区域注释、群体频率查询以及分子发现 表型上下文的可解释记录拼装。技能定位与许可边界OpenMed 是一个本地优先local-first的临床/生物医学 NLP 库其 skills 目录 为 Claude Code、Codex、OpenCode 等编码 Agent 提供 73 个可移植技能包annotating-variants属于其中Research genomics类别配对关系为↔ adjacent相邻任务双向交接。该技能的许可边界非常明确所用的注释工具免费且许可宽松Ensembl、gnomAD、ClinVar 等开放资源受限的临床解读数据库如商业授权的 HGMD由用户自行提供技能本身不捆绑任何受限数据技能只产生注释annotation不产生诊断或致病性判断——致病性分类ACMG/AMP依赖用户自行提供的 curated 证据与许可数据库。适用场景当你处于以下任一情形时应选用该技能手上有一份 VCF / HGVS 字符串 / rsID需要后果预测missense、stop-gain、splice 后果、受影响的转录本和蛋白质变化需要在已知基因组版本默认 GRCh38GRCh37 走专用端点上把HGVS 规范化为基因组坐标以及反向映射需要gnomAD 群体等位基因频率来区分常见变异与罕见变异需要把分子发现与 OpenMed 从病历或文献中提取的表型/肿瘤学上下文配对。快速开始Ensembl VEP REST 实际调用默认 Base URL 为https://rest.ensembl.orgGRCh38GRCh37 数据必须使用https://grch37.rest.ensembl.org。默认物种为human/homo_sapiens。单变体 HGVS 注释GETimport requests REST https://rest.ensembl.org HEADERS {Content-Type: application/json, Accept: application/json} def vep_hgvs(hgvs: str) - list[dict]: Annotate a single HGVS variant (GET). r requests.get(f{REST}/vep/human/hgvs/{hgvs}, headersHEADERS, timeout30) r.raise_for_status() return r.json() # Transcript-level HGVS (coding) — note the build-aware default transcript set ann vep_hgvs(ENST00000269305.9:c.215CG) # TP53 example v ann[0] print(v[most_severe_consequence]) # e.g. missense_variant for tc in v.get(transcript_consequences, []): print(tc[gene_symbol], tc.get(hgvsp), tc.get(sift_prediction), tc.get(polyphen_prediction))等价 cURLcurl https://rest.ensembl.org/vep/human/hgvs/ENST00000269305.9:c.215CG \ -H Content-Type:application/json批量区域注释POST每请求最多 200 条变体列表使用region格式CHROM POS ID REF ALT . . .1-based 坐标def vep_region_batch(variants: list[str]) - list[dict]: body {variants: variants} # [17 7676154 . C G . . ., ...] 1-based r requests.post(f{REST}/vep/human/region, headersHEADERS, jsonbody, timeout60) r.raise_for_status() return r.json()响应关键字段每个变体的响应中需要重点消费most_severe_consequence—— 该变体的最严重后果等级如missense_varianttranscript_consequences[]—— 按转录本展开gene_symbol、hgvsc、hgvsp、sift_prediction、polyphen_prediction、impactcolocated_variants[]—— 共定位的 rsID 及群体频率。如需 gnomAD 频率与 ClinVar 信息通过 VEP 的 options/plugins 请求REST 默认返回不含完整频率字段。群体频率查询gnomAD GraphQL要拿到权威等位基因频率用 gnomAD GraphQL APIhttps://gnomad.broadinstitute.org/api。变体 ID 使用chrom-pos-ref-alt形式如17-7676154-C-G。关键细节子群体频率要从ac/anallele count / allele number推导而不是请求子群体上不存在的af字段。GNOMAD https://gnomad.broadinstitute.org/api QUERY query Variant($id: String!, $ds: DatasetId!) { variant(variantId: $id, dataset: $ds) { variant_id rsids genome { ac an af homozygote_count } exome { ac an af homozygote_count } } } def gnomad_freq(variant_id: str, dataset: str gnomad_r4) - dict: r requests.post(GNOMAD, json{query: QUERY, variables: {id: variant_id, ds: dataset}}, timeout30) r.raise_for_status() return r.json()[data][variant] # gnomad_freq(17-7676154-C-G) - ac/an/af for exome and genome注意 gnomAD 的 schema 在版本之间会变化跟踪当前 schema 版本后再定稿查询语句。规模化离线注释VEP / SnpEff / ANNOVAR 选型整 VCF 作业不要走逐变体 REST应改用本地注释器工具优势备注Ensembl VEP离线注释最丰富插件生态gnomAD、CADD、SpliceAI支持 HGVS每个基因组构建需下载对应 cacheSnpEff快自带基因组数据库、自包含适合大批量后果判定ANNOVAR可挂接多种注释数据库需要注册许可条款适用三者都能输出逐变体的基因、后果以及配好数据库后频率与临床字段。全程保持参考构建版本GRCh38端到端一致是硬性要求。标准五步工作流规范化输入VCF 等位基因先 left-align/trimHGVS 输入需确认参考转录本与基因组构建版本注释少量变体走 REST/vep/human/hgws的 GET 或/vep/human/region的 POST整份 VCF 走离线 VEP/SnpEff挂频率从 gnomAD 取频率标记常见变体例如 AF 1%过滤/优先级排序按most_severe_consequence、impact 等级与罕见程度排序与 OpenMed 临床上下文合并用 OpenMed 提取的基因/变异提及、肿瘤学与表型信息拼装出可解释的记录。与 OpenMed 的双向交接技能文档明确了两条数据通路OpenMed → 变体上下文调用openmed.analyze_text(report, model_nameGenomics 或 Oncology 模型)从病理或分子报告中提取基因符号、变异提及如 EGFR L858R和肿瘤学发现用于 (a) 筛选 VCF 中哪些变体值得关注(b) 为每条注释附加表型上下文。变体 → OpenMed报告自由文本中的变异描述先在本技能侧规范化为 HGVS再由 OpenMed 结构化周围临床叙述——把基因型链接到提取出的表型/诊断。隐私底线基因组数据与临床数据保持本地。REST/GraphQL 调用只携带变体坐标公开的等位基因数据绝不携带患者标识符任何叙述文本先用openmed.deidentify脱敏再出网。这两条通路在仓库源码中均有对应实现analyze_text是 OpenMed 的核心公开 API定义于 openmed/init.py接受text、model_name注册表 key、完整 HF 模型 ID 或本地路径、output_formatdict/json/html/csv、confidence_threshold等参数并支持句级检测与实体分组deidentify通过惰性导入导出实现位于openmed/core/pii.py见 openmed/init.py 中的deidentify: .core.pii映射技能要求的先脱敏再交接正是调用它肿瘤学上下文提取可落到仓库模型注册表中的真实模型models.jsonl 收录了OpenMed-NER-OncologyDetect-*系列如 278M/560M 的 BigMed、108M 的 BioClinical 及对应 MLX、ONNX-Android 运行时格式其 canonical labels 包含GENE_OR_GENE_PRODUCT、CANCER、CELL等——这与技能里EGFR L858R 这类变异提及 肿瘤学发现的提取目标一一对应说明该技能的模型选择建议选 Genomics/Oncology 模型在当前仓库的注册表中是可直接落地的。边界情况与常见陷阱技能文档列出的六条陷阱按严重度排序值得逐条落实构建版本错配是第一号错误。GRCh38 坐标打到 GRCh37 端点或 GRCh37 cache上会得到错误的基因归属。grch37.rest.ensembl.org只能用于 GRCh37 数据默认 REST 是 GRCh38。转录本选择会改变 HGVS。c./p.记法依赖参考转录本MANE Select vs 其他必须显式固定转录本。先规范化再注释。未 left-align 的 indel 和多等位 VCF 行会产生不一致的注释——先分解decompose并规范化如bcftools norm。REST 有速率限制。Ensembl REST 约 15 req/s、每次 POST 200 个变体大 VCF 切换到离线 VEP遇到 429 遵守Retry-After。gnomAD 子群体字段陷阱。子群体查询ac/an后自行计算 AF部分 schema 路径直接拒绝af——gnomAD 每次发布都可能变 schema务必跟踪当前版本。这里不做临床解读。后果consequence≠ 致病性pathogenicity。ACMG/AMP 分类需要 curated 证据与用户自供的许可数据库本技能产出的是注释不是诊断。相关标准与规范涉及的数据与记法规范仓库技能文档中给出了对应规范出处此处列出以便对照VCF 规范VCFv4.4 规范文档hts-specsHGVS 命名法HGVS Nomenclature 官方规范站Ensembl VEP RESTvep_hgvs_get、vep_region_post两个端点的官方文档与 VEP 离线版SnpEff工具文档gnomAD APIhttps://gnomad.broadinstitute.org/api与ClinVar。上述资源均为公开、免费或用户自备许可与 OpenMed 技能体系仅使用开放资源、受限数据库用户自供的边界一致。小结annotating-variants技能把从原始变体到可解释记录这条链路拆成了清晰可复用的环节输入规范化 → VEP REST/离线注释 → gnomAD 频率挂载 → 后果与罕见度过滤 → 与 OpenMed 提取的临床上下文合并并始终守住两条红线坐标一致构建/转录本、数据本地只把公共变体坐标出网叙述文本先经openmed.deidentify脱敏。配合仓库中真实的analyze_textAPI、OncologyDetect 系列模型与deidentify实现这条从基因型到表型的本地优先工作流在 OpenMed 生态内可以直接落地运行。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考