aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/systems/icd10cm/icdformat.py

@@ -0,0 +1,43 @@
+"""ICD-10-CM format validation + billing-specificity qualifiers.
+
+ICD-10-CM has no check digit; a code is *well-formed* if it matches the shape
+(letter, 2 digits, optional dotted alphanumeric subclassification, up to 7 chars).
+Whether it is *billable* (vs a non-billable category) needs the DB.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# First char is any letter A-Z. U was historically reserved, but ICD-10-CM now
+# uses it: U07.1 (COVID-19), U09.9 (post-COVID condition), U07.0 (vaping).
+_ICD10CM = re.compile(r"^[A-Z][0-9][0-9A-Z](\.[0-9A-Z]{1,4})?$")
+
+_LATERALITY = ["bilateral", "left", "right"]
+_ENCOUNTER = ["initial", "subsequent", "sequela"]
+_COMPLICATIONS = [
+    "without complication", "with hyperglycemia", "with hypoglycemia",
+    "with neuropathy", "with nephropathy", "with retinopathy",
+    "with ketoacidosis", "with complication",
+]
+
+
+def is_valid_icd10cm(code: Optional[str]) -> bool:
+    return bool(code and _ICD10CM.match(code.strip().upper()))
+
+
+def _find(text: str, options) -> Optional[str]:
+    for o in options:
+        if o in text:
+            return o
+    return None
+
+
+def extract_qualifiers(text: Optional[str]) -> dict:
+    t = (text or "").lower()
+    return {
+        "laterality": _find(t, _LATERALITY),
+        "encounter": _find(t, _ENCOUNTER),
+        "complication": _find(t, _COMPLICATIONS),
+    }

aimedicalcoding/systems/icd10cm/patterns.py

@@ -0,0 +1,133 @@
+"""Per-pattern ICD-10-CM gap classification + parsers (diagnosis value slot)."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from ...core.models import ClinicalStatement, CodingCandidate, Gap, System
+from ...core.system_registry import HL7_STRUCTURAL
+from . import icdformat as F
+
+# diagnosis sections where an ICD-10-CM code is expected (value slot)
+ICD_CONTEXTS = {"problem", "encounters"}
+STRUCTURAL = HL7_STRUCTURAL | {System.NULLFLAVOR}
+
+
+class Icd10cmGapPattern(str, Enum):
+    SNOMED_ONLY = "SNOMED_ONLY"           # SNOMED in the value, no ICD -> SNOMED→ICD map
+    LOCAL_CODE_ONLY = "LOCAL_CODE_ONLY"   # local/ICD-9/other code, no ICD-10-CM
+    NULLFLAVOR = "NULLFLAVOR"
+    DISPLAY_ONLY = "DISPLAY_ONLY"
+    NARRATIVE_ONLY = "NARRATIVE_ONLY"
+    BAD_CODE = "BAD_CODE"                 # ICD-shaped but malformed
+
+
+def is_icd_expected(stmt: ClinicalStatement) -> bool:
+    return stmt.context in ICD_CONTEXTS and stmt.value is not None
+
+
+def _value_codings(stmt: ClinicalStatement):
+    return stmt.value.codings if (stmt.value and stmt.value.codings) else (
+        [stmt.value.coded_value] if (stmt.value and stmt.value.coded_value) else [])
+
+
+def icd_coding(stmt: ClinicalStatement) -> Optional[CodingCandidate]:
+    """The ICD-10-CM coding on the value, if present (root or translation)."""
+    return next((c for c in _value_codings(stmt)
+                 if c.system == System.ICD10CM and c.code), None)
+
+
+def concept_coding(stmt: ClinicalStatement) -> Optional[CodingCandidate]:
+    """The coding to recover from: prefer ICD-10-CM, else the best alternative
+    present (SNOMED / ICD-9 / local)."""
+    icd = icd_coding(stmt)
+    if icd:
+        return icd
+    return next((c for c in _value_codings(stmt)
+                 if c.code and c.system not in STRUCTURAL), None)
+
+
+def _has_nullflavor(stmt: ClinicalStatement) -> bool:
+    return any(c.system == System.NULLFLAVOR for c in _value_codings(stmt))
+
+
+def classify(stmt: ClinicalStatement) -> Optional[Icd10cmGapPattern]:
+    if not is_icd_expected(stmt):
+        return None
+
+    icd = icd_coding(stmt)
+    if icd:
+        return None if F.is_valid_icd10cm(icd.code) else Icd10cmGapPattern.BAD_CODE
+
+    other = next((c for c in _value_codings(stmt)
+                  if c.code and c.system not in STRUCTURAL), None)
+    if other and other.system == System.SNOMEDCT:
+        return Icd10cmGapPattern.SNOMED_ONLY
+    if other:                                   # ICD-9 / local / anything else
+        return Icd10cmGapPattern.LOCAL_CODE_ONLY
+
+    if _has_nullflavor(stmt):
+        return Icd10cmGapPattern.NULLFLAVOR
+    if stmt.raw_text or (stmt.value and (stmt.value.original_text or stmt.value.raw)):
+        if "/text" in (stmt.source_ref or ""):
+            return Icd10cmGapPattern.NARRATIVE_ONLY
+        return Icd10cmGapPattern.DISPLAY_ONLY
+    return None
+
+
+# --------------------------------------------------------------------------
+
+def _term(stmt: ClinicalStatement) -> Optional[str]:
+    cc = concept_coding(stmt)
+    if cc and cc.display:
+        return cc.display
+    if stmt.value and (stmt.value.original_text or stmt.value.raw):
+        return stmt.value.original_text or stmt.value.raw
+    return stmt.raw_text
+
+
+def _match_key(stmt: ClinicalStatement, term: Optional[str]) -> str:
+    q = F.extract_qualifiers(term)
+    return " | ".join([
+        f"condition:{(term or '?').lower()}",
+        f"laterality:{q['laterality'] or '-'}",
+        f"encounter:{q['encounter'] or '-'}",
+        f"complication:{q['complication'] or '-'}",
+    ])
+
+
+def parse_gap(stmt: ClinicalStatement, pattern: Icd10cmGapPattern) -> Gap:
+    term = _term(stmt)
+    q = F.extract_qualifiers(term)
+    ev = {
+        "term": term,
+        "laterality": q["laterality"],
+        "encounter": q["encounter"],
+        "complication": q["complication"],
+        "section_context": stmt.context,
+    }
+    gap = Gap(type=pattern.value, match_key=_match_key(stmt, term), evidence=ev)
+    cc = concept_coding(stmt)
+
+    if pattern == Icd10cmGapPattern.SNOMED_ONLY and cc:
+        gap.evidence["snomed_code"] = cc.code
+        gap.evidence["snomed_system"] = (cc.system.value if cc.system else None)
+        gap.note = ("Use the official SNOMED CT → ICD-10-CM map (NLM) — mostly "
+                    "deterministic; LLM to pick among targets / add specificity.")
+    elif pattern == Icd10cmGapPattern.LOCAL_CODE_ONLY and cc:
+        gap.evidence["local_code"] = cc.code
+        gap.evidence["local_system"] = (cc.system.value if cc.system else cc.raw_system)
+        gap.note = ("Crosswalk the source code → ICD-10-CM (ICD-9 → use CMS GEMs); "
+                    "else text + qualifier search.")
+    elif pattern == Icd10cmGapPattern.BAD_CODE and cc:
+        gap.evidence["malformed_code"] = cc.code
+        gap.note = "ICD-shaped but malformed; re-resolve via text + qualifiers."
+    elif pattern == Icd10cmGapPattern.NULLFLAVOR:
+        nf = next((c for c in _value_codings(stmt)
+                   if c.system == System.NULLFLAVOR), None)
+        gap.evidence["null_flavor"] = nf.raw_system if nf else None
+        gap.note = "Diagnosis recovered from narrative; text + qualifier search."
+    else:
+        gap.note = "Diagnosis text only; search ICD-10-CM by term + qualifiers."
+    return gap

