ontology-term-resolution

本体术语解析

适用时机

每当准备记录或信任一个本体标识符时：为元数据列添加注释、填写提交模板、审查他人生成的表格，或检查旧文件中的 ID 是否仍然有效。

规则

绝不凭记忆填写本体 ID，也绝不在未经核查的情况下接受它。

本体 ID 的形式容易记住，具体细节却是任意的。一个看起来合理的 UBERON:0002108 是真实术语（小肠），却不是肝脏；下游流程不会发现这种替换——ID 格式正确、本体也正确，元数据却悄无声息地出错。审稿人也无法发现，因此这类错误会一直留存在已发布的数据集中。

此技能输出的每个 ID 都来自实时 OLS 查询。传入的每个 ID 都会经过验证。Bioregistry、Identifiers.org、ZOOMA 和 Ontobee 可以回答前缀、落地页和简称相关问题，但不能替代 OLS 核查。

使用哪个服务

问题	脚本	权威来源
“左心室”对应哪个术语？	scripts/resolve_terms.py	OLS
OLS 未找到实验室简称（PBMC、WT）	scripts/map_terms.py，然后运行 validate_terms.py	ZOOMA 提议；OLS 判定
EFO:0001067 是否真实、有效且标签正确？	scripts/validate_terms.py	OLS
HPO 是真实前缀吗？HP:notanid 符合格式吗？	scripts/lookup_prefix.py	Bioregistry
这个 CURIE 应打开哪个落地页？	scripts/lookup_prefix.py	Identifiers.org + Ontobee URL

这四个脚本都接受单个值或文件，输出 TSV 或 JSON，且除标准库外不需要其他软件包。有关非 OLS 服务的完整陷阱说明，请参阅 references/companion-apis.md。

将文本解析为术语

cd skills/ontology-term-resolution/scripts

# one string, constrained to the ontology that should define it
python3 resolve_terms.py "liver" --ontology uberon

query   rank  curie           label  ontology  match_type   strategy  defining_ontology
liver   1     UBERON:0002107  liver  uberon    exact_label  exact     true

# a column of tissue names; anything not an exact hit is reported, not guessed
python3 resolve_terms.py --input tissues.txt --ontology uberon \
    --exact-only --format tsv -o resolved.tsv

# accept fuzzy fallbacks, then review the partial hits by hand
python3 resolve_terms.py "left ventrical of heart" --ontology uberon --top 3

搜索会依次升级为 exact（标签和同义词）→ token → fulltext，并在第一个返回结果的策略处停止，同时报告命中了哪种策略。--exact-only 会禁用此搜索阶梯。--branch UBERON:0000465 会将候选项限制为某个术语的后代。

使用结果前请先查看 match_type。 exact_label 和 exact_synonym 是安全匹配；partial 表示 OLS 为一个并非按原样存在的字符串返回了最接近的猜测，需要人工判断。unresolved 是合理的输出——请参阅 references/curation-rules.md，了解哪些规范化处理值得先尝试。

验证现有 ID

python3 validate_terms.py UBERON:0002107 EFO:0001067 UBERON:9999999

id              status     actual_label                  ontology  replacement     detail
UBERON:0002107  ok         liver                         uberon
EFO:0001067     obsolete   obsolete_parasitic infection  efo       MONDO:0005135   obsolete; replaced by MONDO:0005135
UBERON:9999999  not_found                                                          no such term in the ontology this prefix names

只要有任何验证失败，退出代码就是 1；否则为 0；遇到用法错误或网络问题时为 2。因此，它可以作为元数据文件的 CI 检查关卡：

# id + label columns; catches IDs that exist but are labelled as something else
python3 validate_terms.py --input metadata.tsv --strict

# a tissue column must hold UBERON anatomical entities and nothing else
python3 validate_terms.py --input tissue_ids.tsv \
    --branch UBERON:0000465 --expect-ontology uberon

状态	含义	判定
ok	存在、有效，且与所有声明一致	通过
matched_synonym	声明的标签是同义词；主标签不同	警告
imported_only	所属本体已不再声明此 ID	警告
not_a_class	该术语是属性或个体	警告
not_found	不存在此术语	失败
obsolete	已废弃；若存在后继术语，replacement 会给出该术语	失败
label_mismatch	ID 和声明的标签描述的是不同事物	失败
wrong_ontology	ID 类型正确，但不属于此列所用的本体	失败
wrong_branch	不是所要求根术语的后代	失败
malformed_curie	格式不是 PREFIX:local	失败

--strict 会将警告升级为失败。

检查前缀或紧凑标识符

python3 lookup_prefix.py HP HPO HP:0001250 HPO:0001250

query        status          preferred_prefix  canonical_curie  pattern    detail
HP           ok              HP                                 ^\d{7}$
HPO          synonym_prefix  HP                                 ^\d{7}$    'HPO' is a synonym of preferred prefix HP
HP:0001250   ok              HP                HP:0001250       ^\d{7}$
HPO:0001250  synonym_prefix  HP                HP:0001250       ^\d{7}$    'HPO' is a synonym of preferred prefix HP

