企业官网建设流程全解析

OneKGPd 注释过滤词表全解：Consequence、Impact、BioType、ClinVar 与 AlphaMissense 受控词汇完整参考

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本文以 scientific-agent-skills 仓库中 OneKGPd Skill 的 annotation_vocabularies.md 为核心，系统整理onekgpd_api.py全部 CSV 注释过滤参数（--consequence、--impact、--variant-type、--feature-type、--bio-type、--clin-significance、--alpha-missense-class）的受控词汇全集、组合语义与底层实现。读者阅读后即可准确无误地构造针对 1000 Genomes Project（3,202 个全基因组测序个体，GRCh38）的变体与个体筛选查询，避免因词表拼写错误或组合冲突导致的查询失败与结果误读。

一、受控词表的设计哲学：为什么需要它

OneKGPd 允许 Agent 在 1000 Genomes Project 队列上按注释维度筛选变体和个体。注释字段（如"错义变体"、"致病性"、"长链非编码 RNA"）在生物信息学中天然存在同义词与大小写差异，若允许自由文本匹配，将产生两类严重问题：

1. 歧义：missense、Missense_variant、MISSENSE_VARIANT写法各异，难以保证语义等价；
2. 不可组合：跨字段自由文本无法可靠地按"AND/OR"逻辑组合。

因此 OneKGPd 为每个注释过滤标志定义了封闭的受控词汇表（controlled vocabulary），并强制执行"按精确成员名解析"。该设计在 onekgpd_api.py 的_CSV_FIELDS常量中可见一斑：CLI 参数名与底层AnnotationFilter字段一一映射，所有 CSV 值最终通过 annotation_vocabularies.md 中列出的枚举解析为强类型库枚举：

_CSV_FIELDS = [ ("clin_significance", "clin_significance"), ("consequence", "consequence"), ("impact", "impact"), ("variant_type", "variant_type"), ("feature_type", "feature_type"), ("bio_type", "bio_type"), ("alpha_missense_class", "am_class"), ]

测试用例 tests/onekgpd/test_scripts.py 验证了 CSV 词条被转换为库枚举元组的底层行为：

built = onekgpd_api._build_annotation_filter( region_args(consequence="MISSENSE_VARIANT,STOP_GAINED") ) assert built.consequence == ( dnaerys.Consequence.MISSENSE_VARIANT, dnaerys.Consequence.STOP_GAINED, )

二、词表的基本使用规则

所有注释过滤标志共享以下语义规则（同样适用于count-variants、select-variants、count-variants-in-samples、select-variants-in-samples、count-samples、select-samples六个命令）：

值得强调的是"同标志内 OR、跨标志 AND"的组合语义。在 onekgpd_api.py 的_build_annotation_filter中，各字段被独立组装为AnnotationFilter的 kwargs，再整体传给服务端，由服务端执行 AND/OR 组合。测试 tests/onekgpd/test_scripts.py 验证了非法词条的拒绝行为：

def test_an_unknown_vocabulary_term_is_rejected(self) -> None: with self.assertRaisesRegex(ValueError, "MISSENSE_VARIANTS"): onekgpd_api._build_annotation_filter( region_args(consequence="MISSENSE_VARIANTS") )

注意：词表是硬编码校验的，MISSENSE_VARIANTS（多一个 S）这类"看起来合理"的值会被直接拒绝，因此必须严格对照本词表拼写。

三、Consequence（Sequence Ontology 后果术语）—--consequence

该标志对应 VEP/Ensembl 的 Sequence Ontology（SO）后果分类，共41 个合法词条。它是最常用的功能影响筛选维度，用于挑选具有特定转录本后果（如终止密码子获得、移码、错义）的变体。

实战示例——筛选 BRCA1 区域（GRCh38）中所有错义或终止获得型变体：

uv run scripts/onekgpd_api.py count-variants \ --chrom chr17 --start 43044292 --end 43170245 \ --consequence MISSENSE_VARIANT,STOP_GAINED \ --output /tmp/brca1_consequence.json

