Linking OpenMed entities to UMLS CUIs

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.

When to use

• You need one canonical id across vocabularies — e.g. to unify a SNOMED CT disorder, an ICD-10 code, and a free-text mention onto a single CUI.
• You want synonym normalization ("MI", "myocardial infarction", "heart attack" → C0027051).
• You need semantic-type filtering to keep only, say, Pharmacologic Substance or Disease or Syndrome entities.
• You are cross-walking codes and need the CUI as the join key before pivoting to RxNorm (normalizing-rxnorm) or SNOMED (mapping-to-snomed).

Quick start (user-supplied UTS API key)

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

Workflow

1. Extract spans with OpenMed (Disease, Pharmaceutical, Chemical, Anatomy).
2. Search each span via /search/{version} for candidate CUIs.
3. Filter by semantic type (TUI) so a drug span resolves to a substance concept, not a same-named disease. Pull semantic types from /content/.../CUI/{cui} and keep only the expected group.
4. Rank candidates (exact preferred-name match > synonym match) and combine with OpenMed's confidence to choose one CUI.
5. Cross-walk the chosen CUI to whatever target you actually store — SNOMEDCT_US, ICD10CM, RXNORM, MSH — via /CUI/{cui}/atoms?sabs=.
6. Emit the CUI plus the target code(s) and OpenMed source offsets.

Hand-off from OpenMed

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.

Edge cases & gotchas

• Never bundle or cache the Metathesaurus. No vendored MRCONSO, no local concept dump baked into the package. If you precompute, do it inside the user's licensed environment, not in distributed OpenMed assets.
• The UTS key is the user's. Read it from the environment/secret store; never embed it, log it, or commit it. One key, the user's license, their rate limits.
• Semantic-type filtering is essential. Many strings are polysemous across types ("cold" = symptom vs temperature). Without TUI filtering you will link to the wrong concept family.
• Version pin for reproducibility. current drifts at each UMLS release. Pin a release (e.g. 2024AB) for stable, auditable mappings; record it.
• Source-vocab restriction. Restrict sabs to the vocabularies you are licensed for and actually need; this both narrows results and respects per-source license terms inside UMLS.
• CUI as hub, not endpoint. Downstream systems usually want a target code (SNOMED/ICD/RxNorm), so resolve to CUI then cross-walk — don't store only the CUI if your consumers expect billable/clinical codes.
• Offline alternatives are still user-licensed. Tools like MetaMap or QuickUMLS run locally but require a UMLS download under the user's license; OpenMed neither ships nor requires those datasets.
• Local-first. OpenMed NER runs on-device; only de-identified concept strings reach UTS. No PHI over the wire.

Standards & references

• UMLS Metathesaurus: https://www.nlm.nih.gov/research/umls/index.html
• UMLS license & UTS account: https://uts.nlm.nih.gov/uts/
• UTS REST API docs: https://documentation.uts.nlm.nih.gov/rest/home.html
• Semantic Network (types/TUIs): https://www.nlm.nih.gov/research/umls/META3_current_semantic_types.html
• MetaMap: https://lhncbc.nlm.nih.gov/ii/tools/MetaMap.html
• QuickUMLS: https://github.com/Georgetown-IR-Lab/QuickUMLS