cms-icd 0.1.0__py3-none-any.whl

cms_icd/__init__.py

@@ -0,0 +1,62 @@
+"""Version-aware access to official CMS ICD-10 materials.
+
+The package separates release acquisition from parsing and keeps CM and PCS materials
+independently lazy.
+"""
+
+from .constants import ICD10_PCS_CHARACTERS
+from .exceptions import (
+    AmbiguousReleaseError,
+    DownloadError,
+    ICDKnowledgeBaseError,
+    MaterialUnavailableError,
+    ParseError,
+    ReleaseUnavailableError,
+)
+from .gems import GEMKnowledgeBase, GEMSystemView
+from .knowledge_base import (
+    ICD10CMKnowledgeBase,
+    ICD10KnowledgeBase,
+    ICD10PCSKnowledgeBase,
+)
+from .models import (
+    Code,
+    GEMChoiceList,
+    GEMDirection,
+    GEMEntry,
+    GEMMapping,
+    GEMProvenance,
+    GEMScenario,
+    Guideline,
+    InstructionalNote,
+    Release,
+    Term,
+)
+from .stores import GEMStore
+
+__all__ = [
+    "ICD10_PCS_CHARACTERS",
+    "AmbiguousReleaseError",
+    "Code",
+    "DownloadError",
+    "GEMChoiceList",
+    "GEMDirection",
+    "GEMEntry",
+    "GEMKnowledgeBase",
+    "GEMMapping",
+    "GEMProvenance",
+    "GEMScenario",
+    "GEMStore",
+    "GEMSystemView",
+    "Guideline",
+    "ICD10CMKnowledgeBase",
+    "ICD10KnowledgeBase",
+    "ICD10PCSKnowledgeBase",
+    "ICDKnowledgeBaseError",
+    "InstructionalNote",
+    "MaterialUnavailableError",
+    "ParseError",
+    "Release",
+    "ReleaseUnavailableError",
+    "Term",
+]

cms_icd/constants.py

@@ -0,0 +1,4 @@
+"""Stable constants defined by the ICD code systems."""
+
+# Ordered characters permitted in ICD-10-PCS codes; I and O are omitted.
+ICD10_PCS_CHARACTERS = tuple("0123456789ABCDEFGHJKLMNPQRSTUVWXYZ")

