Medical Ontology & Code Mapping

Overview

Healthcare data is only as interoperable as its vocabularies. The same condition may be a free-text string in one feed, an ICD-9 code in another, and a SNOMED CT concept in a third. This skill builds the terminology normalization layer mapping messy inputs to canonical concepts and crosswalking between code systems so that records become joinable, groupable, and analyzable. It is the "healthcare-specific business ontology" backbone for data-quality and analytics work.

When to Use This Skill

• Standardizing dirty diagnosis, procedure, or drug free-text into coded concepts.
• Crosswalking between vocabularies: NDC↔RxNorm, ICD-9↔ICD-10, SNOMED↔ICD-10,

local codes → standard codes.

• Validating that codes exist, are billable/active, and are used in the right context.
• Grouping codes into clinical categories (CCSR, ATC drug classes, value sets).
• Navigating an ontology graph parents, children, synonyms, relationships.

Code Systems Covered

Workflow

1. Detect the field type (dx vs. procedure vs. drug vs. lab) and current state

(free-text vs. coded, which system).

1. Normalize text lowercase, expand abbreviations, strip dose/route noise; for drugs

parse ingredient/strength/form.

1. Map to canonical concepts: exact/synonym lookup first, then fuzzy/lexical match

(e.g., RxNorm approximateTerm, UMLS MetaMap-style), keeping a confidence score.

1. Crosswalk via UMLS CUI or official maps (GEMs for ICD-9↔10, RxNorm relations for

NDC↔ingredient, SNOMED→ICD-10 map).

1. Validate code exists, is active for the service date, billable, and context-

appropriate; flag retired or non-billable codes.

1. Group into analytic categories (CCSR, ATC, custom value sets) for rollups.

Example

# RxNorm + ICD via public APIs (no key required for RxNav / Clinical Tables)
import requests

def ndc_to_rxnorm(ndc):
    r = requests.get(f"https://rxnav.nlm.nih.gov/REST/ndcstatus.json?ndc={ndc}").json()
    return r.get("ndcStatus", {}).get("rxcui")

def normalize_drug(text):
    r = requests.get("https://rxnav.nlm.nih.gov/REST/approximateTerm.json",
                     params={"term": text, "maxEntries": 1}).json()
    cand = r["approximateGroup"]["candidate"][0]
    return cand["rxcui"], cand["score"]

def search_icd10(query):  # NLM Clinical Tables typeahead
    r = requests.get("https://clinicaltables.nlm.nih.gov/api/icd10cm/v3/search",
                     params={"sf": "code,name", "terms": query}).json()
    return r[3]      # [[code, name], ...]

rxcui, conf = normalize_drug("lipitor 20 mg tab")   # -> ('617312', 95)
codes = search_icd10("type 2 diabetes")             # -> [['E11.9','Type 2 diabetes...'], ...]

Outputs

• mapped_codes.parquet input value → canonical code, system, display, confidence.
• crosswalk.parquet source code/system → target code/system with map provenance.
• unmapped_review.csv low-confidence or unresolved inputs for clerical review.
• mapping_report.md coverage %, confidence distribution, top unmapped terms.

Healthcare Context

This is the vocabulary layer that makes claims/EHR data trustworthy and joinable. It feeds healthcare-data-quality-profiling (validity rules), patient-record-entity- resolution (standardized coded fields), and downstream modeling. Map confidence should be retained end-to-end so low-confidence mappings can be audited.

References

• UMLS Metathesaurus & RxNav APIs https://rxnav.nlm.nih.gov / https://uts.nlm.nih.gov
• NLM Clinical Tables API https://clinicaltables.nlm.nih.gov
• CMS GEMs (ICD-9↔ICD-10); AHRQ CCSR; OHDSI OMOP vocabularies https://athena.ohdsi.org