aimedicalcoding 0.3.4__tar.gz → 0.3.6__tar.gz

{aimedicalcoding-0.3.4/aimedicalcoding.egg-info → aimedicalcoding-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aimedicalcoding
-Version: 0.3.4
+Version: 0.3.6
 Summary: Detect missing/broken clinical codes (LOINC / SNOMED CT / RxNorm / ICD-10-CM / CVX) in CCDA and FHIR documents, with recovery evidence
 Author: Aakash Kag, Vinay Shankar Miryala, Siva Karthik, Mohammed Rayaan
 License: MIT

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6}/aimedicalcoding/adapters/ccda/codes.py

@@ -186,6 +186,18 @@ def extract_companion(obs_el: etree._Element) -> dict:
             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 "")
+
+    # method: the LOINC Method axis, carried structurally as <methodCode>.
+    # Prefer the displayName (e.g. "Automated") over the raw code.
+    method = obs_el.find(q("methodCode"))
+    if method is not None and (method.get("displayName") or method.get("code")):
+        out["method"] = method.get("displayName") or method.get("code")
+
+    # body site: <targetSiteCode> (usually SNOMED, e.g. "Right arm").
+    site = obs_el.find(q("targetSiteCode"))
+    if site is not None and (site.get("displayName") or site.get("code")):
+        out["body_site"] = site.get("displayName") or site.get("code")
+        out["body_site_code"] = site.get("code")
     return out
 
 

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6}/aimedicalcoding/serialize.py

@@ -87,14 +87,20 @@ def _qualifiers(stmt: ClinicalStatement) -> dict:
     unit = stmt.value.unit if stmt.value else None
     q = snomed_q.extract_qualifiers(stmt, stmt.raw_text)
     out = {
-        "specimen": {"value": spec_hint, "source": spec_src, "confidence": spec_conf},
+        "specimen": {"value": spec_hint, "source": spec_src, "confidence": spec_conf,
+                     # explicit specimen disagrees with the analyte text (data-quality signal)
+                     "conflict": loinc_axes.specimen_conflict(stmt)},
         "property": loinc_axes.property_from_unit(unit),
         "scale": loinc_axes.scale_from_value(stmt),
+        "method": stmt.companion.get("method"),
+        "body_site": stmt.companion.get("body_site"),
         "laterality": q["laterality"],
         "severity": q["severity"],
         "course": q["course"],
         # structural negationInd wins over text cues ("denies", "no known")
         "negation": ("negated" if stmt.companion.get("negation") else q["negation_context"]),
+        "interpretation": stmt.companion.get("interpretation"),
+        "reference_range": stmt.companion.get("reference_range"),
         "panel": (stmt.panel.code if stmt.panel else None),
         "effective_time": stmt.effective_time,
     }
@@ -121,20 +127,6 @@ def _dedupe(items) -> list:
     return out
 
 
-# SNOMED search-term enrichment (Problems 11450-4, Allergies 48765-2, Social
-# History 29762-2), matched by section LOINC or by the contexts those sections
-# route to (FHIR resources often carry no meta.tag/section code). Which slot's
-# labels get appended differs by section:
-#   - Social History  -> CODE tag labels (the question, e.g. "Gender identity" —
-#     the value label is often a placeholder like "Not on file")
-#   - Problems / Allergies -> VALUE tag labels (the concept; the code tag is a
-#     generic marker like ASSERTION / "Problem" — appending it is noise)
-_SNOMED_CODE_LABEL_SECTIONS = {"29762-2"}
-_SNOMED_CODE_LABEL_CONTEXTS = {"social_history"}
-_SNOMED_VALUE_LABEL_SECTIONS = {"11450-4", "48765-2"}
-_SNOMED_VALUE_LABEL_CONTEXTS = {"problem", "allergy_substance", "allergy_reaction"}
-
-
 def _recovery(record: NormalizedRecord, slot: str, system: str) -> dict:
     stmt, ev, g = record.statement, record.gap.evidence, record.gap
 
@@ -146,18 +138,17 @@ def _recovery(record: NormalizedRecord, slot: str, system: str) -> dict:
         terms = [stmt.display_name, stmt.original_text]
     # add any normalized term the handler produced
     terms += [ev.get("analyte_normalized"), ev.get("term_normalized"), ev.get("ingredient")]