cms_icd/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by :mod:`cms_icd`."""
+
+from __future__ import annotations
+
+
+class ICDKnowledgeBaseError(RuntimeError):
+    """Base exception for expected CMS ICD knowledge-base failures."""
+
+
+class ReleaseUnavailableError(ICDKnowledgeBaseError):
+    """Raised when the requested CMS release cannot be resolved."""
+
+
+class AmbiguousReleaseError(ICDKnowledgeBaseError):
+    """Raised when multiple CMS artifacts match one material selection."""
+
+
+class MaterialUnavailableError(ICDKnowledgeBaseError):
+    """Raised when a release does not provide a requested material."""
+
+
+class DownloadError(ICDKnowledgeBaseError):
+    """Raised when an official CMS artifact cannot be downloaded or validated."""
+
+
+class ParseError(ICDKnowledgeBaseError):
+    """Raised when a CMS material does not match the expected structure."""

cms_icd/gems.py

@@ -0,0 +1,330 @@
+"""Lazy access to official CMS General Equivalence Mappings."""
+
+from __future__ import annotations
+
+from datetime import date
+from itertools import pairwise
+from threading import Lock
+from typing import TYPE_CHECKING, Self
+
+from .models import GEMDirection, GEMProvenance, Release
+from .parsers import parse_gems
+from .sources import CMSProvider, DirectoryProvider, MaterialProvider
+from .stores import GEMStore
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class GEMSystemView:
+    """Lazy bidirectional GEMs for one ICD-10 system (CM or PCS)."""
+
+    def __init__(
+        self,
+        provider: MaterialProvider | None,
+        system: str,
+        *,
+        icd9_to_icd10: GEMStore | None = None,
+        icd10_to_icd9: GEMStore | None = None,
+        correction_providers: tuple[MaterialProvider, ...] = (),
+    ) -> None:
+        if system not in {"cm", "pcs"}:
+            raise ValueError(f"Unsupported GEM system: {system!r}")
+        self._provider = provider
+        self._correction_providers = correction_providers
+        self.system = system
+        self._stores = {
+            GEMDirection.ICD9_TO_ICD10: icd9_to_icd10,
+            GEMDirection.ICD10_TO_ICD9: icd10_to_icd9,
+        }
+        self._locks = {direction: Lock() for direction in GEMDirection}
+
+    @classmethod
+    def from_stores(
+        cls,
+        system: str,
+        *,
+        icd9_to_icd10: GEMStore | None = None,
+        icd10_to_icd9: GEMStore | None = None,
+    ) -> Self:
+        """Construct a view from prebuilt stores for custom sources or tests."""
+        return cls(
+            None,
+            system,
+            icd9_to_icd10=icd9_to_icd10,
+            icd10_to_icd9=icd10_to_icd9,
+        )
+
+    @property
+    def release(self) -> Release | None:
+        """Return release metadata, if this view is provider-backed."""
+        return self._provider.release if self._provider is not None else None
+
+    def _load(self, direction: GEMDirection) -> GEMStore:
+        store = self._stores[direction]
+        if store is None:
+            with self._locks[direction]:
+                store = self._stores[direction]
+                if store is None:
+                    if self._provider is None:
+                        raise RuntimeError(
+                            f"{type(self).__name__} has no provider for unloaded GEMs"
+                        )
+                    store = self._load_provider(self._provider, direction)
+                    if self._correction_providers:
+                        stores = [store]
+                        target_universes = [
+                            set(
+                                self._load_provider(
+                                    self._provider, _opposite(direction)
+                                )
+                            )
+                        ]
+                        for provider in self._correction_providers:
+                            stores.append(self._load_provider(provider, direction))
+                            target_universes.append(
+                                set(self._load_provider(provider, _opposite(direction)))
+                            )
+                        store = _backport_corrections(stores, target_universes)
+                    self._stores[direction] = store
+        return store
+
+    def _load_provider(
+        self, provider: MaterialProvider, direction: GEMDirection
+    ) -> GEMStore:
+        return parse_gems(
+            provider.paths(self.system, "gems"),
+            system=self.system,
+            direction=direction,
+            release=provider.release,
+        )
+
+    @property
+    def icd9_to_icd10(self) -> GEMStore:
+        """Return mappings from ICD-9-CM to ICD-10-CM or ICD-10-PCS."""
+        return self._load(GEMDirection.ICD9_TO_ICD10)
+
+    @property
+    def icd10_to_icd9(self) -> GEMStore:
+        """Return mappings from ICD-10-CM or ICD-10-PCS to ICD-9-CM."""
+        return self._load(GEMDirection.ICD10_TO_ICD9)
+
+    def __repr__(self) -> str:
+        """Return a representation without loading mappings."""
+        loaded = [
+            direction.value
+            for direction, store in self._stores.items()
+            if store is not None
+        ]
+        return (
+            f"GEMSystemView(system={self.system!r}, release={self.release!r}, "
+            f"loaded={loaded!r})"
+        )
+
+
+class GEMKnowledgeBase:
+    """A CMS fiscal-year GEM release with independently lazy CM and PCS views."""
+
+    def __init__(
+        self,
+        provider: MaterialProvider,
+        *,
+        correction_providers: tuple[MaterialProvider, ...] = (),
+    ) -> None:
+        self._provider = provider
+        self._correction_providers = correction_providers
+        self._cm: GEMSystemView | None = None
+        self._pcs: GEMSystemView | None = None
+
+    @classmethod
+    def from_cms(
+        cls,
+        fiscal_year: int,
+        *,
+        cache_dir: str | Path | None = None,
+        offline: bool = False,
+    ) -> Self:
+        """Create a lazy GEM selector for an official CMS fiscal year.
+
+        Args:
+            fiscal_year: Official CMS GEM fiscal year.
+            cache_dir: Persistent artifact cache directory. ``None`` uses the
+                platform default cache directory.
+            offline: Require the catalog and artifacts to already be cached.
+        """
+        release = Release(fiscal_year, date(fiscal_year - 1, 10, 1))
+        return cls(
+            CMSProvider(
+                release,
+                cache_dir=cache_dir,
+                offline=offline,
+            )
+        )
+
+    @classmethod
+    def corrected_from_cms(
+        cls,
+        fiscal_year: int,
+        *,
+        corrections_through_fiscal_year: int = 2018,
+        cache_dir: str | Path | None = None,
+        offline: bool = False,
+    ) -> Self:
+        """Create GEMs using historical vocabulary and later safe corrections.
+
+        Each source remains on the requested fiscal year's vocabulary. Later complete
+        row sets are adopted only until that source encounters an introduced or retired
+        source/target code. Corrections are reviewed through FY2018 by default, the last
+        CMS GEM release.
+
+        Args:
+            fiscal_year: Historical vocabulary fiscal year.
+            corrections_through_fiscal_year: Last GEM release considered for safe
+                corrections.
+            cache_dir: Persistent artifact cache directory shared by all releases.
+                ``None`` uses the platform default cache directory.
+            offline: Require the catalog and artifacts to already be cached.
+        """
+        if corrections_through_fiscal_year < fiscal_year:
+            raise ValueError(
+                "corrections_through_fiscal_year must not precede fiscal_year"
+            )
+
+        def provider(year: int) -> CMSProvider:
+            return CMSProvider(
+                Release(year, date(year - 1, 10, 1)),
+                cache_dir=cache_dir,
+                offline=offline,
+            )
+
+        return cls(
+            provider(fiscal_year),
+            correction_providers=tuple(
+                provider(year)
+                for year in range(fiscal_year + 1, corrections_through_fiscal_year + 1)
+            ),
+        )
+
+    @classmethod
+    def from_directory(
+        cls,
+        directory: str | Path,
+        *,
+        fiscal_year: int,
+    ) -> Self:
+        """Create a knowledge base from locally supplied CMS-format GEM files."""
+        release = Release(fiscal_year, date(fiscal_year - 1, 10, 1))
+        return cls(DirectoryProvider(directory, release))
+
+    @property
+    def release(self) -> Release:
+        """Return the selected CMS GEM release."""
+        return self._provider.release
+
+    @property
+    def cm(self) -> GEMSystemView:
+        """Return the lazy diagnosis GEM view."""
+        if self._cm is None:
+            self._cm = GEMSystemView(
+                self._provider,
+                "cm",
+                correction_providers=self._correction_providers,
+            )
+        return self._cm
+
+    @property
+    def pcs(self) -> GEMSystemView:
+        """Return the lazy procedure GEM view."""
+        if self._pcs is None:
+            self._pcs = GEMSystemView(
+                self._provider,
+                "pcs",
+                correction_providers=self._correction_providers,
+            )
+        return self._pcs
+
+    def __repr__(self) -> str:
+        """Return a representation without acquiring any GEM material."""
+        loaded = [
+            name
+            for name, view in (("cm", self._cm), ("pcs", self._pcs))
+            if view is not None
+        ]
+        corrections_through = (
+            self._correction_providers[-1].release
+            if self._correction_providers
+            else None
+        )
+        return (
+            f"GEMKnowledgeBase(release={self.release!r}, "
+            f"corrections_through={corrections_through!r}, loaded={loaded!r})"
+        )
+
+
+def _opposite(direction: GEMDirection) -> GEMDirection:
+    if direction is GEMDirection.ICD9_TO_ICD10:
+        return GEMDirection.ICD10_TO_ICD9
+    return GEMDirection.ICD9_TO_ICD10
+
+
+def _targets(entries: tuple) -> set[str]:
+    return {entry.target for entry in entries if entry.target is not None}
+
+
+def _backport_corrections(
+    stores: list[GEMStore], target_universes: list[set[str]]
+) -> GEMStore:
+    """Backport correction-only row sets without crossing code lifecycle changes."""
+    if len(stores) != len(target_universes) or not stores:
+        raise ValueError("A target universe is required for every GEM store")
+    base = stores[0]
+    if base.release is None or any(store.release is None for store in stores):
+        raise ValueError("Retrospective correction requires release metadata")
+    base_targets = target_universes[0]
+    values = dict(base.items())
+    selected = dict.fromkeys(base, base.release)
+    blocked: dict[str, Release] = {}
+
+    for index, (old, new) in enumerate(pairwise(stores)):
+        old_universe = target_universes[index]
+        new_universe = target_universes[index + 1]
+        introduced = new_universe - old_universe
+        retired = old_universe - new_universe
+        for source in base:
+            if source in blocked:
+                continue
+            if source not in old or source not in new:
+                blocked[source] = new.release
+                continue
+            old_entries = old[source]
+            new_entries = new[source]
+            if old_entries == new_entries:
+                continue
+            old_targets = _targets(old_entries)
+            new_targets = _targets(new_entries)
+            lifecycle = bool((old_targets | new_targets) & (introduced | retired))
+            historically_compatible = new_targets <= base_targets
+            lineage_matches = values[source] == old_entries
+            if lifecycle or not historically_compatible or not lineage_matches:
+                blocked[source] = new.release
+                continue
+            values[source] = new_entries
+            selected[source] = new.release
+
+    reviewed = stores[-1].release
+    provenance = {
+        source: GEMProvenance(
+            vocabulary_release=base.release,
+            selected_mapping_release=selected[source],
+            reviewed_through_release=reviewed,
+            blocked_by_code_lifecycle_release=blocked.get(source),
+        )
+        for source in base
+    }
+    return GEMStore(
+        values,
+        system=base.system,
+        direction=base.direction,
+        release=base.release,
+        provenance=provenance,
+    )

cms_icd/guidelines.py

@@ -0,0 +1,216 @@
+"""Parsing for official ICD-10 coding-guideline PDFs."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from pypdf import PdfReader
+
+from .exceptions import ParseError
+from .models import Guideline
+from .stores import GuidelineStore
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from pathlib import Path
+
+    from pypdf import PageObject
+    from pypdf.generic import Destination
+
+
+_SECTION = re.compile(r"Section\s+(IV|I{1,3})\b", re.I)
+_SUBSECTION = re.compile(r"^([A-Z])\.\s")
+_NUMBER = re.compile(r"^(\d+)\.\s")
+_PAGE_FOOTER = re.compile(r"^Page\s+\d+\s+of\s+\d+$", re.I)
+_CM_RUNNING_FOOTER = re.compile(
+    r"\s*ICD\s*-\s*10\s*-\s*CM\s+Official\s+Guidelines\s+for\s+Coding\s+and"
+    r"\s+Reporting\s+FY\s+\d{4}\s+Page\s+\d+\s+of\s+\d+\s*",
+    re.I,
+)
+
+
+def _text_position(
+    text_matrix: Sequence[float], user_matrix: Sequence[float]
+) -> tuple[float, float]:
+    """Return text-space translation transformed into page coordinates."""
+    x = text_matrix[4] * user_matrix[0] + text_matrix[5] * user_matrix[2]
+    y = text_matrix[4] * user_matrix[1] + text_matrix[5] * user_matrix[3]
+    return x + user_matrix[4], y + user_matrix[5]
+
+
+def _page_text(page: PageObject) -> str:
+    footer_text: set[str] = set()
+    threshold = float(page.mediabox.height) * 0.08
+
+    def visit_text(
+        text: str,
+        user_matrix: Sequence[float],
+        text_matrix: Sequence[float],
+        _font: object,
+        _font_size: float,
+    ) -> None:
+        _, y = _text_position(text_matrix, user_matrix)
+        item = text.strip()
+        if item and 0 <= y <= threshold and _PAGE_FOOTER.match(item):
+            footer_text.add(item)
+
+    text = page.extract_text(visitor_text=visit_text) or ""
+    text = _CM_RUNNING_FOOTER.sub("", text)
+    for item in footer_text:
+        text = text.replace(item, "", 1)
+    text = re.sub(
+        r"\bICD\s*-\s*10\s*-\s*(CM|PCS)\b",
+        lambda match: f"ICD-10-{match.group(1).upper()}",
+        text,
+        flags=re.I,
+    )
+    text = re.sub(r"(?<=\d)\s+(st|nd|rd|th)\b", r"\1", text)  # codespell:ignore nd
+    text = re.sub(r"\b([A-Z])\s+(?=\d{2}(?:\d|\.))", r"\1", text)
+    # Some CMS fonts place artificial word boundaries inside these words.
+    text = text.replace("Tabular L ist", "Tabular List")  # codespell:ignore ist
+    text = re.sub(r"\bap\s+propriate\b", "appropriate", text)
+    text = re.sub(r"\bW\s+hen\b", "When", text)
+    text = re.sub(r"\bw\s+hen\b", "when", text)
+    return re.sub(r"^(\d+\.)\s*\n\s*", r"\n\1 ", text, flags=re.M).strip()
+
+
+def _outline_entries(
+    document: PdfReader,
+) -> Iterator[tuple[int, str, int]]:
+    def walk(
+        items: Sequence[Destination | list[Destination]], level: int
+    ) -> Iterator[tuple[int, str, int]]:
+        for item in items:
+            if isinstance(item, list):
+                yield from walk(item, level + 1)
+                continue
+            page_number = document.get_destination_page_number(item)
+            if page_number is None:
+                raise ParseError(f"Guideline outline destination has no page: {item!s}")
+            yield level, str(item.title), page_number + 1
+
+    yield from walk(document.outline, 1)
+
+
+def _strip_header(title: str, content: str) -> str:
+    words = [re.escape(word) for word in title.split()]
+    if not words:
+        return content
+    return re.sub(
+        r"^.*?" + r"\s+".join(words), "", content, count=1, flags=re.I | re.S
+    ).strip()
+
+
+def _structured_cm_guidelines(document: PdfReader, path: str | Path) -> GuidelineStore:
+    entries: list[dict[str, object]] = []
+    current_section: str | None = None
+    current_subsection: str | None = None
+    for level, raw_title, page_number in _outline_entries(document):
+        if level == 1 and (match := _SECTION.search(raw_title)):
+            current_section = match.group(1).upper()
+            current_subsection = None
+            title = re.sub(
+                r"Section\s+(?:IV|I{1,3})\.\s*", "", raw_title, count=1, flags=re.I
+            ).strip()
+            entries.append(
+                {
+                    "key": current_section,
+                    "title": title,
+                    "page": page_number,
+                    "level": 1,
+                    "raw_title": raw_title,
+                }
+            )
+        elif level == 2 and current_section and (match := _SUBSECTION.match(raw_title)):
+            current_subsection = f"{current_section}.{match.group(1)}"
+            entries.append(
+                {
+                    "key": current_subsection,
+                    "title": raw_title[match.end() :].strip(),
+                    "page": page_number,
+                    "level": 2,
+                    "raw_title": raw_title,
+                }
+            )
+        elif level == 3 and current_subsection and (match := _NUMBER.match(raw_title)):
+            entries.append(
+                {
+                    "key": f"{current_subsection}.{match.group(1)}",
+                    "title": raw_title[match.end() :].strip(),
+                    "page": page_number,
+                    "level": 3,
+                    "raw_title": raw_title,
+                }
+            )
+    if not entries:
+        raise ParseError(f"No structured CM guideline outline found in {path}")
+    for index, entry in enumerate(entries):
+        entry["leaf"] = index == len(entries) - 1 or int(
+            entries[index + 1]["level"]
+        ) <= int(entry["level"])
+    first_page = int(entries[0]["page"])
+    full_text = "\n".join(
+        _page_text(document.pages[number])
+        for number in range(first_page - 1, len(document.pages))
+    )
+    search_from = 0
+    for entry in entries:
+        words = str(entry["raw_title"]).split()[:8]
+        heading = "".join(words)
+        pattern = r"\s*".join(re.escape(character) for character in heading)
+        match = re.search(pattern, full_text[search_from:], re.I | re.M)
+        entry["position"] = search_from + match.start() if match else None
+        if match:
+            search_from = int(entry["position"])
+    titles = {str(entry["key"]): str(entry["title"]) for entry in entries}
+    guidelines: dict[str, Guideline] = {}
+    preambles: dict[str, str] = {}
+    for index, entry in enumerate(entries):
+        position = entry["position"]
+        if position is None:
+            continue
+        later = [item for item in entries[index + 1 :] if item["position"] is not None]
+        end = int(later[0]["position"]) if later else len(full_text)
+        content = full_text[int(position) : end].strip()
+        key = str(entry["key"])
+        if entry["leaf"]:
+            guidelines[key] = Guideline(
+                id=key.replace(".", "_"),
+                number=key,
+                title=str(entry["title"]),
+                content=content,
+            )
+        else:
+            body = _strip_header(str(entry["title"]), content)
+            if body:
+                preambles[key] = body
+    return GuidelineStore(guidelines, titles, preambles)
+
+
+def parse_guidelines(path: str | Path, *, system: str) -> GuidelineStore:
+    """Parse an official coding-guidelines PDF.
+
+    CM PDFs receive dotted section keys. PCS PDFs, whose outlines vary more by release,
+    are exposed as one deterministic ``document`` guideline.
+    """
+    if system not in {"cm", "pcs"}:
+        raise ValueError(f"Unsupported guideline system: {system!r}")
+    try:
+        document = PdfReader(path)
+    except Exception as exc:
+        raise ParseError(
+            f"Unable to open ICD-10-{system.upper()} guidelines {path}: {exc}"
+        ) from exc
+    try:
+        if system == "pcs":
+            content = "\n".join(_page_text(page) for page in document.pages)
+            guideline = Guideline(
+                "document", "document", "Official Guidelines", content
+            )
+            return GuidelineStore(
+                {"document": guideline}, {"document": guideline.title}
+            )
+        return _structured_cm_guidelines(document, path)
+    finally:
+        document.close()