carebundle 0.1.0__py3-none-any.whl

carebundle/__init__.py

@@ -0,0 +1,37 @@
+"""Clinically coherent synthetic FHIR(R) R4 test data.
+
+FHIR(R) is the registered trademark of HL7 and is used with the permission of HL7.
+"""
+
+from __future__ import annotations
+
+from carebundle.calibration.custom import Quartiles, calibrate_profile, forget_profile
+from carebundle.core.bundle import to_json
+from carebundle.generate import (
+    generate_bundle,
+    generate_cohort,
+    generate_draw,
+    generate_patient,
+)
+from carebundle.history import generate_history
+from carebundle.imperfection import Defect, Imperfection, inject_defects
+from carebundle.profiles.library import PROFILES
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PROFILES",
+    "Defect",
+    "Imperfection",
+    "Quartiles",
+    "__version__",
+    "calibrate_profile",
+    "forget_profile",
+    "generate_bundle",
+    "generate_cohort",
+    "generate_draw",
+    "generate_history",
+    "generate_patient",
+    "inject_defects",
+    "to_json",
+]

carebundle/benchmark/__init__.py

@@ -0,0 +1,23 @@
+"""Clinical quality measures computed over generated output.
+
+This exists to answer one question with evidence rather than assertion: does the
+generated population reproduce the quality-measure rates a real population produces?
+
+The measures are computed from the emitted FHIR, not from the internal draw. That is
+deliberate — a measure engine reading `ProfileDraw` would be marking its own homework,
+and the thing users receive is the bundle.
+"""
+
+from carebundle.benchmark.cqm import (
+    MEASURES,
+    MeasureResult,
+    controlling_high_blood_pressure,
+    run_measure,
+)
+
+__all__ = [
+    "MEASURES",
+    "MeasureResult",
+    "controlling_high_blood_pressure",
+    "run_measure",
+]

carebundle/benchmark/cqm.py

