Ontology Term Resolution
When to use
Any time an ontology identifier is about to be written down or trusted: annotating a metadata
column, filling a submission template, auditing a table someone else produced, or checking whether
an ID in an old file is still current.
The rule
Never write an ontology ID from memory, and never accept one without checking it.
Ontology IDs are memorable in form and arbitrary in detail. A plausible-looking UBERON:0002108
is a real term (small intestine) that is not the liver, and nothing downstream will catch the
substitution — the ID is well-formed, the ontology is right, and the metadata is silently wrong.
Reviewers cannot spot it either, which is why these errors persist into published datasets.
Every ID this skill emits comes from a live OLS lookup. Every ID it is handed gets verified.
Two directions
| Direction | Script | Question answered |
|---|
| text → ID | scripts/resolve_terms.py | What is the term for "left ventricle"? |
| ID → verdict | scripts/validate_terms.py | Is EFO:0001067 real, current, and labelled what this file claims? |
Both take single values or files, emit TSV or JSON, and need no packages beyond the standard
library.
Resolve text to terms
cd skills/ontology-term-resolution/scripts
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
python3 resolve_terms.py --input tissues.txt --ontology uberon \
--exact-only --format tsv -o resolved.tsv
python3 resolve_terms.py "left ventrical of heart" --ontology uberon --top 3
The search escalates exact (label and synonym) → token → fulltext and stops at the first
strategy that returns anything, reporting which one fired. --exact-only disables the ladder.
--branch UBERON:0000465 restricts candidates to descendants of a term.
Read match_type before using a result. exact_label and exact_synonym are safe;
partial means OLS returned its best guess for a string that does not exist as written, and
needs a human decision. unresolved is a legitimate output — see references/curation-rules.md
for the normalisations worth retrying first.
Validate existing IDs
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
Exit code is 1 if anything failed, 0 otherwise, 2 on usage or network trouble — so it works as a
CI gate on a metadata file:
python3 validate_terms.py --input metadata.tsv --strict
python3 validate_terms.py --input tissue_ids.tsv \
--branch UBERON:0000465 --expect-ontology uberon
| Status | Meaning | Verdict |
|---|
ok | Exists, current, consistent with everything asserted | pass |
matched_synonym | Claimed label is a synonym; primary label differs | warn |
imported_only | Home ontology no longer asserts this ID | warn |
not_a_class | Term is a property or individual | warn |
not_found | No such term | fail |
obsolete | Obsoleted; replacement gives the successor when one exists | fail |
label_mismatch | ID and claimed label describe different things | fail |
wrong_ontology | Right kind of ID, wrong ontology for this column | fail |
wrong_branch | Not a descendant of the required root | fail |
malformed_curie | Not of the form PREFIX:local | fail |
--strict promotes warnings to failures.
API behaviour that will mislead you
These are verified against the live service and are the reason this skill ships scripts rather
than a recipe. Full detail in references/ols4-api.md.
| Trap | Consequence |
|---|
exact=true is exact token matching | liver returns 161 hits in UBERON; adding queryFields=label returns 1 |
/search never returns is_obsolete or term_replaced_by | Named in fieldList they are dropped silently; only term detail can answer "is this ID still current" |
ontology=efo returns MONDO and CL hits | Ontologies import each other; filter on the CURIE prefix yourself |
| The same term appears once per importing ontology | Deduplicate on obo_id, keep is_defining_ontology: true |
The obo_id index has holes | MONDO:0000001 is live but unindexed by obo_id; an IRI fallback is required to avoid a false not_found |
| IRIs are not all OBO PURLs | EFO and Orphanet use their own namespaces — resolve IRIs, do not template them |
| OxO is retired | Returns HTML with HTTP 200; use term cross-references or SSSOM instead |
| A branch check does not exclude cell types from anatomy | CARO puts cell under anatomical structure; constrain the prefix too |
Choosing the ontology
MONDO for disease, HP for phenotype, UBERON for tissue, CL for cell type, EFO for assay, ChEBI for
compounds, NCBITaxon for organism, PATO for sex and for normal. Prefix-to-OLS-id mappings (HP
is served as hp, Orphanet as ordo), branch roots for --branch, and the overlapping-ontology
judgement calls are in references/ontology-registry.md.
Reporting results
Give the ID and the label, and say how each was matched. A table of bare IDs cannot be
reviewed. State unresolved terms explicitly rather than filling them with the nearest hit.
References
references/ols4-api.md — endpoints, parameters, response fields, and every verified trap.references/ontology-registry.md — prefix/ontology-id table, branch roots, which ontology owns
which concept.references/curation-rules.md — candidate-selection procedure, normalisations to retry,
auditing an existing table, obsolete terms, cross-ontology mapping.
