# Ontology Term Resolution

> Resuelve etiquetas científicas en texto libre a IDs de ontología y valida CURIEs existentes contra el EBI Ontology Lookup Service (OLS4), para anotar tejido, tipo celular, enfermedad, fenotipo o metadatos de envío como GEO o ENA.

Fuente: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/ontology-term-resolution
Markdown: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/ontology-term-resolution.md

Repositorio: https://github.com/K-Dense-AI/scientific-agent-skills
Autor: K-Dense-AI
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 202 tok instalada, 1.9k tok al activarse, 13.8k tok con todos los archivos del bundle
Bundle: 7 archivos, 54 KB
Permisos que pide: read write edit bash

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent claude-code
# Cursor
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent cursor
# Codex
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent codex
# Gemini CLI
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent gemini
# Windsurf
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent windsurf
# Cline
npx -y skills add K-Dense-AI/scientific-agent-skills --skill ontology-term-resolution --agent cline
```

## Qué hace

- Resuelve texto libre (p.ej. 'liver') a un CURIE de ontología mediante búsquedas en vivo en OLS4, escalando de exact a token a fulltext
- Valida CURIEs existentes contra OLS4 y reporta si son válidos, obsoletos, mal formados o de la ontología equivocada
- Devuelve el match_type de cada resultado (exact_label, exact_synonym, partial, unresolved) para que un humano decida en casos no exactos
- Ofrece código de salida apto para CI (0 ok, 1 fallo, 2 error de uso o red) al validar una tabla de metadatos
- Documenta comportamientos de la API OLS4 que pueden inducir a error, como que exact=true no equivale a exact_label

## Cuándo usarla

- Hay que anotar campos de tejido, tipo celular, enfermedad, fenotipo, ensayo, químico, organismo, sexo o estadio de desarrollo
- Se preparan metadatos para envío a GEO, ENA, BioSamples, CELLxGENE, HCA o ISA-Tab
- Se audita una tabla de metadatos con IDs de ontología ya existentes
- Se necesita comprobar si un término está obsoleto y qué lo reemplazó, o mapear entre ontologías

## Qué la activa

- "¿Cuál es el ID UBERON para 'ventrículo izquierdo del corazón'?"
- "Valida estos CURIEs de mi tabla de metadatos contra OLS4"
- "Comprueba si EFO:0001067 está obsoleto y qué lo reemplaza"

## Antes de instalar

- Requiere Python 3.11+ y acceso de red a https://www.ebi.ac.uk/ols4; los scripts solo usan la librería estándar, sin API key.
- Necesita en el PATH: python3
- makes network requests

## Archivos

- SKILL.md — 7 KB
- references/curation-rules.md — 5 KB
- references/ols4-api.md — 6 KB
- references/ontology-registry.md — 5 KB
- scripts/ols_client.py — 12 KB
- scripts/resolve_terms.py — 8 KB
- scripts/validate_terms.py — 10 KB

## SKILL.md

Reproducido tal cual desde K-Dense-AI/scientific-agent-skills bajo MIT. Esta sección es el documento original y está en inglés.

# 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

```bash
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
```

```bash
# 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
```

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

```bash
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:

```bash
# 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
```

| 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.

## Dónde encaja

- Categoría: [Investigación](https://skillsagentes.com/categorias/investigacion.md) — Investigación estructurada, búsqueda de fuentes y síntesis.
- Creador: [K-Dense-AI](https://skillsagentes.com/creators/k-dense-ai.md) — 163 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Citation Management](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/citation-management.md): Gestión integral de citas académicas: busca en OpenAlex, PubMed y Google Scholar, extrae metadatos precisos, valida citas y genera entradas BibTeX correctamente formateadas.
- [Scientific Slides](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/scientific-slides.md): Crea decks de diapositivas y presentaciones para charlas de investigación: PowerPoint, presentaciones de conferencia, seminarios, defensas de tesis. Da estructura, plantillas, guía de tiempos y validación visual.
- [Literature Review](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/literature-review.md): Realiza revisiones bibliográficas sistemáticas y completas usando varias bases académicas (PubMed, arXiv, bioRxiv, Semantic Scholar). Genera markdown y PDF con citas verificadas en varios estilos (APA, Nature, Vancouver).
- [Infographics](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/infographics.md): Crea infografías profesionales con Nano Banana Pro AI y refinamiento iterativo inteligente. Usa Gemini 3.6 Flash para revisar la calidad e integra investigación con Perplexity Sonar. Soporta 10 tipos, 8 estilos y paletas para daltonismo.
- [Latex Posters](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/latex-posters.md): Crea pósteres de investigación profesionales en LaTeX con beamerposter, tikzposter o baposter, para conferencias y comunicación científica: layout, colores, columnas múltiples e integración de figuras.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)