Bioregistry 接受同义前缀。Identifiers.org 不接受——HPO:0001250 会返回 HTTP 400。将 CURIE 交给 OLS 前，请先改用首选前缀。落地页列来自 Bioregistry 映射（providers.miriam、mappings.ontobee），而非通过首选前缀模板生成：ORPHA:558 会返回 400，orphanet:558 会返回 200，而 OBA 完全没有 Identifiers.org 命名空间。单元格为空表示该服务不托管此前缀。此脚本不会判断术语是否存在；这仍需通过 validate_terms.py 验证。

映射实验室简称（ZOOMA）

# after resolve_terms.py returned unresolved / partial
python3 map_terms.py PBMC --ontology cl --exact-only

--ontology 是必需参数。未筛选的 ZOOMA annotate 对 liver 的返回结果中，除 UBERON 外还包含 FOODON、XAO 和 BTO，且置信度均为 HIGH。HIGH/GOOD 命中仅是候选项——写下任何 CURIE 前，都要对其运行 validate_terms.py。

可能误导你的 API 行为

以下行为已通过实时服务验证，也是此技能提供脚本而非操作指南的原因。详情请参阅 references/ols4-api.md。

陷阱	后果
exact=true 执行精确的词元匹配	liver 在 UBERON 中返回 161 个命中；添加 queryFields=label 后返回 1 个
/search 从不返回 is_obsolete 或 term_replaced_by	在 fieldList 中指定这些字段也会被静默丢弃；只有术语详情才能回答“此 ID 是否仍有效”
ontology=efo 会返回 MONDO 和 CL 命中	本体彼此导入；请自行按 CURIE 前缀筛选
同一术语会在每个导入它的本体中各出现一次	按 obo_id 去重，并保留 is_defining_ontology: true 的条目
obo_id 索引存在缺失	MONDO:0000001 有效，但未按 obo_id 编入索引；必须回退到 IRI，以免误报 not_found
并非所有 IRI 都是 OBO PURL	EFO 和 Orphanet 使用各自的命名空间——应解析 IRI，不要套用模板
OxO 已退役	返回 HTTP 200，但内容是 HTML；请改用术语交叉引用或 SSSOM
分支检查无法排除解剖学中的细胞类型	CARO 将 cell 置于 anatomical structure 下；还要限制前缀
ZOOMA 未筛选本体	liver 会返回 100 多个来自 FOODON、XAO、BTO、UBERON 的 HIGH 命中
Identifiers.org 同义词前缀	HPO:0001250 返回 HTTP 400；Bioregistry 接受相同的 CURIE
Identifiers.org 对冒号进行编码	HP%3A0001250 返回 HTTP 400；路径必须保留 :
Bioregistry 的 preferred_prefix 不是 Identifiers.org 命名空间	ORPHA:558 返回 400；orphanet:558 返回 200。hp:0001250 和 chebi:15377 返回 400，因为这些命名空间会将前缀嵌入 LUI。请使用 /api/reference/{CURIE} 中的 providers.miriam；如果缺少该映射（OBA、XAO、ECTO），则省略 URL
Ontobee 搜索	仅提供 HTML 页面——没有 JSON API；不要抓取该页面

选择本体

疾病使用 MONDO，表型使用 HP，组织使用 UBERON，细胞类型使用 CL，检测使用 EFO，化合物使用 ChEBI，生物使用 NCBITaxon，性别和 normal 使用 PATO。前缀到 OLS ID 的映射（HP 以 hp 提供服务，Orphanet 以 ordo 提供服务）、--branch 的分支根，以及重叠本体的判定说明见 references/ontology-registry.md。

报告结果

请同时给出 ID 和标签，并说明各自的匹配方式。只有 ID 的表格无法审核。请明确列出未解决的术语，不要用最接近的命中来填补。

参考资料

• references/ols4-api.md — 端点、参数、响应字段，以及每个已验证的 OLS 陷阱。
• references/companion-apis.md — Bioregistry、Identifiers.org、ZOOMA 和 Ontobee：何时使用，以及哪些陷阱会让未筛选查询或同义词前缀查询看似成功。
• references/ontology-registry.md — 前缀／本体 ID 表、分支根，以及各本体负责的概念。
• references/curation-rules.md — 候选项筛选流程、需重试的标准化形式、现有表格审核、已废弃术语、跨本体映射。

Agent 操作流程

1. 检查环境。 确认网络访问、API 密钥（如需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，而不是猜测。
3. 先运行小规模版本。 获取一条已知记录，并在批量查询前检查响应格式。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数量，并记录数据库版本或访问日期。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	采用退避策略、批量发送请求并遵守速率限制，如实报告部分结果。
这些说明中的函数、标志或端点在已安装版本中缺失	查看已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿虚构 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直说。
• 切勿编造登录号、ID 或记录；如未找到，请报告“未找到”。
• 将此处与版本相关的细节视为可能已过时：请根据已安装版本的官方文档进行确认。
• 涉及付费、消耗共享 GPU 或云配额、访问个人或患者数据，或无法撤销的操作前，请先征求许可。