aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/adapters/ccda/codes.py

@@ -0,0 +1,198 @@
+"""Scan-and-identify code extraction for CCDA <code> elements.
+
+Implements LOINC_pattern_analysis.md §3.4: never predict which slot holds a
+code; enumerate the root <code> + all <translation> children, canonicalize each
+by system, and let downstream pick. Also extracts <value>, effectiveTime,
+interpretation and reference ranges.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from lxml import etree
+
+from ...core.checkdigits import is_valid_loinc, is_valid_sctid
+from ...core.models import (
+    CodingCandidate,
+    System,
+    ValueInfo,
+    QN,
+    ORD,
+    NOM,
+    NAR,
+)
+from ...core.system_registry import canonicalize
+
+V3 = "urn:hl7-org:v3"
+XSI = "http://www.w3.org/2001/XMLSchema-instance"
+
+
+def q(tag: str) -> str:
+    """Qualify an unprefixed tag with the HL7 V3 default namespace."""
+    return f"{{{V3}}}{tag}"
+
+
+def xsi_type(el: etree._Element) -> Optional[str]:
+    t = el.get(f"{{{XSI}}}type")
+    if t and ":" in t:
+        t = t.split(":", 1)[1]
+    return t
+
+
+def _coding_from_code_el(el: etree._Element, from_translation: bool) -> CodingCandidate:
+    raw_system = el.get("codeSystem") or el.get("codeSystemName")
+    system = canonicalize(raw_system)
+    code = el.get("code")
+    cand = CodingCandidate(
+        raw_system=raw_system,
+        system=system,
+        code=code,
+        display=el.get("displayName"),
+        from_translation=from_translation,
+    )
+    if code:
+        if system == System.LOINC:
+            cand.check_digit_valid = is_valid_loinc(code)
+        elif system == System.SNOMEDCT:
+            cand.check_digit_valid = is_valid_sctid(code)
+    return cand
+
+
+def scan_codings(code_el: Optional[etree._Element]) -> list[CodingCandidate]:
+    """Return all codings on a <code> element: root + every <translation>.
+
+    A nullFlavor code with no code attribute still yields a candidate (so the
+    handler can classify it as a NULLFLAVOR gap), but only if it carries a
+    nullFlavor or displayName/originalText signal.
+    """
+    if code_el is None:
+        return []
+    codings: list[CodingCandidate] = []
+
+    null_flavor = code_el.get("nullFlavor")
+    if code_el.get("code") or code_el.get("codeSystem") or null_flavor:
+        root = _coding_from_code_el(code_el, from_translation=False)
+        if null_flavor and not root.code:
+            root.system = System.NULLFLAVOR
+            root.raw_system = null_flavor  # the flavor itself: UNK, OTH, NA, NI, …
+        codings.append(root)
+
+    for tr in code_el.findall(q("translation")):
+        codings.append(_coding_from_code_el(tr, from_translation=True))
+
+    return codings
+
+
+def best_loinc(codings: list[CodingCandidate]) -> Optional[CodingCandidate]:
+    """Select the canonical LOINC coding (root preferred, must validate)."""
+    hits = [
+        c
+        for c in codings
+        if c.system == System.LOINC and c.code and c.check_digit_valid
+    ]
+    if not hits:
+        return None
+    roots = [c for c in hits if not c.from_translation]
+    return roots[0] if roots else hits[0]
+
+
+# --------------------------------------------------------------------------
+# Value extraction
+# --------------------------------------------------------------------------
+
+def extract_value(obs_el: etree._Element) -> Optional[ValueInfo]:
+    val = obs_el.find(q("value"))
+    if val is None:
+        return None
+    t = xsi_type(val)
+
+    if t in ("PQ", "REAL", "INT"):
+        raw = val.get("value")
+        num = _to_float(raw)
+        return ValueInfo(
+            type=QN, raw=raw, num=num, unit=val.get("unit"),
+            unit_system="UCUM" if val.get("unit") else None,
+        )
+    if t in ("CD", "CE", "CO"):
+        # scan the value's root <code> + any <translation> children (e.g. a SNOMED
+        # value with an ICD-10-CM translation, or vice-versa) — same structure as
+        # a <code> element, so reuse scan_codings.
+        codings = scan_codings(val)
+        coded = next((c for c in codings if not c.from_translation),
+                     codings[0] if codings else None)
+        vtype = ORD if (val.get("displayName") or "").lower() in _ORDINAL_WORDS else NOM
+        return ValueInfo(type=vtype, raw=val.get("displayName") or val.get("code"),
+                         coded_value=coded, codings=codings)
+    if t in ("ST", "ED"):
+        return ValueInfo(type=NAR, raw=(val.text or "").strip() or None)
+    if t == "IVL_PQ":
+        low = val.find(q("low"))
+        raw = low.get("value") if low is not None else None
+        return ValueInfo(type=QN, raw=raw, num=_to_float(raw),
+                         unit=low.get("unit") if low is not None else None,
+                         unit_system="UCUM")
+    # unknown type: keep whatever value attr exists
+    raw = val.get("value") or (val.text or "").strip() or None
+    return ValueInfo(type=None, raw=raw, num=_to_float(val.get("value")),
+                     unit=val.get("unit"))
+
+
+_ORDINAL_WORDS = {"positive", "negative", "reactive", "non-reactive",
+                  "detected", "not detected", "present", "absent"}
+
+
+def extract_effective_time(obs_el: etree._Element) -> Optional[str]:
+    et = obs_el.find(q("effectiveTime"))
+    if et is None:
+        return None
+    if et.get("value"):
+        return et.get("value")
+    low = et.find(q("low"))
+    return low.get("value") if low is not None else None
+
+
+def extract_specimen(el: etree._Element) -> Optional[dict]:
+    """Explicit specimen from an observation or organizer:
+    specimen/specimenRole/specimenPlayingEntity/code (usually SNOMED).
+    Returns {code, system, display} or None.
+    """
+    sp = el.find(
+        f"{q('specimen')}/{q('specimenRole')}/{q('specimenPlayingEntity')}/{q('code')}"
+    )
+    if sp is None:
+        return None
+    return {
+        "code": sp.get("code"),
+        "system": canonicalize(sp.get("codeSystem")),
+        "display": sp.get("displayName"),
+    }
+
+
+def extract_companion(obs_el: etree._Element) -> dict:
+    out: dict = {}
+    interp = obs_el.find(q("interpretationCode"))
+    if interp is not None and interp.get("code"):
+        out["interpretation"] = interp.get("code")
+
+    # reference range: observationRange/value (IVL_PQ low-high) or text
+    rng = obs_el.find(f"{q('referenceRange')}/{q('observationRange')}/{q('value')}")
+    if rng is not None:
+        low = rng.find(q("low"))
+        high = rng.find(q("high"))
+        if low is not None or high is not None:
+            lo = low.get("value") if low is not None else ""
+            hi = high.get("value") if high is not None else ""
+            unit = (low.get("unit") if low is not None else None) or (
+                high.get("unit") if high is not None else None)
+            out["reference_range"] = f"{lo}-{hi}" + (f" {unit}" if unit else "")
+    return out
+
+
+def _to_float(s: Optional[str]) -> Optional[float]:
+    if s is None:
+        return None
+    try:
+        return float(s)
+    except (ValueError, TypeError):
+        return None

aimedicalcoding/adapters/ccda/narrative.py

@@ -0,0 +1,121 @@
+"""CCDA narrative handling.
+
+Two jobs (LOINC_pattern_analysis.md §3.5):
+  1. originalText/<reference value="#id"/> resolution against the section's
+     human-readable <text> block.
+  2. Narrative-table extraction for sections/rows that have NO structured
+     <entry> — the highest-yield "display without code" recovery path.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from lxml import etree
+
+from .codes import q
+
+_NUM_UNIT = re.compile(r"^\s*([<>]?=?\s*-?\d+(?:\.\d+)?)\s*([A-Za-z%/µ°\[\]\d\.\^*-]*)\s*$")
+_RANGE = re.compile(r"^\s*-?\d+(?:\.\d+)?\s*[-–]\s*-?\d+(?:\.\d+)?")
+
+
+def text_of(el: etree._Element) -> str:
+    """Flattened text content of a narrative element."""
+    return re.sub(r"\s+", " ", "".join(el.itertext())).strip()
+
+
+def build_id_map(section_el: etree._Element) -> dict[str, str]:
+    """Map every narrative element carrying an ID/id attribute to its text.
+
+    Used to resolve <reference value="#id"/> from originalText.
+    """
+    text_el = section_el.find(q("text"))
+    if text_el is None:
+        return {}
+    id_map: dict[str, str] = {}
+    for el in text_el.iter():
+        for attr in ("ID", "id"):
+            ref_id = el.get(attr)
+            if ref_id:
+                id_map[ref_id] = text_of(el)
+    return id_map
+
+
+def resolve_reference(id_map: dict[str, str], ref: Optional[str]) -> Optional[str]:
+    if not ref:
+        return None
+    return id_map.get(ref.lstrip("#"))
+
+
+def original_text(code_el: Optional[etree._Element], id_map: dict[str, str]) -> Optional[str]:
+    """Return originalText for a <code>: inline text or resolved #reference."""
+    if code_el is None:
+        return None
+    ot = code_el.find(q("originalText"))
+    if ot is None:
+        return None
+    ref = ot.find(q("reference"))
+    if ref is not None and ref.get("value"):
+        resolved = resolve_reference(id_map, ref.get("value"))
+        if resolved:
+            return resolved
+    inline = text_of(ot)
+    return inline or None
+
+
+def parse_narrative_table(section_el: etree._Element) -> list[dict]:
+    """Extract rows from a section's narrative <table>(s).
+
+    Heuristic, source-tolerant: first cell is the analyte label; we then scan
+    remaining cells for a value+unit and a reference range. Returns a list of
+    {"label", "value_raw", "num", "unit", "reference_range", "row_index"}.
+    """
+    text_el = section_el.find(q("text"))
+    if text_el is None:
+        return []
+
+    rows: list[dict] = []
+    for table in text_el.iter(q("table")):
+        headers = _header_labels(table)
+        body_rows = list(table.iter(q("tr")))
+        for ri, tr in enumerate(body_rows):
+            cells = [text_of(td) for td in tr.iter(q("td"))]
+            if not cells:
+                continue  # header row (th) or empty
+            label = cells[0].strip()
+            if not label:
+                continue
+            row = {
+                "label": label,
+                "value_raw": None,
+                "num": None,
+                "unit": None,
+                "reference_range": None,
+                "row_index": ri,
+                "headers": headers,
+            }
+            for c in cells[1:]:
+                c = c.strip()
+                if not c:
+                    continue
+                if row["reference_range"] is None and _RANGE.match(c):
+                    row["reference_range"] = c
+                    continue
+                m = _NUM_UNIT.match(c)
+                if m and row["value_raw"] is None:
+                    row["value_raw"] = c
+                    try:
+                        row["num"] = float(m.group(1).replace(" ", "").lstrip("<>=~"))
+                    except ValueError:
+                        pass
+                    row["unit"] = m.group(2) or None
+            rows.append(row)
+    return rows
+
+
+def _header_labels(table: etree._Element) -> list[str]:
+    thead = table.find(q("thead"))
+    if thead is None:
+        return []
+    return [text_of(th) for tr in thead.iter(q("tr")) for th in tr.iter(q("th"))]

