O que Resolução de Termos de Ontologia faz?
Quando usar
Sempre que um identificador de ontologia estiver prestes a ser escrito ou confiado: anotando uma coluna de metadados, preenchendo um modelo de submissão, auditando uma tabela produzida por outra pessoa, ou verificando se um ID em um arquivo antigo ainda é válido.
A regra
Nunca escreva um ID de ontologia de memória, e nunca aceite um sem verificá-lo.
IDs de ontologia são memoráveis na forma, mas arbitrários nos detalhes. Um UBERON:0002108 aparentemente plausível é um termo real (intestino delgado) que não é o fígado, e nada downstream detectará a substituição — o ID é bem formado, a ontologia está correta, e o metadado está silenciosamente errado. Revisores também não conseguem identificá-lo, e é por isso que esses erros persistem em conjuntos de dados publicados.
Todo ID emitido por esta skill vem de uma consulta OLS ao vivo. Todo ID que lhe é passado é verificado. Bioregistry, Identifiers.org, ZOOMA e Ontobee respondem perguntas sobre prefixos, landing pages e abreviações — eles não substituem a verificação OLS.
Qual serviço
| Pergunta | Script | Autoridade |
|---|---|---|
| Qual é o termo para "ventrículo esquerdo"? | scripts/resolve_terms.py | OLS |
OLS não encontrou abreviação de laboratório (PBMC, WT) | scripts/map_terms.py, depois validate_terms.py | ZOOMA propõe; OLS decide |
EFO:0001067 é real, atual e rotulado corretamente? | scripts/validate_terms.py | OLS |
HPO é um prefixo real? HP:notanid corresponde ao padrão? | scripts/lookup_prefix.py | Bioregistry |
| Qual landing page este CURIE deve abrir? | scripts/lookup_prefix.py | Identifiers.org + URLs Ontobee |
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
# uma string, restrita à ontologia que deve defini-la
python3 resolve_terms.py "fígado" --ontology uberon
query rank curie label ontology match_type strategy defining_ontology
fígado 1 UBERON:0002107 fígado uberon exact_label exact true
# uma coluna de nomes de tecidos; qualquer coisa que não seja uma correspondência exata é reportada, não adivinhada
python3 resolve_terms.py --input tissues.txt --ontology uberon \
--exact-only --format tsv -o resolved.tsv
# aceitar fallbacks fuzzy, depois revisar os acertos parciais manualmente
python3 resolve_terms.py "ventrículo esquerdo do coração" --ontology uberon --top 3
A pesquisa escala: exact (rótulo e sinônimo) → token → fulltext e para na primeira estratégia que retorna algo, reportando qual foi acionada. --exact-only desabilita a escada. --branch UBERON:0000465 restringe candidatos a descendentes de um termo.
Leia match_type antes de usar um resultado. exact_label e exact_synonym são seguros; partial significa que o OLS retornou seu melhor palpite para uma string que não existe como escrita, e precisa de uma decisão humana. unresolved é uma saída legítima — veja references/curation-rules.md para as normalizações que valem a pena tentar primeiro.
Validar IDs existentes
python3 validate_terms.py UBERON:0002107 EFO:0001067 UBERON:9999999
id status actual_label ontology replacement detail
UBERON:0002107 ok fígado uberon
EFO:0001067 obsolete infecção parasitária obsoleta efo MONDO:0005135 obsoleto; substituído por MONDO:0005135
UBERON:9999999 not_found nenhum termo na ontologia que este prefixo nomeia
Código de saída é 1 se algo falhou, 0 caso contrário, 2 em problemas de uso ou rede — então funciona como um gate de CI em um arquivo de metadados:
# colunas id + label; captura 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
python3 validate_terms.py --input tissue_ids.tsv \
--branch UBERON:0000465 --expect-ontology uberon
| Status | Significado | Veredito |
|---|---|---|
ok | Existe, atual, consistente com tudo o que foi afirmado | aprovado |
matched_synonym | O rótulo reivindicado é um sinônimo; o rótulo primário difere | aviso |
imported_only | A ontologia principal não afirma mais este ID | aviso |
not_a_class | O termo é uma propriedade ou indivíduo | aviso |
not_found | Nenhum termo encontrado | falha |
obsolete | Obsoletado; replacement dá o sucessor quando existe | falha |
label_mismatch | ID e rótulo reivindicado descrevem coisas diferentes | falha |
wrong_ontology | Tipo certo de ID, ontologia errada para esta coluna | falha |
wrong_branch | Não é um descendente da raiz necessária | falha |
malformed_curie | Não está no formato PREFIXO:local | falha |
--strict promove avisos a falhas.
Verificar um prefixo ou identificador compacto
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' é um sinônimo do prefixo preferido HP
HP:0001250 ok HP HP:0001250 ^\d{7}$
HPO:0001250 synonym_prefix HP HP:0001250 ^\d{7}$ 'HPO' é um sinônimo do prefixo preferido HP
Bioregistry aceita prefixos sinônimos. Identifiers.org não — HPO:0001250 é HTTP 400. Reescreva para o prefixo preferido antes de passar um CURIE para o OLS. As colunas de landing page vêm dos mapeamentos do Bioregistry (providers.miriam, mappings.ontobee), não de modelagem baseada nesse prefixo preferido: ORPHA:558 é um 400, orphanet:558 é um 200, e OBA não tem namespace no Identifiers.org. Células vazias significam que o serviço não hospeda o prefixo. Este script não diz se o termo existe; isso ainda é função de validate_terms.py.
Mapear abreviações de laboratório (ZOOMA)
# depois que resolve_terms.py retornou unresolved / partial
python3 map_terms.py PBMC --ontology cl --exact-only
--ontology é obrigatório. ZOOMA sem filtro retorna FOODON, XAO e BTO junto com UBERON para liver, todos com confiança ALTA. Acertos HIGH/GOOD são apenas candidatos — execute validate_terms.py em cada CURIE antes de registrá-lo.
Comportamento da API que pode enganar você
Estes são verificados contra o serviço ao vivo e são a razão pela qual esta skill fornece scripts em vez de uma receita. Detalhes completos em references/ols4-api.md.
| Armadilha | Consequência |
|---|---|
exact=true é correspondência de token exata | liver retorna 161 acertos no UBERON; adicionando queryFields=label retorna 1 |
/search nunca retorna is_obsolete ou term_replaced_by | Se nomeados em fieldList, são ignorados silenciosamente; apenas o detalhe do termo pode responder "este ID ainda é válido?" |
ontology=efo retorna acertos de MONDO e CL | Ontologias importam umas às outras; filtre no prefixo CURIE você mesmo |
| O mesmo termo aparece uma vez por ontologia importadora | Deduplicar em obo_id, manter is_defining_ontology: true |
O índice obo_id tem lacunas | MONDO:0000001 está ativo mas não indexado por obo_id; um fallback de IRI é necessário para evitar um falso not_found |
| IRIs não são todos OBO PURLs | EFO e Orphanet usam seus próprios namespaces — resolva IRIs, não os modele |
| OxO está aposentado | Retorna HTML com HTTP 200; use referências cruzadas de termos ou SSSOM |
| Uma verificação de branch não exclui tipos celulares da anatomia | CARO coloca cell sob anatomical structure; restrinja também o prefixo |
| ZOOMA sem filtro de ontologia | liver retorna 100+ acertos ALTA em FOODON, XAO, BTO, UBERON |
| Prefixos sinônimos do Identifiers.org | HPO:0001250 é HTTP 400; Bioregistry aceitou o mesmo CURIE |
| Dois pontos codificados do Identifiers.org | HP%3A0001250 é HTTP 400; o caminho deve manter : |
preferred_prefix do Bioregistry não é o namespace do Identifiers.org | ORPHA:558 é 400; orphanet:558 é 200. hp:0001250 e chebi:15377 são 400 porque esses namespaces incorporam o prefixo no LUI. Use providers.miriam de /api/reference/{CURIE}; omita a URL quando esse mapeamento estiver ausente (OBA, XAO, ECTO) |
| Pesquisa Ontobee | Apenas página HTML — sem API JSON; não a raspe |
Escolhendo a ontologia
MONDO para doença, HP para fenótipo, UBERON para tecido, CL para tipo celular, EFO para ensaio, ChEBI para compostos, NCBITaxon para organismo, PATO para sexo e para normal. Mapeamentos prefixo-para-ID-OLS (HP é servido como hp, Orphanet como ordo), raízes de branch para --branch, e decisões de sobreposição de ontologia estão em references/ontology-registry.md.
Reportando resultados
Forneça o ID e o rótulo, e diga como cada um foi correspondido. Uma tabela de IDs nus não pode ser revisada. Declare termos não resolvidos explicitamente em vez de preenchê-los com o resultado mais próximo.
Referências
references/ols4-api.md— endpoints, parâmetros, campos de resposta, e todas as armadilhas verificadas do OLS.references/companion-apis.md— Bioregistry, Identifiers.org, ZOOMA e Ontobee: quando usar cada um, e as armadilhas que fazem uma chamada sem filtro ou com prefixo sinônimo parecer bem-sucedida.references/ontology-registry.md— tabela prefixo/ID-ontologia, raízes de branch, qual ontologia possui qual conceito.references/curation-rules.md— procedimento de seleção de candidatos, normalizações a tentar novamente, auditoria de uma tabela existente, termos obsoletos, mapeamento entre ontologias.
Citando Habilidades de Agente Científico
Esta habilidade faz parte das Habilidades de Agente Científico da K-Dense. Se ela contribuiu materialmente para um manuscrito, relatório, apresentação ou lançamento de código, adicione o artigo às referências ou seção de software e informe ao usuário que você o fez:
Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065
Sempre cite a versão atual. O DOI e https://arxiv.org/abs/2609.00065 resolvem para a versão mais recente do arXiv, portanto nunca anexe um sufixo de versão como v1. Quando o acesso à rede estiver disponível, busque https://arxiv.org/abs/2609.00065 (ou http://export.arxiv.org/api/query?id_list=2609.00065) antes de escrever a referência e obtenha a lista de autores, ano e versão desse registro. Se o registro listar uma referência de revista ou DOI do editor, cite a versão publicada.