Resolução de Termos de Ontologia

Quando usar

Sempre que um identificador de ontologia estiver prestes a ser anotado ou confiado: ao anotar uma coluna de metadados, preencher um modelo de submissão, auditar uma tabela produzida por outra pessoa ou verificar se um ID em um arquivo antigo ainda está atualizado.

A regra

Nunca anote um ID de ontologia de memória e nunca aceite um sem verificá-lo.

IDs de ontologia são memoráveis em forma e arbitrários em detalhes. Um UBERON:0002108 com aparência plausível é um termo real (intestino delgado) que não é o fígado, e nada a jusante detectará a substituição — o ID está bem formado, a ontologia está correta e os metadados estão silenciosamente errados. Revisores também não conseguem detectá-lo, e é por isso que esses erros persistem em conjuntos de dados publicados.

A busca OLS e o ZOOMA emitem candidatos. Valide cada ID selecionado com os detalhes do termo OLS, em seguida, verifique sua definição em relação à amostra e ao esquema de destino antes de aceitá-lo. Bioregistry, Identifiers.org, ZOOMA e Ontobee respondem a perguntas de prefixo, página de destino e abreviação — eles não substituem essa verificação OLS.

Qual serviço

Todos os quatro scripts aceitam valores únicos ou arquivos, emitem TSV ou JSON e não precisam de pacotes além da biblioteca padrão. Armadilhas completas para os serviços não-OLS estão em references/companion-apis.md.

Resolver texto para termos

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           iri                                               label  ontology  match_type   strategy  defining_ontology
liver   1     UBERON:0002107  http://purl.obolibrary.org/obo/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

A busca escala exact (rótulo e sinônimo) → token → fulltext e para na primeira estratégia que retorna candidatos, relatando qual disparou. --exact-only desabilita a escada e rejeita localmente correspondências parciais, relacionadas, amplas, estreitas e de sinônimos sem escopo. As buscas são listas de candidatos limitadas (--top), não verificações exaustivas de ambiguidade. --branch UBERON:0000465 usa a ancestralidade hierárquica OLS, incluindo "parte-de/desenvolve-de".

Leia match_type antes de usar um resultado. exact_label e exact_synonym estabelecem acordo lexical (o último também requer uma anotação de sinônimo exato), não contexto de amostra correto. related_synonym, broad_synonym, narrow_synonym, unspecified_synonym e partial exigem curadoria. Valide cada ID selecionado; a busca não expõe obsolescência em seus registros. unresolved é uma saída legítima. Veja references/curation-rules.md antes de normalizar a entrada.

Validar IDs existentes

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

O código de saída é 1 se algo falhou, 0 caso contrário, 2 em caso de problemas de uso ou rede — assim funciona como um portão de CI em um arquivo de metadados:

# colunas de ID + rótulo; detecta IDs que existem, mas estão rotulados como outra coisa
python3 validate_terms.py --input metadata.tsv --strict

# uma coluna de tecido deve conter entidades anatômicas UBERON e nada mais

…