Resolve concept spans that OpenMed extracts to UMLS Metathesaurus concepts.
The atom is the CUI (Concept Unique Identifier, e.g. C0011860): one CUI
unifies synonyms from many source vocabularies (SNOMED CT, ICD-10-CM, RxNorm,
MeSH, LOINC), making the CUI the natural hub for cross-vocabulary normalization.
Every concept also carries one or more semantic types (TUIs, e.g. *Disease or
Syndrome* T047) for type-based filtering.
Hard licensing boundary — read first. The UMLS Metathesaurus is
license-restricted. OpenMed and this skill never bundle, ship, or cache
Metathesaurus content. Concept linking runs **out-of-process against the NLM
UTS (UMLS Terminology Services) REST API using the user's own UTS API key**.
A free UTS account + API key is required (request at uts.nlm.nih.gov and accept
the UMLS license). The Metathesaurus stays user-supplied: your code holds only
the key (from the environment) and stores only returned CUIs/strings.
disorder, an ICD-10 code, and a free-text mention onto a single CUI.
attack" → C0027051).
Substance or Disease or Syndrome* entities.
RxNorm (normalizing-rxnorm) or SNOMED (mapping-to-snomed).
The UTS REST API base is https://uts-ws.nlm.nih.gov/rest. Authentication uses
your API key as the apiKey query parameter (the modern, simplest method).
import os, requests
UTS = "https://uts-ws.nlm.nih.gov/rest"
API_KEY = os.environ["UTS_API_KEY"] # USER's own key — never hardcoded
VERSION = "current" # or a fixed release like 2024AB
def search(term: str, sabs: str | None = None, count: int = 10) -> list[dict]:
"""Search the Metathesaurus for a term; optionally restrict source vocabs."""
params = {"string": term, "apiKey": API_KEY, "pageSize": count}
if sabs: # e.g. "SNOMEDCT_US,RXNORM,ICD10CM"
params["sabs"] = sabs
r = requests.get(f"{UTS}/search/{VERSION}", params=params, timeout=15)
r.raise_for_status()
return r.json().get("result", {}).get("results", [])
def concept(cui: str) -> dict:
"""Pull a concept's preferred name and semantic types."""
r = requests.get(f"{UTS}/content/{VERSION}/CUI/{cui}",
params={"apiKey": API_KEY}, timeout=15)
r.raise_for_status()
return r.json().get("result", {})
def crosswalk(cui: str, target_sab: str) -> list[dict]:
"""Atoms of a CUI in a target vocabulary (the cross-walk)."""
r = requests.get(f"{UTS}/content/{VERSION}/CUI/{cui}/atoms",
params={"apiKey": API_KEY, "sabs": target_sab,
"pageSize": 50}, timeout=20)
r.raise_for_status()
return r.json().get("result", [])
hits = search("type 2 diabetes") # -> [{ui: 'C0011860', name: ...}, ...]
sct = crosswalk("C0011860", "SNOMEDCT_US") # CUI -> SNOMED CT codes
/search/{version} for candidate CUIs.concept, not a same-named disease. Pull semantic types from/content/.../CUI/{cui} and keep only the expected group.
with OpenMed's confidence to choose one CUI.
SNOMEDCT_US, ICD10CM, RXNORM, MSH — via /CUI/{cui}/atoms?sabs=.
openmed.analyze_text(..., output_format="dict") returns entities, each a dict
with text, label, confidence, start, end. Use the label to pick the
semantic-type group you keep:
import openmed
note = "History of myocardial infarction; started on lisinopril."
result = openmed.analyze_text(
note,
model_name="disease_detection_superclinical", # Disease category
output_format="dict",
)
# OpenMed label -> acceptable UMLS semantic-type groups (TUI prefixes)
KEEP_STY = {
"DISEASE": {"Disease or Syndrome", "Sign or Symptom", "Neoplastic Process"},
"DRUG": {"Pharmacologic Substance", "Clinical Drug"},
"CHEM": {"Pharmacologic Substance", "Organic Chemical"},
}
for ent in result["entities"]:
for hit in search(ent["text"], count=5):
cui = hit["ui"]
stys = {s["name"] for s in concept(cui).get("semanticTypes", [])}
if not KEEP_STY.get(ent["label"]) or stys & KEEP_STY[ent["label"]]:
print(ent["text"], ent["start"], ent["end"], "->", cui, hit["name"])
break
Keep OpenMed's start/end offsets beside each CUI for traceability. Store only
CUIs and codes — never the raw note, never a local copy of the Metathesaurus.
concept dump baked into the package. If you precompute, do it inside the
user's licensed environment, not in distributed OpenMed assets.
embed it, log it, or commit it. One key, the user's license, their rate limits.
types ("cold" = symptom vs temperature). Without TUI filtering you will link to
the wrong concept family.
current drifts at each UMLS release. Pina release (e.g. 2024AB) for stable, auditable mappings; record it.
sabs to the vocabularies you arelicensed for and actually need; this both narrows results and respects per-source
license terms inside UMLS.
(SNOMED/ICD/RxNorm), so resolve to CUI then cross-walk — don't store only the
CUI if your consumers expect billable/clinical codes.
QuickUMLS run locally but require a UMLS download under the user's license;
OpenMed neither ships nor requires those datasets.
reach UTS. No PHI over the wire.