aimedicalcoding/systems/loinc/__init__.py

@@ -0,0 +1,14 @@
+"""LOINC-specific gap extraction.
+
+Consumes the format-agnostic IR and emits ONLY the statements that need a LOINC
+code corrected or filled — classified per pattern, each with a recovery evidence
+packet + composite match key. Valid, already-coded LOINCs are skipped.
+
+DB lookup and LLM ranking remain placeholders; this layer prepares everything
+the recovery step needs.
+"""
+
+from .handler import LoincGapExtractor, GapPattern
+from .patterns import classify, is_loinc_expected
+
+__all__ = ["LoincGapExtractor", "GapPattern", "classify", "is_loinc_expected"]

aimedicalcoding/systems/loinc/axes.py

@@ -0,0 +1,199 @@
+"""Derive LOINC disambiguating axes from a ClinicalStatement.
+
+Turns the raw IR (unit, value shape, panel, text) into the axis hints that
+constrain a LOINC candidate set (LOINC_pattern_analysis.md §2.5):
+  unit  -> Property      value -> Scale      panel/text/section -> System(specimen)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ...core.models import ClinicalStatement, QN, ORD, NOM, NAR
+from .normalize import normalize_analyte
+
+# UCUM unit -> LOINC Property hint
+_UNIT_PROPERTY = {
+    "mg/dl": "MCnc", "g/dl": "MCnc", "ug/dl": "MCnc", "ng/ml": "MCnc",
+    "mmol/l": "SCnc", "meq/l": "SCnc", "umol/l": "SCnc", "u/l": "CCnc",
+    "%": "MFr", "fl": "EntVol", "pg": "EntMass",
+    "mm[hg]": "Pres", "/min": "NRat", "cel": "Temp", "kg": "Mass",
+    "cm": "Len", "kg/m2": "Ratio", "[degf]": "Temp", "/min)": "NRat",
+}
+
+_SPECIMEN_HINTS = {
+    "serum": "Ser", "plasma": "Plas", "ser/plas": "Ser/Plas",
+    "blood": "Bld", "whole blood": "Bld", "urine": "Urine",
+    "csf": "CSF", "cerebrospinal": "CSF", "stool": "Stool",
+    "saliva": "Saliva", "sputum": "Sputum",
+}
+
+# SNOMED specimen codes -> LOINC System-axis hint (explicit <specimen> element)
+_SPECIMEN_CODE = {
+    "119364003": "Ser",    "119361006": "Plas",   "119297000": "Bld",
+    "122555007": "Bld",    "122575003": "Urine",  "258574006": "Bld",
+    "258450006": "CSF",    "119339001": "Stool",  "119342007": "Saliva",
+    "119334006": "Sputum",
+}
+
+# A *generic* "blood" specimen is the COLLECTED sample, not a reliable LOINC
+# System axis. Routine chemistry drawn from blood is reported in Serum/Plasma,
+# so a generic blood specimen must NOT be trusted as "Bld" — LOINC reserves
+# "Bld" for true whole-blood analytes (HbA1c, blood gases, lead, …). We demote
+# it and let panel/analyte context decide.
+_GENERIC_BLOOD = "Bld"
+
+# panels (LOINC and CPT) whose membership implies a serum/plasma specimen
+_SERUM_PANELS = {
+    "24323-8", "24321-2", "24320-4",   # LOINC: CMP, BMP, electrolytes
+    "24325-3", "24331-1",              # LOINC: hepatic function, lipid
+    "80053", "80048", "80051",         # CPT:   CMP, BMP, electrolytes
+    "80076", "80061",                  # CPT:   hepatic function, lipid
+}
+
+
+def _specimen_to_hint(display: Optional[str], code: Optional[str]) -> Optional[str]:
+    if code and code in _SPECIMEN_CODE:
+        return _SPECIMEN_CODE[code]
+    d = (display or "").lower()
+    for word, hint in _SPECIMEN_HINTS.items():
+        if word in d:
+            return hint
+    return display or None
+
+
+# Units whose Property is ambiguous — the same unit maps to different LOINC
+# Properties depending on the analyte, so it must NOT be a hard filter:
+#   "%"  -> HbA1c is MFr, but CBC differentials are NFr, SpO2 is a sat fraction.
+_AMBIGUOUS_UNITS = {"%"}
+
+
+def property_from_unit(unit: Optional[str]) -> Optional[str]:
+    if not unit:
+        return None
+    return _UNIT_PROPERTY.get(unit.strip().lower())
+
+
+def property_from_unit_conf(unit: Optional[str]) -> tuple[Optional[str], str]:
+    """Property hint + confidence. Ambiguous units (e.g. '%') are LOW confidence
+    so downstream treats them as a soft hint, not a hard filter (mirrors the
+    specimen-axis gating that fixed the Bld/Ser-Plas bug)."""
+    hint = property_from_unit(unit)
+    if not hint:
+        return (None, "none")
+    conf = "low" if (unit or "").strip().lower() in _AMBIGUOUS_UNITS else "high"
+    return (hint, conf)
+
+
+def scale_from_value(stmt: ClinicalStatement) -> Optional[str]:
+    if stmt.value and stmt.value.type:
+        return stmt.value.type  # QN / ORD / NOM / NAR already inferred by adapter
+    return None
+
+
+def infer_specimen(stmt: ClinicalStatement) -> tuple[Optional[str], str, str]:
+    """Resolve the LOINC System axis with a priority that reflects trust. Returns
+    (hint, source, confidence):
+      1. explicit SPECIFIC specimen (Ser/Plas/Urine/CSF/…) -> "explicit", high
+      1b. explicit GENERIC "blood":                         -> ambiguous —
+          - inside a serum/plasma panel -> "Ser/Plas", "panel_over_blood", medium
+          - otherwise                   -> "Bld",      "explicit_generic_blood", low
+      2. analyte text ("urine", "csf", …)                   -> "text", medium
+      3. parent panel convention (CMP/BMP/…)                -> "panel", low
+      else                                                  -> (None, "none", "none")
+
+    Why 1b exists: a CCDA commonly carries SNOMED 119297000 "Blood specimen" (the
+    *collected* draw) on a chemistry panel whose analytes are actually reported in
+    Serum/Plasma. Trusting that generic "blood" as LOINC "Bld" picked the wrong
+    code (e.g. Glucose 2339-0 Bld instead of 2345-7 Ser/Plas). The panel — and the
+    coded siblings — are the reliable signal, so generic blood no longer overrides
+    a serum/plasma panel.
+    """
+    panel_is_serum = bool(stmt.panel and stmt.panel.code in _SERUM_PANELS)
+
+    # (1) explicit specimen captured from the document
+    explicit = None
+    if stmt.companion.get("specimen") or stmt.companion.get("specimen_code"):
+        explicit = _specimen_to_hint(stmt.companion.get("specimen"),
+                                     stmt.companion.get("specimen_code"))
+
+    # (1) explicit + SPECIFIC -> trust it fully
+    if explicit and explicit != _GENERIC_BLOOD:
+        return (explicit, "explicit", "high")
+
+    # (1b) explicit but GENERIC blood -> ambiguous; serum/plasma panel overrides
+    if explicit == _GENERIC_BLOOD:
+        if panel_is_serum:
+            return ("Ser/Plas", "panel_over_blood", "medium")
+        return (_GENERIC_BLOOD, "explicit_generic_blood", "low")
+
+    # (2) analyte text
+    text = (stmt.raw_text or "").lower()
+    for word, hint in _SPECIMEN_HINTS.items():
+        if word in text:
+            if hint == _GENERIC_BLOOD and panel_is_serum:
+                return ("Ser/Plas", "panel_over_blood", "medium")
+            return (hint, "text", "medium")
+
+    # (3) panel convention (fallback, low confidence)
+    if panel_is_serum:
+        return ("Ser/Plas", "panel", "low")
+
+    return (None, "none", "none")
+
+
+def method_from_text(stmt: ClinicalStatement) -> Optional[str]:
+    text = (stmt.raw_text or "").lower()
+    for kw in ("fasting", "post", "challenge", "poc", "point of care", "random"):
+        if kw in text:
+            return kw
+    return None
+
+
+def build_match_key(stmt: ClinicalStatement, expand_abbrev: bool = False) -> str:
+    """Composite disambiguation key (component + specimen + property + scale + method).
+
+    The component shows the original text; when ``expand_abbrev`` is on and an
+    abbreviation was expanded, it also shows the search term after an arrow
+    (e.g. ``BUN→urea nitrogen``) so the file's own wording stays visible.
+    """
+    raw = (stmt.raw_text or "").strip()
+    norm = normalize_analyte(stmt.raw_text, expand=expand_abbrev) or "?"
+    if not raw:
+        component = norm
+    elif norm == raw.lower():
+        component = raw
+    else:
+        component = f"{raw}→{norm}"
+    specimen_hint, _, _ = infer_specimen(stmt)
+    parts = [
+        f"component:{component}",
+        f"specimen:{specimen_hint or '?'}",
+        f"property:{property_from_unit(stmt.value.unit if stmt.value else None) or '?'}",
+        f"scale:{scale_from_value(stmt) or '?'}",
+        f"method:{method_from_text(stmt) or '-'}",
+    ]
+    return " | ".join(parts)
+
+
+def evidence_packet(stmt: ClinicalStatement, expand_abbrev: bool = False) -> dict:
+    """Everything the recovery layer (DB search / LLM) needs to resolve a LOINC."""
+    unit = stmt.value.unit if stmt.value else None
+    specimen_hint, specimen_source, specimen_conf = infer_specimen(stmt)
+    property_hint, property_conf = property_from_unit_conf(unit)
+    return {
+        "analyte_raw": stmt.raw_text,
+        "analyte_normalized": normalize_analyte(stmt.raw_text, expand=expand_abbrev),
+        "unit": unit,
+        "property_hint": property_hint,
+        "property_confidence": property_conf,       # high | low | none
+        "scale_hint": scale_from_value(stmt),
+        "specimen_hint": specimen_hint,
+        "specimen_source": specimen_source,        # explicit | text | panel | none
+        "specimen_confidence": specimen_conf,      # high | medium | low | none
+        "method_hint": method_from_text(stmt),
+        "value": stmt.value.raw if stmt.value else None,
+        "reference_range": stmt.companion.get("reference_range"),
+        "panel": (stmt.panel.code if stmt.panel else None),
+        "context": stmt.context,
+    }

aimedicalcoding/systems/loinc/handler.py

@@ -0,0 +1,80 @@
+"""LoincGapExtractor — the LOINC-only, gaps-only entry point.
+
+Takes either a raw document or already-parsed IR statements and returns
+``NormalizedRecord``s ONLY for observations whose LOINC needs correcting or
+filling. Each record carries the gap pattern, match key, and evidence packet;
+``resolved_*`` is left for the (placeholder) DB/LLM recovery step.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from ...core.models import ClinicalStatement, NormalizedRecord, System
+from ...pipeline import parse_document
+from . import patterns
+from .patterns import GapPattern
+
+__all__ = ["LoincGapExtractor", "GapPattern"]
+
+
+class LoincGapExtractor:
+    def extract(
+        self,
+        statements: Iterable[ClinicalStatement],
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,
+    ) -> list[NormalizedRecord]:
+        """Return gap records ONLY (valid/coded LOINCs are skipped).
+
+        ``contexts`` optionally restricts which statement contexts are inspected
+        (e.g. {"result", "vital"} for a lab-focused run).
+
+        ``include_narrative`` (default False): NARRATIVE_ONLY gaps come from
+        human-readable narrative tables (often questionnaire text) and are
+        skipped by default.
+
+        ``apply_dict`` (default False): expand lab abbreviations (BUN -> urea
+        nitrogen) in the match key / evidence to boost LOINC text-search recall.
+        Off by default so output reflects the document's own wording.
+        """
+        records: list[NormalizedRecord] = []
+        for stmt in statements:
+            if contexts is not None and stmt.context not in contexts:
+                continue
+            pattern = patterns.classify(stmt)
+            if pattern is None:
+                continue  # valid LOINC, or not a LOINC-expected node
+            if pattern is GapPattern.NARRATIVE_ONLY and not include_narrative:
+                continue  # human-readable narrative; not a code-recovery target
+            gap = patterns.parse_gap(stmt, pattern, expand_abbrev=apply_dict)
+            records.append(NormalizedRecord(
+                statement=stmt,
+                resolved_system=System.LOINC,   # the target system
+                resolved_code=None,             # filled by recovery layer later
+                gap=gap,
+            ))
+        return records
+
+    def extract_from_document(
+        self,
+        document: str | bytes,
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,
+    ) -> list[NormalizedRecord]:
+        """Parse a CCDA/FHIR document and return LOINC gap records."""
+        return self.extract(
+            parse_document(document),
+            contexts=contexts,
+            include_narrative=include_narrative,
+            apply_dict=apply_dict,
+        )
+
+    def summary(self, records: list[NormalizedRecord]) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for r in records:
+            t = r.gap.type if r.gap else "RESOLVED"
+            out[t] = out.get(t, 0) + 1
+        return out