aimedicalcoding/adapters/ccda/sections.py

@@ -0,0 +1,44 @@
+"""CCDA section routing.
+
+Maps a section's LOINC code to (context, target_system_hint) so downstream
+handlers receive correctly-framed statements. This is *routing* knowledge, not
+terminology logic (ARCHITECTURE.md §1 subtlety): the adapter tags context/role,
+the handler stays format-agnostic.
+"""
+
+from __future__ import annotations
+
+from ...core.models import System
+
+# section LOINC code -> (context, entry-level target system hint)
+SECTION_ROUTING: dict[str, tuple[str, System | None]] = {
+    "30954-2": ("result", System.LOINC),          # Results
+    "8716-3": ("vital", System.LOINC),            # Vital signs
+    "11450-4": ("problem", System.SNOMEDCT),      # Problem list
+    "10160-0": ("medication", System.RXNORM),     # Medications
+    "11369-6": ("immunization", System.CVX),      # History of immunizations
+    "48765-2": ("allergy", System.RXNORM),        # Allergies
+    "47519-4": ("procedure", System.CPT),         # Procedures
+    "29762-2": ("social_history", System.LOINC),  # Social history (question slot)
+    "10157-6": ("family_history", System.SNOMEDCT),  # Family history
+    "47420-5": ("functional_status", System.LOINC),
+    "8648-8": ("hospital_course", None),
+    "18776-5": ("plan_of_treatment", None),
+    "46240-8": ("encounters", None),
+    "51848-0": ("assessment", System.LOINC),
+    # PHQ-9 / survey panels surface as LOINC inside assessment-style sections
+}
+
+# Result/observation organizer & observation templateIds (entries-level routing)
+TEMPLATE_RESULT_ORGANIZER = "2.16.840.1.113883.10.20.22.4.1"
+TEMPLATE_RESULT_OBSERVATION = "2.16.840.1.113883.10.20.22.4.2"
+TEMPLATE_VITALS_ORGANIZER = "2.16.840.1.113883.10.20.22.4.26"
+TEMPLATE_VITALS_OBSERVATION = "2.16.840.1.113883.10.20.22.4.27"
+TEMPLATE_ALLERGY_REACTION = "2.16.840.1.113883.10.20.22.4.9"   # Reaction Observation
+
+
+def route_section(section_code: str | None) -> tuple[str, System | None]:
+    """Return (context, target_system_hint) for a section LOINC code."""
+    if section_code and section_code in SECTION_ROUTING:
+        return SECTION_ROUTING[section_code]
+    return ("section", None)

