Home / pyhealth / references/medical_coding.md

references/medical_coding.md

PyHealth Medical Code Translation

Overview

Healthcare data uses multiple coding systems and standards. PyHealth's MedCode module enables translation and mapping between medical coding systems through ontology lookups and cross-system mappings.

Core Classes

InnerMap

Handles within-system ontology lookups and hierarchical navigation.

Key Capabilities: - Code lookup with attributes (names, descriptions) - Ancestor/descendant hierarchy traversal - Code standardization and conversion - Parent-child relationship navigation

CrossMap

Manages cross-system mappings between different coding standards.

Key Capabilities: - Translation between coding systems - Many-to-many relationship handling - Hierarchical level specification (for medications) - Bidirectional mapping support

Supported Coding Systems

Diagnosis Codes

ICD-9-CM (International Classification of Diseases, 9th Revision, Clinical Modification) - Legacy diagnosis coding system - Hierarchical structure with 3-5 digit codes - Used in US healthcare pre-2015 - Usage: from pyhealth.medcode import InnerMap - icd9_map = InnerMap.load("ICD9CM")

ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification) - Current diagnosis coding standard - Alphanumeric codes (3-7 characters) - More granular than ICD-9 - Usage: from pyhealth.medcode import InnerMap - icd10_map = InnerMap.load("ICD10CM")

CCSCM (Clinical Classifications Software for ICD-CM) - Groups ICD codes into clinically meaningful categories - Reduces dimensionality for analysis - Single-level and multi-level hierarchies - Usage: from pyhealth.medcode import CrossMap - icd_to_ccs = CrossMap.load("ICD9CM", "CCSCM")

Procedure Codes

ICD-9-PROC (ICD-9 Procedure Codes) - Inpatient procedure classification - 3-4 digit numeric codes - Legacy system (pre-2015) - Usage: from pyhealth.medcode import InnerMap - icd9proc_map = InnerMap.load("ICD9PROC")

ICD-10-PROC (ICD-10 Procedure Coding System) - Current procedural coding standard - 7-character alphanumeric codes - More detailed than ICD-9-PROC - Usage: from pyhealth.medcode import InnerMap - icd10proc_map = InnerMap.load("ICD10PROC")

CCSPROC (Clinical Classifications Software for Procedures) - Groups procedure codes into categories - Simplifies procedure analysis - Usage: from pyhealth.medcode import CrossMap - proc_to_ccs = CrossMap.load("ICD9PROC", "CCSPROC")

Medication Codes

NDC (National Drug Code) - US FDA drug identification system - 10 or 11-digit codes - Product-level specificity (manufacturer, strength, package) - Usage: from pyhealth.medcode import InnerMap - ndc_map = InnerMap.load("NDC")

RxNorm - Standardized drug terminology - Normalized drug names and relationships - Links multiple drug vocabularies - Usage: from pyhealth.medcode import CrossMap - ndc_to_rxnorm = CrossMap.load("NDC", "RXNORM")

ATC (Anatomical Therapeutic Chemical Classification) - WHO drug classification system - 5-level hierarchy: - Level 1: Anatomical main group (1 letter) - Level 2: Therapeutic subgroup (2 digits) - Level 3: Pharmacological subgroup (1 letter) - Level 4: Chemical subgroup (1 letter) - Level 5: Chemical substance (2 digits) - Example: "C03CA01" = Furosemide - C = Cardiovascular system - C03 = Diuretics - C03C = High-ceiling diuretics - C03CA = Sulfonamides - C03CA01 = Furosemide

Usage:

from pyhealth.medcode import CrossMap
ndc_to_atc = CrossMap.load("NDC", "ATC")
atc_codes = ndc_to_atc.map("00074-3799-13", level=3)  # Get ATC level 3

Common Operations

InnerMap Operations

1. Code Lookup

from pyhealth.medcode import InnerMap

icd9_map = InnerMap.load("ICD9CM")
info = icd9_map.lookup("428.0")  # Heart failure
# Returns: name, description, additional attributes

2. Ancestor Traversal

# Get all parent codes in hierarchy
ancestors = icd9_map.get_ancestors("428.0")
# Returns: ["428", "420-429", "390-459"]

3. Descendant Traversal

# Get all child codes
descendants = icd9_map.get_descendants("428")
# Returns: ["428.0", "428.1", "428.2", ...]

4. Code Standardization

# Normalize code format
standard_code = icd9_map.standardize("4280")  # Returns "428.0"

CrossMap Operations

1. Direct Translation

from pyhealth.medcode import CrossMap

# ICD-9-CM to CCS
icd_to_ccs = CrossMap.load("ICD9CM", "CCSCM")
ccs_codes = icd_to_ccs.map("82101")  # Coronary atherosclerosis
# Returns: ["101"]  # CCS category for coronary atherosclerosis

2. Hierarchical Drug Mapping

# NDC to ATC at different levels
ndc_to_atc = CrossMap.load("NDC", "ATC")

# Get specific ATC level
atc_level_1 = ndc_to_atc.map("00074-3799-13", level=1)  # Anatomical group
atc_level_3 = ndc_to_atc.map("00074-3799-13", level=3)  # Pharmacological
atc_level_5 = ndc_to_atc.map("00074-3799-13", level=5)  # Chemical substance

3. Bidirectional Mapping

# Map in either direction
rxnorm_to_ndc = CrossMap.load("RXNORM", "NDC")
ndc_codes = rxnorm_to_ndc.map("197381")  # Get all NDC codes for RxNorm

Workflow Examples

Example 1: Standardize and Group Diagnoses

from pyhealth.medcode import InnerMap, CrossMap

# Load maps
icd9_map = InnerMap.load("ICD9CM")
icd_to_ccs = CrossMap.load("ICD9CM", "CCSCM")

# Process diagnosis codes
raw_codes = ["4280", "428.0", "42800"]

standardized = [icd9_map.standardize(code) for code in raw_codes]
# All become "428.0"

ccs_categories = [icd_to_ccs.map(code)[0] for code in standardized]
# All map to CCS category "108" (Heart failure)

Example 2: Drug Classification Analysis

from pyhealth.medcode import CrossMap

# Map NDC to ATC for drug class analysis
ndc_to_atc = CrossMap.load("NDC", "ATC")

patient_drugs = ["00074-3799-13", "00074-7286-01", "00456-0765-01"]

# Get therapeutic subgroups (ATC level 2)
drug_classes = []
for ndc in patient_drugs:
    atc_codes = ndc_to_atc.map(ndc, level=2)
    if atc_codes:
        drug_classes.append(atc_codes[0])

# Analyze drug class distribution

Example 3: ICD-9 to ICD-10 Migration

from pyhealth.medcode import CrossMap

# Load ICD-9 to ICD-10 mapping
icd9_to_icd10 = CrossMap.load("ICD9CM", "ICD10CM")

# Convert historical ICD-9 codes
icd9_code = "428.0"
icd10_codes = icd9_to_icd10.map(icd9_code)
# Returns: ["I50.9", "I50.1", ...]  # Multiple possible ICD-10 codes

# Handle one-to-many mappings
for icd10_code in icd10_codes:
    print(f"ICD-9 {icd9_code} -> ICD-10 {icd10_code}")

Integration with Datasets

Medical code translation integrates seamlessly with PyHealth datasets:

from pyhealth.datasets import MIMIC4Dataset
from pyhealth.medcode import CrossMap

# Load dataset
dataset = MIMIC4Dataset(root="/path/to/data")

# Load code mapping
icd_to_ccs = CrossMap.load("ICD10CM", "CCSCM")

# Process patient diagnoses
for patient in dataset.iter_patients():
    for visit in patient.visits:
        diagnosis_events = [e for e in visit.events if e.vocabulary == "ICD10CM"]

        for event in diagnosis_events:
            ccs_codes = icd_to_ccs.map(event.code)
            print(f"Diagnosis {event.code} -> CCS {ccs_codes}")

Use Cases

Clinical Research

  • Standardize diagnoses across different coding systems
  • Group related conditions for cohort identification
  • Harmonize multi-site studies with different standards

Drug Safety Analysis

  • Classify medications by therapeutic class
  • Identify drug-drug interactions at class level
  • Analyze polypharmacy patterns

Healthcare Analytics

  • Reduce diagnosis/procedure dimensionality
  • Create meaningful clinical categories
  • Enable longitudinal analysis across coding system changes

Machine Learning

  • Create consistent feature representations
  • Handle vocabulary mismatch in training/test data
  • Generate hierarchical embeddings

Best Practices

  1. Always standardize codes before mapping to ensure consistent format
  2. Handle one-to-many mappings appropriately (some codes map to multiple targets)
  3. Specify ATC level explicitly when mapping drugs to avoid ambiguity
  4. Use CCS categories to reduce diagnosis/procedure dimensionality
  5. Validate mappings as some codes may not have direct translations
  6. Document code versions (ICD-9 vs ICD-10) to maintain data provenance
← Back to pyhealth