四、Impact（VEP 影响等级）—--impact

对应 VEP 对每个变体后果的影响等级判定，共4 个合法词条，按严重程度递减排列：

由于 Impact 与 Consequence 之间存在天然对应关系，二者常组合使用以"以 AND 语义收窄结果集"。例如只保留高影响的变体：

uv run scripts/onekgpd_api.py select-variants \ --region chr17:43044292-43170245 \ --impact HIGH \ --output /tmp/high_impact.json

五、VariantType（SO 变体类别）—--variant-type

对应 Sequence Ontology 的变体类别分类，共34 个合法词条，覆盖单核苷酸到复杂结构变异：

该字段可用于专门检索结构变异（structural variant），例如查找目标区域内所有缺失（DELETION）与插入（INSERTION）：

uv run scripts/onekgpd_api.py count-samples \ --region chr1:1000000-2000000 \ --variant-type DELETION,INSERTION \ --output /tmp/sv_carriers.json

六、FeatureType（VEP 特征类型）—--feature-type

对应 VEP 注释落入的特征类型，仅3 个合法词条：

配合--consequence TFBS_ABLATION等调控后果使用，可聚焦非转录本注释。

七、BioType（VEP 生物型）—--bio-type

对应 VEP 的基因/转录本生物型（biotype），共47 个合法词条，是词表最庞大的一类：

实战示例——筛选某区域内落在蛋白编码基因转录本上的变体：

uv run scripts/onekgpd_api.py count-variants \ --chrom chr12 --start 121400000 --end 121450000 \ --bio-type PROTEIN_CODING \ --consequence MISSENSE_VARIANT \ --output /tmp/protein_coding_mis.json

八、ClinSignificance（ClinVar 临床意义）—--clin-significance

对应 ClinVar 数据库（版本 202502）的临床意义分类，共19 个合法词条：

注意：CLNSIG_前缀陷阱

这是整个词表最容易踩的坑——ClinVar 中表示"良性"的词条是CLNSIG_BENIGN（注意CLNSIG_前缀），而其余全部 ClinSignificance 词条都是裸词条（无前缀）。也就是说：

• ✅--clin-significance CLNSIG_BENIGN—— 良性
• ✅--clin-significance PATHOGENIC—— 致病性
• ❌--clin-significance BENIGN—— 不在词表中，会被拒绝

实战示例——查找区域内携带 ClinVar 致病性或疑似致病性变体的个体：

uv run scripts/onekgpd_api.py count-samples \ --chrom chr17 --start 43044292 --end 43170245 \ --clin-significance PATHOGENIC,LIKELY_PATHOGENIC \ --output /tmp/clinvar_path.json

九、AlphaMissense（错义预测分类）—--alpha-missense-class

对应 AlphaMissense 对错义变体的致病性预测分类，仅3 个合法词条：

与 AlphaMissense 分数上下界互斥

AlphaMissense 分类（--alpha-missense-class）与 AlphaMissense 分数范围（--alpha-missense-score-lt/--alpha-missense-score-gt）是互斥的：二者只能设置其一，不能同时设置。该互斥性在 onekgpd_api.py 中由显式校验强制实现：

if kwargs.get("am_class") and ("am_score_lt" in kwargs or "am_score_gt" in kwargs): _fail( "Error: --alpha-missense-class cannot be combined with " "--alpha-missense-score-lt/--alpha-missense-score-gt" )

测试 tests/onekgpd/test_scripts.py 同样覆盖了此拒绝路径。原因在 SKILL.md 中亦有说明：分类本身就是由分数阈值派生的，同时指定二者属于语义矛盾。此外还需留意 SKILL.md 中的另一条约定：返回变体的am_score为0.0表示未注释/未打分，并不代表良性，真实 AlphaMissense 分数恒大于 0。

实战示例——查找 BRCA1 区域内携带"疑似致病"AlphaMissense 分类错义变体的个体：