aimedicalcoding/adapters/custom_json/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import CustomJsonAdapter
+
+__all__ = ["CustomJsonAdapter"]

aimedicalcoding/adapters/custom_json/adapter.py

@@ -0,0 +1,30 @@
+"""Custom JSON adapter — PLACEHOLDER.
+
+Planned: config-driven field mapping per source (mappings/<source>.yaml),
+validate any 'loinc'-named key before trusting it, split combined "value unit"
+strings. See ARCHITECTURE.md §5.1 and LOINC_pattern_analysis.md §5.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ...core.models import ClinicalStatement
+from ..base import FormatAdapter
+
+
+class CustomJsonAdapter(FormatAdapter):
+    format_key = "custom"
+
+    def __init__(self, mapping: dict | None = None):
+        self.mapping = mapping or {}
+
+    def detect(self, document: str | bytes) -> bool:
+        # Custom JSON has no universal signature; the orchestrator selects it
+        # explicitly (by source config), not by detection.
+        return False
+
+    def parse(self, document: str | bytes) -> Iterable[ClinicalStatement]:
+        raise NotImplementedError(
+            "Custom JSON adapter is a placeholder; supply a source mapping later."
+        )

aimedicalcoding/adapters/fhir/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import FhirAdapter
+
+__all__ = ["FhirAdapter"]