aimedicalcoding/systems/loinc/normalize.py

@@ -0,0 +1,81 @@
+"""Analyte text normalization for LOINC matching.
+
+Local codes and narrative labels are terse and abbreviated; normalize before
+any text search. Whole-token abbreviation expansion only (so "Na" -> sodium but
+"Nasal" is untouched).
+"""
+
+from __future__ import annotations
+
+import re
+
+# common lab abbreviation -> canonical component word(s)
+ABBREV = {
+    "na": "sodium",
+    "k": "potassium",
+    "cl": "chloride",
+    "co2": "carbon dioxide",
+    "bun": "urea nitrogen",
+    "cr": "creatinine",
+    "creat": "creatinine",
+    "glu": "glucose",
+    "ca": "calcium",
+    "mg": "magnesium",
+    "phos": "phosphate",
+    "hgb": "hemoglobin",
+    "hb": "hemoglobin",
+    "hct": "hematocrit",
+    "wbc": "leukocytes",
+    "rbc": "erythrocytes",
+    "plt": "platelets",
+    "a1c": "hemoglobin a1c",
+    "hba1c": "hemoglobin a1c",
+    "alt": "alanine aminotransferase",
+    "ast": "aspartate aminotransferase",
+    "alk phos": "alkaline phosphatase",
+    "tsh": "thyrotropin",
+    "ldl": "ldl cholesterol",
+    "hdl": "hdl cholesterol",
+    "trig": "triglyceride",
+    "inr": "inr",
+    "sbp": "systolic blood pressure",
+    "dbp": "diastolic blood pressure",
+    "hr": "heart rate",
+    "rr": "respiratory rate",
+    "temp": "body temperature",
+    "spo2": "oxygen saturation",
+    "bmi": "body mass index",
+}
+
+_PUNCT = re.compile(r"[^\w\s%/.\-]")
+_WS = re.compile(r"\s+")
+
+
+def normalize_analyte(text: str | None, expand: bool = False) -> str | None:
+    """Lowercase and strip noise punctuation.
+
+    ``expand`` (default False): when True, also expand known lab abbreviations
+    via the ABBREV dictionary (e.g. BUN -> urea nitrogen). Off by default so the
+    output reflects the document's own wording; enable to boost LOINC text-search
+    recall. Case/punctuation normalization always happens; only the dictionary
+    is gated.
+    """
+    if not text:
+        return None
+    t = _PUNCT.sub(" ", text.lower())
+    t = _WS.sub(" ", t).strip()
+    if not t:
+        return None
+    if not expand:
+        return t
+    # whole-string abbreviation (e.g. "alk phos", "hba1c")
+    if t in ABBREV:
+        return ABBREV[t]
+    # token-wise expansion, then collapse adjacent duplicate words
+    # (e.g. "hemoglobin a1c" -> tokens expand to "hemoglobin hemoglobin a1c")
+    words: list[str] = []
+    for tok in t.split():
+        for w in ABBREV.get(tok, tok).split():
+            if not words or words[-1] != w:
+                words.append(w)
+    return " ".join(words)