@@ -0,0 +1,205 @@
+"""CMS/HEDIS clinical quality measures, computed from generated bundles.
+
+Why this module exists
+----------------------
+Synthea's published validation (Chen J, Chun D, Patel M, Chiang E, James J, "The
+validity of synthetic clinical data: a validation study of a leading synthetic data
+generator (Synthea) using clinical quality measures", BMC Med Inform Decis Mak 2019)
+measured Synthea against four CMS quality measures and found it tracks reality on the
+*process* measure and collapses on every *outcome* measure:
+
+    Colorectal cancer screening   68.7%   vs 69.8% US   (process, close)
+    COPD 30-day mortality          0.7%   vs  8.0% US   (outcome)
+    Hip/knee complications         0.0%   vs  2.8% US   (outcome)
+    Controlling high blood pressure 0.0%  vs 69.7% US   (outcome)
+
+The authors name the mechanism: synthetic generators "do not currently model for
+deviations in care and the potential outcomes that may result from care deviations."
+That is a statement about architecture. A state machine over care pathways decides
+*whether a patient was screened*; it has no representation of what the blood pressure
+did afterwards, so a control rate cannot emerge from it.
+
+This project models clinical state directly, which is the machinery an outcome measure
+needs, so this is the ground on which it can be compared and win.
+
+Reading the numbers honestly
+----------------------------
+Denominators differ between sources and conflating them produces a wrong answer that
+looks right:
+
+  * NHANES reports control over *all* adults with hypertension, including the unaware
+    and untreated, and since the 2017 ACC/AHA guideline it uses a **<130/80** threshold.
+    The August 2021-August 2023 figure is 20.7%.
+  * HEDIS/CMS `Controlling High Blood Pressure` (CBP) uses **<140/90** over a much
+    narrower denominator: members aged 18-85 with a *diagnosed* hypertension and an
+    outpatient encounter. That is the ~70% figure, and it is the one the Synthea
+    validation study used.
+
+These profiles emit a coded hypertension diagnosis and an encounter, so they are the
+HEDIS denominator, and <140/90 is the applicable threshold. Using NHANES's 20.7%
+as the target here would be comparing against a different population and a different
+cut-off.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from carebundle.terminology import codes, systems
+
+# LOINC panel and component codes for an office blood pressure.
+_BP_PANEL = "85354-9"
+_SYSTOLIC = codes.BP_SYSTOLIC.code
+_DIASTOLIC = codes.BP_DIASTOLIC.code
+
+# NCQA HEDIS CBP: adults 18-85 with diagnosed hypertension, controlled at <140/90.
+CBP_SYSTOLIC_THRESHOLD = 140.0
+CBP_DIASTOLIC_THRESHOLD = 90.0
+CBP_MIN_AGE = 18
+CBP_MAX_AGE = 85
+
+HYPERTENSION_CODES = frozenset({codes.ESSENTIAL_HYPERTENSION.code})
+
+
+@dataclass(frozen=True)
+class MeasureResult:
+    """One measure evaluated over a population of bundles."""
+
+    measure: str
+    numerator: int
+    denominator: int
+
+    @property
+    def rate(self) -> float:
+        """Proportion meeting the measure, or 0.0 when nobody qualifies.
+
+        A zero denominator is reported as a zero rate *and* a zero denominator, so a
+        measure nobody qualified for cannot be mistaken for a measure everybody failed.
+        That distinction is the whole difference between "not modelled" and "0%", and
+        it is the row most worth being honest about when comparing against Synthea.
+        """
+        if self.denominator == 0:
+            return 0.0
+        return self.numerator / self.denominator
+
+
+def _resources(bundle: dict[str, Any], resource_type: str) -> list[dict[str, Any]]:
+    return [
+        entry["resource"]
+        for entry in bundle.get("entry", [])
+        if entry.get("resource", {}).get("resourceType") == resource_type
+    ]
+
+
+def _has_hypertension(bundle: dict[str, Any]) -> bool:
+    for condition in _resources(bundle, "Condition"):
+        for coding in condition.get("code", {}).get("coding", []):
+            if (
+                coding.get("system") == systems.ICD10CM
+                and coding.get("code") in HYPERTENSION_CODES
+            ):
+                return True
+    return False
+
+
+def _blood_pressures(bundle: dict[str, Any]) -> list[tuple[float, float]]:
+    """Every (systolic, diastolic) pair recorded in the bundle.
+
+    Reads the panel's components rather than trusting ordering, because a BP panel is
+    a single Observation with two components and their order is not guaranteed.
+    """
+    readings: list[tuple[float, float]] = []
+    for observation in _resources(bundle, "Observation"):
+        panel = {
+            coding.get("code")
+            for coding in observation.get("code", {}).get("coding", [])
+        }
+        if _BP_PANEL not in panel:
+            continue
+        systolic = diastolic = None
+        for component in observation.get("component", []):
+            found = {
+                coding.get("code")
+                for coding in component.get("code", {}).get("coding", [])
+            }
+            value = component.get("valueQuantity", {}).get("value")
+            if value is None:
+                continue
+            if _SYSTOLIC in found:
+                systolic = float(value)
+            elif _DIASTOLIC in found:
+                diastolic = float(value)
+        if systolic is not None and diastolic is not None:
+            readings.append((systolic, diastolic))
+    return readings
+
+
+def _age_years(bundle: dict[str, Any]) -> float | None:
+    """Age at the encounter, from birthDate and the encounter period.
+
+    Returns None when either is missing rather than guessing — an unknown age must not
+    silently enter or leave a measure denominator.
+    """
+    patients = _resources(bundle, "Patient")
+    encounters = _resources(bundle, "Encounter")
+    if not patients or not encounters:
+        return None
+    birth = patients[0].get("birthDate")
+    start = encounters[0].get("period", {}).get("start")
+    if not birth or not start:
+        return None
+    birth_year, birth_month, birth_day = (int(p) for p in birth.split("-"))
+    enc_year, enc_month, enc_day = (int(p) for p in start[:10].split("-"))
+    years = enc_year - birth_year
+    if (enc_month, enc_day) < (birth_month, birth_day):
+        years -= 1
+    return float(years)
+
+
+def controlling_high_blood_pressure(bundle: dict[str, Any]) -> tuple[bool, bool]:
+    """HEDIS CBP for one bundle: (in denominator, in numerator).
+
+    Denominator: age 18-85 with a coded hypertension diagnosis and a recorded BP.
+    Numerator:   most recent BP below 140/90. Both components must be controlled;
+                 an isolated diastolic elevation fails the measure.
+    """
+    age = _age_years(bundle)
+    if age is None or not (CBP_MIN_AGE <= age <= CBP_MAX_AGE):
+        return False, False
+    if not _has_hypertension(bundle):
+        return False, False
+
+    readings = _blood_pressures(bundle)
+    if not readings:
+        return False, False
+
+    systolic, diastolic = readings[-1]
+    controlled = (
+        systolic < CBP_SYSTOLIC_THRESHOLD and diastolic < CBP_DIASTOLIC_THRESHOLD
+    )
+    return True, controlled
+
+
+MEASURES: dict[str, Callable[[dict[str, Any]], tuple[bool, bool]]] = {
+    "controlling_high_blood_pressure": controlling_high_blood_pressure,
+}
+
+
+def run_measure(
+    measure: str, bundles: Iterable[dict[str, Any]] | Sequence[dict[str, Any]]
+) -> MeasureResult:
+    """Evaluate a named measure across a population of decoded bundles."""
+    if measure not in MEASURES:
+        raise KeyError(f"unknown measure {measure!r}; known: {sorted(MEASURES)}")
+    evaluate = MEASURES[measure]
+
+    numerator = denominator = 0
+    for bundle in bundles:
+        in_denominator, in_numerator = evaluate(bundle)
+        denominator += in_denominator
+        numerator += in_numerator
+    return MeasureResult(
+        measure=measure, numerator=numerator, denominator=denominator
+    )

carebundle/builders/clinical.py

@@ -0,0 +1,188 @@
+"""Condition, Observation and AllergyIntolerance builders."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from carebundle.core import uscore
+from carebundle.core.safety import htest_meta, synthetic_narrative
+from carebundle.models.r4 import (
+    AllergyIntolerance,
+    CodeableConcept,
+    Condition,
+    Observation,
+    ObservationComponent,
+    Quantity,
+    Reference,
+)
+from carebundle.terminology import codes
+from carebundle.terminology.systems import UCUM
+
+
+def _ref(urn: str) -> Reference:
+    return Reference(reference=urn)
+
+
+def build_condition(
+    *,
+    resource_id: str,
+    code: codes.Code,
+    subject_urn: str,
+    onset_date: str,
+    encounter_urn: str | None = None,
+) -> Condition:
+    """A US Core problem-list Condition.
+
+    Coded with ICD-10-CM. US Core's Condition code binding is extensible and admits
+    ICD-10-CM alongside SNOMED, which is what makes the no-SNOMED decision
+    (build doc Section 6) survivable here.
+    """
+    return Condition(
+        id=resource_id,
+        meta=htest_meta(uscore.CONDITION_PROBLEMS),
+        text=synthetic_narrative(f"Condition: {code.display} (synthetic)."),
+        clinicalStatus=codes.CLINICAL_ACTIVE.concept(),
+        verificationStatus=codes.VERIFICATION_CONFIRMED.concept(),
+        category=[codes.CATEGORY_PROBLEM_LIST.concept()],
+        code=code.concept(),
+        subject=_ref(subject_urn),
+        encounter=_ref(encounter_urn) if encounter_urn else None,
+        onsetDateTime=onset_date,
+    )
+
+
+def build_lab_observation(
+    *,
+    resource_id: str,
+    code: codes.Code,
+    subject_urn: str,
+    effective: str,
+    value: Decimal,
+    unit: tuple[str, str],
+    encounter_urn: str | None = None,
+    performer_urn: str | None = None,
+) -> Observation:
+    """A US Core laboratory result.
+
+    `unit` is (human display, UCUM code) — they differ often enough (mmHg vs mm[Hg])
+    that conflating them silently produces non-conformant output.
+    """
+    display_unit, ucum_code = unit
+    return Observation(
+        id=resource_id,
+        meta=htest_meta(uscore.OBSERVATION_LAB),
+        text=synthetic_narrative(f"{code.display}: {value} {display_unit} (synthetic)."),
+        status="final",
+        category=[codes.CATEGORY_LABORATORY.concept()],
+        code=code.concept(),
+        subject=_ref(subject_urn),
+        encounter=_ref(encounter_urn) if encounter_urn else None,
+        effectiveDateTime=effective,
+        performer=[_ref(performer_urn)] if performer_urn else None,
+        valueQuantity=Quantity(
+            value=value, unit=display_unit, system=UCUM, code=ucum_code
+        ),
+    )
+
+
+def build_blood_pressure(
+    *,
+    resource_id: str,
+    subject_urn: str,
+    effective: str,
+    systolic: Decimal,
+    diastolic: Decimal,
+    encounter_urn: str | None = None,
+    performer_urn: str | None = None,
+) -> Observation:
+    """A US Core blood pressure: one Observation with two components, never two
+    independent Observations. The panel code plus components is the profile's shape."""
+    display_unit, ucum_code = codes.UNIT_MMHG
+
+    def _component(code: codes.Code, value: Decimal) -> ObservationComponent:
+        return ObservationComponent(
+            code=code.concept(),
+            valueQuantity=Quantity(
+                value=value, unit=display_unit, system=UCUM, code=ucum_code
+            ),
+        )
+
+    return Observation(
+        id=resource_id,
+        meta=htest_meta(uscore.BLOOD_PRESSURE),
+        text=synthetic_narrative(
+            f"Blood pressure {systolic}/{diastolic} {display_unit} (synthetic)."
+        ),
+        status="final",
+        category=[codes.CATEGORY_VITAL_SIGNS.concept()],
+        code=codes.BP_PANEL.concept(),
+        subject=_ref(subject_urn),
+        encounter=_ref(encounter_urn) if encounter_urn else None,
+        effectiveDateTime=effective,
+        performer=[_ref(performer_urn)] if performer_urn else None,
+        component=[
+            _component(codes.BP_SYSTOLIC, systolic),
+            _component(codes.BP_DIASTOLIC, diastolic),
+        ],
+    )
+
+
+def build_vital_observation(
+    *,
+    resource_id: str,
+    code: codes.Code,
+    profile: str,
+    subject_urn: str,
+    effective: str,
+    value: Decimal,
+    unit: tuple[str, str],
+    encounter_urn: str | None = None,
+    performer_urn: str | None = None,
+    additional_codes: tuple[codes.Code, ...] = (),
+) -> Observation:
+    """A US Core vital-sign Observation (height, weight, BMI).
+
+    Same shape as a lab result but categorised vital-signs and asserting the specific
+    US Core vitals profile, whose value[x] must be a UCUM Quantity.
+    """
+    display_unit, ucum_code = unit
+    # Some US Core vitals profiles slice Observation.code and require more than one
+    # coding — pulse oximetry needs both the method code and the base oxygensat code.
+    concept = CodeableConcept(
+        coding=[code.coding(), *(extra.coding() for extra in additional_codes)],
+        text=code.display,
+    )
+    return Observation(
+        id=resource_id,
+        meta=htest_meta(profile),
+        text=synthetic_narrative(f"{code.display}: {value} {display_unit} (synthetic)."),
+        status="final",
+        category=[codes.CATEGORY_VITAL_SIGNS.concept()],
+        code=concept,
+        subject=_ref(subject_urn),
+        encounter=_ref(encounter_urn) if encounter_urn else None,
+        effectiveDateTime=effective,
+        performer=[_ref(performer_urn)] if performer_urn else None,
+        valueQuantity=Quantity(
+            value=value, unit=display_unit, system=UCUM, code=ucum_code
+        ),
+    )
+
+
+def build_allergy_intolerance(
+    *,
+    resource_id: str,
+    code: CodeableConcept,
+    patient_urn: str,
+    recorded_date: str,
+) -> AllergyIntolerance:
+    return AllergyIntolerance(
+        id=resource_id,
+        meta=htest_meta(uscore.ALLERGY_INTOLERANCE),
+        text=synthetic_narrative("Allergy record (synthetic)."),
+        clinicalStatus=codes.ALLERGY_ACTIVE.concept(),
+        verificationStatus=codes.ALLERGY_CONFIRMED.concept(),
+        code=code,
+        patient=_ref(patient_urn),
+        recordedDate=recorded_date,
+    )

