K-Dense-AI/scientific-agent-skills / skills/ontology-term-resolution
ontology-term-resolution
VerifiedResolves free-text scientific labels to ontology term IDs and validates existing CURIEs against the EBI Ontology Lookup Service (OLS4). Also looks up prefixes in Bioregistry, resolves compact identifiers via Identifiers.org, maps lab shorthand with ZOOMA, and builds Ontobee term pages. Use whenever an ontology identifier must be produced or checked - annotating tissue, cell type, disease, phenotype, assay, chemical, organism, sex, or developmental stage fields; preparing metadata for GEO, ENA, BioSamples, CELLxGENE, HCA, or ISA-Tab submission; auditing a metadata table of term IDs; checking whether a term is obsolete and what replaced it; or deciding HPO vs HP. Triggers include "ontology term", "ontology ID", "CURIE", "controlled vocabulary", "UBERON", "CL:", "MONDO", "HPO", "EFO", "ChEBI", "NCBITaxon", "GO term", "PATO", "Zooma", "Bioregistry", "Identifiers.org", "Ontobee", "annotate this tissue/cell type/disease", and any request to emit or verify an identifier shaped like PREFIX:0001234.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.3 KB |
| references/companion-apis.md | markdown | 9.4 KB |
| references/curation-rules.md | markdown | 5.9 KB |
| references/ols4-api.md | markdown | 7.5 KB |
| references/ontology-registry.md | markdown | 6.1 KB |
| scripts/id_client.py | script | 11.5 KB |
| scripts/lookup_prefix.py | script | 6.3 KB |
| scripts/map_terms.py | script | 7.3 KB |
| scripts/ols_client.py | script | 15.5 KB |
| scripts/resolve_terms.py | script | 8.3 KB |
| scripts/validate_terms.py | script | 10.7 KB |
| scripts/zooma_client.py | script | 5.2 KB |
scripts/resolve_terms.py
View on GitHub#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Resolve free-text labels to ontology terms via EBI OLS4.
Never emit an ontology ID from memory -- run this instead. Each input string is
searched with an escalating strategy and every returned candidate is labelled
with how it actually matched, so a partial hit can never be mistaken for an
exact one.
Strategies, tried in order until one returns candidates:
exact exact=true restricted to label and synonym fields
token exact=true across all indexed fields (whole-word match)
fulltext unrestricted relevance search
Examples:
# single term, constrained to the ontology that should define it
uv run resolve_terms.py "liver" --ontology uberon
# a column of tissue names, requiring anatomical entities only
uv run resolve_terms.py --input tissues.txt \\
--ontology uberon --branch UBERON:0000465 --format tsv -o resolved.tsv
# accept exact matches only; unresolved rows are reported, not guessed
uv run resolve_terms.py "kidney cortex" "left ventrical" --exact-only
"""
from __future__ import annotations
import argparse
import csv
import json
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
from ols_client import ( # noqa: E402
OlsError,
iri_for,
is_curie,
rank_candidates,
search,
)
STRATEGIES = (
("exact", {"exact": True, "query_fields": "label,synonym"}),
("token", {"exact": True, "query_fields": None}),
("fulltext", {"exact": False, "query_fields": None}),
)
TSV_COLUMNS = (
"query",
"rank",
"curie",
"iri",
"label",
"ontology",
"match_type",
"strategy",
"defining_ontology",
)
def read_inputs(args: argparse.Namespace) -> list[str]:
"""Collect query strings from positional args, a file, or stdin."""
values: list[str] = list(args.text)
if args.input:
raw = (
sys.stdin.read()
if args.input == "-"
else Path(args.input).read_text(encoding="utf-8")
)
for line in raw.splitlines():
line = line.strip()
if line and not line.startswith("#"):
values.append(line)
if not values and not sys.stdin.isatty():
for line in sys.stdin.read().splitlines():
line = line.strip()
if line and not line.startswith("#"):
values.append(line)
# Preserve order, drop duplicates.
seen: set[str] = set()
unique = []
for value in values:
if value not in seen:
seen.add(value)
unique.append(value)
return unique
def resolve_one(
text: str,
*,
ontology: str | None,
subtree_iri: str | None,
rows: int,
exact_only: bool,
) -> dict:
"""Run the strategy ladder for one string and return ranked candidates."""
strategies = STRATEGIES[:1] if exact_only else STRATEGIES
for name, options in strategies:
docs = search(
text,
ontology=ontology,
subtree_iri=subtree_iri,
rows=rows,
**options,
)
ranked = rank_candidates(text, docs)
if exact_only:
ranked = [candidate for candidate in ranked
if candidate["match_type"] in {"exact_label", "exact_synonym"}]
if ranked:
return {"query": text, "strategy": name, "candidates": ranked[:rows]}
return {"query": text, "strategy": strategies[-1][0], "candidates": []}
def to_rows(results: list[dict]) -> list[dict]:
"""Flatten results into one row per candidate, or one row if unresolved."""
rows: list[dict] = []
for result in results:
if not result["candidates"]:
rows.append(
{
"query": result["query"],
"rank": 1,
"curie": "",
"iri": "",
"label": "",
"ontology": "",
"match_type": "unresolved",
"strategy": result["strategy"],
"defining_ontology": "",
}
)
continue
for position, candidate in enumerate(result["candidates"], start=1):
rows.append(
{
"query": result["query"],
"rank": position,
"curie": candidate.get("obo_id", ""),
"iri": candidate.get("iri", ""),
"label": candidate.get("label", ""),
"ontology": candidate.get("ontology_name", ""),
"match_type": candidate["match_type"],
"strategy": result["strategy"],
"defining_ontology": str(
bool(candidate.get("is_defining_ontology"))
).lower(),
}
)
return rows
def write_output(results: list[dict], fmt: str, output: str | None) -> None:
"""Emit TSV or JSON to a path or stdout."""
stream = open(output, "w", encoding="utf-8", newline="") if output else sys.stdout
try:
if fmt == "json":
json.dump(results, stream, indent=2)
stream.write("\n")
else:
writer = csv.DictWriter(
stream, fieldnames=TSV_COLUMNS, delimiter="\t", lineterminator="\n"
)
writer.writeheader()
writer.writerows(to_rows(results))
finally:
if output:
stream.close()
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="Resolve free-text labels to ontology terms via EBI OLS4.",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("text", nargs="*", help="strings to resolve")
parser.add_argument(
"--input",
help="file with one string per line ('-' for stdin); # lines are comments",
)
parser.add_argument(
"--ontology",
help="restrict to OLS ontology ids, comma separated (e.g. uberon,cl)",
)
parser.add_argument(
"--branch",
help="require candidates to be descendants of this CURIE (e.g. UBERON:0000465)",
)
parser.add_argument(
"--top", type=int, default=5, help="candidates to report per query (default 5)"
)
parser.add_argument(
"--exact-only",
action="store_true",
help="only exact label/synonym matches; report anything else as unresolved",
)
parser.add_argument(
"--format", choices=("tsv", "json"), default="tsv", help="output format"
)
parser.add_argument("-o", "--output", help="write here instead of stdout")
return parser
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.top < 1:
print("--top must be positive.", file=sys.stderr)
return 2
queries = read_inputs(args)
if not queries:
print("No input strings given. See --help.", file=sys.stderr)
return 2
subtree_iri = None
if args.branch:
if not is_curie(args.branch):
print(f"--branch expects a CURIE, got {args.branch!r}", file=sys.stderr)
return 2
try:
subtree_iri = iri_for(args.branch)
except OlsError as exc:
print(f"Could not resolve --branch {args.branch}: {exc}", file=sys.stderr)
return 2
if not subtree_iri:
print(f"--branch term not found in OLS: {args.branch}", file=sys.stderr)
return 2
results = []
for query in queries:
try:
results.append(
resolve_one(
query,
ontology=args.ontology,
subtree_iri=subtree_iri,
rows=args.top,
exact_only=args.exact_only,
)
)
except OlsError as exc:
print(f"OLS lookup failed for {query!r}: {exc}", file=sys.stderr)
return 2
write_output(results, args.format, args.output)
unresolved = [r["query"] for r in results if not r["candidates"]]
if unresolved:
print(
f"{len(unresolved)}/{len(results)} unresolved: "
+ ", ".join(repr(q) for q in unresolved[:10]),
file=sys.stderr,
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |