linking-umls-concepts

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