carebundle/builders/orders.py

@@ -0,0 +1,104 @@
+"""Encounter, MedicationRequest and DiagnosticReport builders."""
+
+from __future__ import annotations
+
+from carebundle.core import uscore
+from carebundle.core.safety import htest_meta, synthetic_narrative
+from carebundle.models.r4 import (
+    DiagnosticReport,
+    Encounter,
+    MedicationRequest,
+    Period,
+    Reference,
+)
+from carebundle.terminology import codes
+
+
+def _ref(urn: str) -> Reference:
+    return Reference(reference=urn)
+
+
+def build_encounter(
+    *,
+    resource_id: str,
+    subject_urn: str,
+    start: str,
+    end: str,
+    type_concept,
+) -> Encounter:
+    """A US Core ambulatory Encounter.
+
+    `type_concept` is injected because US Core's Encounter.type value set draws on
+    CPT-4 and SNOMED CT — neither of which this project can ship (build doc Section 6).
+    Making it a caller-supplied argument keeps that constraint visible instead of
+    burying an unlicensed code in the library.
+    """
+    return Encounter(
+        id=resource_id,
+        meta=htest_meta(uscore.ENCOUNTER),
+        text=synthetic_narrative("Ambulatory encounter (synthetic)."),
+        status="finished",
+        class_=codes.ENCOUNTER_AMBULATORY.coding(),
+        type=[type_concept],
+        subject=_ref(subject_urn),
+        period=Period(start=start, end=end),
+    )
+
+
+def build_medication_request(
+    *,
+    resource_id: str,
+    medication: codes.Code,
+    subject_urn: str,
+    requester_urn: str,
+    authored_on: str,
+    encounter_urn: str | None = None,
+) -> MedicationRequest:
+    """A US Core MedicationRequest.
+
+    `requester_urn` is mandatory rather than optional: US Core requires a requester,
+    so allowing it to default to None would let non-conformant output be constructed.
+    """
+    return MedicationRequest(
+        id=resource_id,
+        meta=htest_meta(uscore.MEDICATION_REQUEST),
+        text=synthetic_narrative(f"Prescription: {medication.display} (synthetic)."),
+        status="active",
+        intent="order",
+        medicationCodeableConcept=medication.concept(),
+        subject=_ref(subject_urn),
+        encounter=_ref(encounter_urn) if encounter_urn else None,
+        authoredOn=authored_on,
+        requester=_ref(requester_urn),
+    )
+
+
+def build_diagnostic_report(
+    *,
+    resource_id: str,
+    code: codes.Code,
+    subject_urn: str,
+    effective: str,
+    issued: str,
+    result_urns: list[str],
+    performer_urn: str | None = None,
+) -> DiagnosticReport:
+    """A US Core laboratory DiagnosticReport tying together its member Observations.
+
+    `code` is the panel's own LOINC code. The generic "Laboratory report" document
+    code (11502-2) is excluded from US Core's lab test value set for good reason —
+    it describes the document, not what was measured.
+    """
+    return DiagnosticReport(
+        id=resource_id,
+        meta=htest_meta(uscore.DIAGNOSTIC_REPORT_LAB),
+        text=synthetic_narrative("Laboratory report (synthetic)."),
+        status="final",
+        category=[codes.SERVICE_SECTION_LAB.concept()],
+        code=code.concept(),
+        subject=_ref(subject_urn),
+        effectiveDateTime=effective,
+        issued=issued,
+        performer=[_ref(performer_urn)] if performer_urn else None,
+        result=[_ref(urn) for urn in result_urns],
+    )

