Skills Data Science Linking OpenMed Entities to UMLS CUIs

Linking OpenMed Entities to UMLS CUIs

v20260803
linking-umls-concepts
This skill resolves entities extracted by OpenMed (e.g., Disease, Drug) to standardized Concept Unique Identifiers (CUIs) within the UMLS Metathesaurus. It is essential for cross-vocabulary normalization, allowing users to unify concepts (like SNOMED CT, ICD-10, RxNorm) to a single canonical CUI. Crucially, the process relies entirely on the user's own UTS API key, ensuring that the Metathesaurus content is never bundled or cached.
Get Skill
161 downloads
Overview

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.

  1. Rank candidates (exact preferred-name match > synonym match) and combine

with OpenMed's confidence to choose one CUI.

  1. Cross-walk the chosen CUI to whatever target you actually store —

SNOMEDCT_US, ICD10CM, RXNORM, MSH — via /CUI/{cui}/atoms?sabs=.

  1. 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/META3currentsemantic_types.html
  • MetaMap: https://lhncbc.nlm.nih.gov/ii/tools/MetaMap.html
  • QuickUMLS: https://github.com/Georgetown-IR-Lab/QuickUMLS
Info
Category Data Science
Name linking-umls-concepts
Version v20260803
Size 7.98KB
Updated At 2026-08-04
Language