Linking Umls Concepts
Links entities extracted by OpenMed to UMLS Metathesaurus CUIs using the USER'S OWN UTS...
Install
npx skills add maziyarpanahi/openmed --skill linking-umls-concepts -g -a claude-code -y- Repository
- maziyarpanahi/openmed5.8k
- Category
- Engineering
- Updated
- 4d ago
- License
- Apache-2.0
- Context cost
- Mediumabout 1,804 tokens
- Runs scripts
- No, instructions only
What it does
Links entities extracted by OpenMed to UMLS Metathesaurus CUIs using the USER'S OWN UTS API key, with nothing from the Metathesaurus bundled or cached. Use when the user wants to normalize concepts across vocabularies to a single CUI, resolve synonyms via the UMLS, filter by semantic type, or cross-walk between SNOMED CT, ICD-10, RxNorm and MeSH through their shared CUI. Trigger keywords: UMLS, CUI, Metathesaurus, UTS API key, semantic type, TUI, MetaMap, QuickUMLS, concept normalization, cross-vocabulary. Pairs after OpenMed NER: consume Disease/Pharmaceutical/Chemical/Anatomy entities from openmed.analyze_text and resolve each span to a CUI out-of-process. UMLS is license-restricted, the Metathesaurus is NEVER bundled; every call uses the user's UTS account.
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