-    # SNOMED only, Problems/Allergies/Social History only: append trailing
-    # label context from the section-appropriate slot (see constants above).
+    # SNOMED: guarantee the TARGET slot's own labels are present, mirroring
+    # `target.slot` in the output record — code-slot gaps carry the code tag's
+    # displayName/originalText, value-slot gaps the value tag's.
     if system == System.SNOMEDCT.value:
-        if (stmt.section_code in _SNOMED_CODE_LABEL_SECTIONS
-                or stmt.context in _SNOMED_CODE_LABEL_CONTEXTS):
-            terms += [stmt.display_name, stmt.original_text]
-        elif (stmt.section_code in _SNOMED_VALUE_LABEL_SECTIONS
-                or stmt.context in _SNOMED_VALUE_LABEL_CONTEXTS):
+        if slot == "value":
             if stmt.value:
                 terms += [stmt.value.coded_value.display
                           if stmt.value.coded_value else None,
                           stmt.value.original_text]
+        else:
+            terms += [stmt.display_name, stmt.original_text]
 
     rec = {
         "search_terms": _dedupe(terms),

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6}/aimedicalcoding/systems/loinc/axes.py

@@ -14,11 +14,26 @@ from .normalize import normalize_analyte
 
 # UCUM unit -> LOINC Property hint
 _UNIT_PROPERTY = {
+    # mass concentration
     "mg/dl": "MCnc", "g/dl": "MCnc", "ug/dl": "MCnc", "ng/ml": "MCnc",
-    "mmol/l": "SCnc", "meq/l": "SCnc", "umol/l": "SCnc", "u/l": "CCnc",
+    "mg/l": "MCnc", "ug/l": "MCnc", "ng/dl": "MCnc", "pg/ml": "MCnc",
+    "g/l": "MCnc",
+    # substance concentration
+    "mmol/l": "SCnc", "meq/l": "SCnc", "umol/l": "SCnc", "nmol/l": "SCnc",
+    "pmol/l": "SCnc", "mol/l": "SCnc",
+    # catalytic (enzyme) concentration
+    "u/l": "CCnc", "iu/l": "CCnc", "u/ml": "CCnc",
+    # arbitrary / international-unit concentration
+    "iu/ml": "ACnc", "miu/ml": "ACnc", "iu/dl": "ACnc",
+    # number concentration (counts per volume) — CBC analytes (platelets, WBC, RBC)
+    "10*3/ul": "NCnc", "10*6/ul": "NCnc", "10*9/l": "NCnc", "10*12/l": "NCnc",
+    "10*3/l": "NCnc", "/ul": "NCnc", "/l": "NCnc", "k/ul": "NCnc",
+    "m/ul": "NCnc", "cells/ul": "NCnc", "/mm3": "NCnc",
+    # fractions / other
     "%": "MFr", "fl": "EntVol", "pg": "EntMass",
     "mm[hg]": "Pres", "/min": "NRat", "cel": "Temp", "kg": "Mass",
     "cm": "Len", "kg/m2": "Ratio", "[degf]": "Temp", "/min)": "NRat",
+    "s": "Time", "mm/h": "Vel",
 }
 
 _SPECIMEN_HINTS = {
@@ -143,6 +158,11 @@ def infer_specimen(stmt: ClinicalStatement) -> tuple[Optional[str], str, str]:
 
 
 def method_from_text(stmt: ClinicalStatement) -> Optional[str]:
+    # Structural <methodCode> (LOINC Method axis) is more reliable than text
+    # cues — use it first (e.g. "Automated"), then fall back to text keywords.
+    method = stmt.companion.get("method")
+    if method:
+        return method
     text = (stmt.raw_text or "").lower()
     for kw in ("fasting", "post", "challenge", "poc", "point of care", "random"):
         if kw in text:
@@ -150,6 +170,24 @@ def method_from_text(stmt: ClinicalStatement) -> Optional[str]:
     return None
 
 
+# specimen words that name a specimen in analyte text (reuse the hint map)
+def specimen_conflict(stmt: ClinicalStatement) -> bool:
+    """True when an EXPLICIT specimen disagrees with a specimen named in the
+    analyte text — a data-quality signal (LOINC_pattern_analysis §1.2). E.g. an
+    explicit "Urine specimen" on a "Platelets ... in Blood" observation."""
+    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"))
+    if not explicit:
+        return False
+    text = (stmt.raw_text or "").lower()
+    for word, hint in _SPECIMEN_HINTS.items():
+        if word in text and hint != explicit:
+            return True
+    return False
+
+
 def build_match_key(stmt: ClinicalStatement, expand_abbrev: bool = False) -> str:
     """Composite disambiguation key (component + specimen + property + scale + method).
 
@@ -191,9 +229,12 @@ def evidence_packet(stmt: ClinicalStatement, expand_abbrev: bool = False) -> dic
         "specimen_hint": specimen_hint,
         "specimen_source": specimen_source,        # explicit | text | panel | none
         "specimen_confidence": specimen_conf,      # high | medium | low | none
+        "specimen_conflict": specimen_conflict(stmt),  # explicit vs analyte text
         "method_hint": method_from_text(stmt),
         "value": stmt.value.raw if stmt.value else None,
         "reference_range": stmt.companion.get("reference_range"),
+        "interpretation": stmt.companion.get("interpretation"),
+        "body_site": stmt.companion.get("body_site"),
         "panel": (stmt.panel.code if stmt.panel else None),
         "context": stmt.context,
     }

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6/aimedicalcoding.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aimedicalcoding
-Version: 0.3.4
+Version: 0.3.6
 Summary: Detect missing/broken clinical codes (LOINC / SNOMED CT / RxNorm / ICD-10-CM / CVX) in CCDA and FHIR documents, with recovery evidence
 Author: Aakash Kag, Vinay Shankar Miryala, Siva Karthik, Mohammed Rayaan
 License: MIT

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6}/docs/GAP_SCHEMA.md

@@ -63,9 +63,11 @@ Each record separates four concerns:
     "codings": [ ... ]
   },
   "qualifiers": {                 // disambiguation context (superset; nulls where N/A)
-    "specimen": { "value","source","confidence" },   // LOINC
-    "property": "MCnc", "scale": "Qn",               // LOINC
+    "specimen": { "value","source","confidence","conflict" }, // LOINC; conflict=explicit specimen disagrees with analyte text
+    "property": "MCnc", "scale": "Qn",               // LOINC (property from UCUM unit; NCnc for counts, etc.)
+    "method": "Automated", "body_site": "Right arm", // LOINC Method axis (<methodCode>) / <targetSiteCode>
     "laterality": null, "severity": null, "course": null, "negation": null,  // SNOMED
+    "interpretation": "N", "reference_range": "150-400 10*3/uL",  // observation companion data
     "panel": "24323-8", "effective_time": null
   }
 }
@@ -89,12 +91,9 @@ Each record separates four concerns:
 - `target.slot = "code"` (LOINC) → search `observation.code.display_text` / `.original_text`.
 - `target.slot = "value"` (SNOMED value-slot) → search `observation.value.display_text` / `.original_text`.
 `recovery.search_terms` already gives you the right ones, deduped.
-For **SNOMED-CT** targets, extra label context is appended at the end,
-section-specific: **Social History (29762-2)** appends the CODE tag's
-`display_text`/`original_text` (the question — useful when the value label
-is a placeholder like "Not on file"); **Problems (11450-4)** and
-**Allergies (48765-2)** append the VALUE tag's labels (the concept — the
-code tag there is a generic marker like ASSERTION/"Problem").
+For **SNOMED-CT** targets the terms follow `target.slot`: value-slot gaps
+carry the VALUE tag's `display_text`/`original_text`, code-slot gaps the
+CODE tag's — the other slot's labels are not mixed in.
 
 ---
 

{aimedicalcoding-0.3.4 → aimedicalcoding-0.3.6}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="aimedicalcoding",
-    version="0.3.4",
+    version="0.3.6",
     author="Aakash Kag, Vinay Shankar Miryala, Siva Karthik, Mohammed Rayaan",
     description=(
         "Detect missing/broken clinical codes (LOINC / SNOMED CT / RxNorm / "