carebundle/builders/people.py

@@ -0,0 +1,64 @@
+"""Patient and Practitioner builders."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from carebundle.core import uscore
+from carebundle.core.safety import (
+    fictional_name,
+    htest_meta,
+    synthetic_mrn,
+    synthetic_narrative,
+    synthetic_npi,
+)
+from carebundle.models.r4 import Patient, Practitioner
+
+SEX_TO_FHIR_GENDER = {"F": "female", "M": "male"}
+
+
+def build_patient(
+    *,
+    resource_id: str,
+    sex: str,
+    birth_date: date,
+    family_index: int,
+    given_index: int,
+) -> Patient:
+    """A US Core Patient. Callers supply every varying input, keeping this pure."""
+    if sex not in SEX_TO_FHIR_GENDER:
+        raise ValueError(f"sex must be one of {sorted(SEX_TO_FHIR_GENDER)}, got {sex!r}")
+
+    name = fictional_name(family_index=family_index, given_index=given_index)
+    gender = SEX_TO_FHIR_GENDER[sex]
+
+    return Patient(
+        id=resource_id,
+        meta=htest_meta(uscore.PATIENT),
+        text=synthetic_narrative(
+            f"{name.given[0]} {name.family}, {gender}, born {birth_date.isoformat()}."
+        ),
+        identifier=[synthetic_mrn(resource_id[:8].upper())],
+        name=[name],
+        gender=gender,
+        birthDate=birth_date.isoformat(),
+    )
+
+
+def build_practitioner(
+    *, resource_id: str, family_index: int, given_index: int
+) -> Practitioner:
+    """A US Core Practitioner.
+
+    Exists because US Core requires MedicationRequest.requester — see the Phase 1
+    notes in the build doc. Identifiers use the synthetic urn:uuid system rather than
+    the real NPI namespace: a checksum-valid NPI could collide with a real clinician.
+    """
+    name = fictional_name(family_index=family_index, given_index=given_index)
+    return Practitioner(
+        id=resource_id,
+        meta=htest_meta(uscore.PRACTITIONER),
+        text=synthetic_narrative(f"Dr {name.given[0]} {name.family} (synthetic)."),
+        identifier=[synthetic_npi(resource_id[:10].upper())],
+        name=[name],
+    )