uv run scripts/onekgpd_api.py count-samples \ --chrom chr17 --start 43044292 --end 43170245 \ --consequence MISSENSE_VARIANT \ --alpha-missense-class AM_LIKELY_PATHOGENIC \ --output /tmp/am_lp_count.json

十、词表完整速查表

下表汇总全部七个过滤字段的词条数量与来源标准，便于 Agent 快速定位：

十一、词表之外：与相邻参数协同的注意点

词表并非孤立存在，使用注释过滤时还需留意与之协同的相邻参数语义：

1. 互斥开关对：除 AlphaMissense 分类/分数外，--biallelic-only/--multiallelic-only、--exclude-males/--exclude-females、--het-only/--hom-only也两两互斥，见 onekgpd_api.py 的 argparse 互斥组定义。

2. 过滤字段不等于返回字段：ClinVar 临床意义与 VEP consequence 仅作为服务端筛选条件，不会回显到返回的变体 JSON 中。返回变体固定携带 22 个键（chr/start/end/ref/alt/af/ac/an/hom_samples/het_samples/mis_samples及 X/Y 染色体性别拆分、gnomAD AF、am_score、amino_acids、biallelic），完整 schema 见 onekgpd_commands.md。

3. 等位频率的 0.0 语义：--gnomad-exomes-af-gt 0选择"存在于 gnomAD 外显子组"的变体；而--gnomad-*-af-lt边界包含未注释变体（gnomAD AF 为 0），如需排除需与--gnomad-*-af-gt 0联用。

4. 非法词条的错误信息：词表外的值会以错误形式拒绝并列出合法值，例如将MISSENSE_VARIANT误写为MISSENSE_VARIANTS即触发ValueError。这意味着词表是"白名单"式的，宁可多查 annotation_vocabularies.md 也不可凭记忆拼写。

十二、典型组合工作流：从词表到个体名单

将词表与 OneKGPd 的"先计数、后选择"规范结合，即构成完整的科学查询流水线。以下为 SKILL.md 中 Quick Start 的完整展开，同时使用了本文全部核心词表维度：

# 1. 先解析坐标（必须）：BRCA1 在 GRCh38 上为 chr17:43044292-43170245 # 2. 先计数：区域内有携带"疑似致病"错义变体的个体多少个？ uv run scripts/onekgpd_api.py count-samples \ --chrom chr17 --start 43044292 --end 43170245 \ --consequence MISSENSE_VARIANT \ --alpha-missense-class AM_LIKELY_PATHOGENIC \ --output /tmp/count.json # 3. 计数可控后，列出这些个体 uv run scripts/onekgpd_api.py select-samples \ --chrom chr17 --start 43044292 --end 43170245 \ --consequence MISSENSE_VARIANT \ --alpha-missense-class AM_LIKELY_PATHOGENIC \ --output /tmp/samples.json # 4. 对个体名单中的实际变体进行查询 uv run scripts/onekgpd_api.py select-variants-in-samples \ --chrom chr17 --start 43044292 --end 43170245 \ --samples HG03169,NA20506 \ --consequence MISSENSE_VARIANT \ --alpha-missense-class AM_LIKELY_PATHOGENIC \ --output /tmp/variants.json

更复杂的多维度 AND 组合可同时叠加 ClinVar 与 impact，例如寻找"高影响且 ClinVar 致病性"的变体携带个体：

uv run scripts/onekgpd_api.py count-samples \ --region chr17:43044292-43170245 \ --impact HIGH \ --clin-significance PATHOGENIC,LIKELY_PATHOGENIC \ --output /tmp/high_clinvar.json

延伸阅读

• onekgpd_api.py —— 注释过滤参数的解析与AnnotationFilter构建实现
• onekgpd_commands.md —— 全命令参数表与返回变体 22 键 schema
• SKILL.md —— OneKGPd 技能总览、坐标溯源规范与典型工作流
• test_scripts.py —— 词表解析、非法词条拒绝与互斥校验的测试证据
• onekgpd_meta.py —— 离线样本/人群元数据命令（与变体查询可组合）

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills