parsing-lab-values

Parsing lab values

Lab results in clinical text arrive as a value, a unit, and a reference range ("Sodium 132 mmol/L (135–145)"). To act on them you need a structured abnormal flag — is 132 low, normal, high, or critical? OpenMed's openmed.clinical lab helpers parse the reference range deterministically and derive the flag, honoring any explicit flag the originating lab already supplied. The helpers are unit-agnostic by design: they compare numbers within a stated range and never convert units, so a mmol/L value is never silently compared against a mg/dL range.

When to use

• After extracting-clinical-entities surfaces lab/measurement entities and you need to classify each as low / normal / high / critical.
• The user asks to parse reference ranges, flag abnormal labs, build a flagged labs table, or interpret values like <5, >=10, 0.5 - 1.2.
• You have an originating-lab flag (H, L, C, HH) and want it honored over a derived comparison.

Quick start

from openmed.clinical import (
    parse_reference_range, derive_abnormal_flag, LAB_FLAG_ADVISORY,
)

# Closed range
rng = parse_reference_range("135-145")
# -> {"low": 135.0, "high": 145.0, "low_inclusive": True, "high_inclusive": True}

derive_abnormal_flag(132, rng)            # "low"
derive_abnormal_flag(140, "135-145")      # "normal"  (raw range string accepted)
derive_abnormal_flag(150, "135 to 145")   # "high"

# One-sided bounds
derive_abnormal_flag(7, parse_reference_range("<5"))    # "high" (above the cap)
derive_abnormal_flag(3, parse_reference_range(">=10"))  # "low"

# Honor the lab's own explicit flag (takes precedence over derived comparison)
derive_abnormal_flag(132, "135-145", explicit_flag="C")   # "critical"
derive_abnormal_flag(132, "135-145", explicit_flag="HH")  # "critical"

# Unparseable / non-numeric inputs fail safe rather than guessing
derive_abnormal_flag("pending", "135-145")  # "unknown"
derive_abnormal_flag(132, "see report")     # "unknown"

print(LAB_FLAG_ADVISORY)  # surface this disclaimer with derived flags