cohort-diff 0.1.0__py3-none-any.whl

cohort_diff/__init__.py

@@ -0,0 +1,20 @@
+"""cohort-diff: how different are "the same" EHR cohorts?"""
+
+from cohort_diff.compare import bootstrap_pairs, describe, jaccard, overlap_table
+from cohort_diff.engine import connect, run
+from cohort_diff.registry import Definition, builtin, load
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Definition",
+    "__version__",
+    "bootstrap_pairs",
+    "builtin",
+    "connect",
+    "describe",
+    "jaccard",
+    "load",
+    "overlap_table",
+    "run",
+]

cohort_diff/cli.py

@@ -0,0 +1,104 @@
+"""Command-line interface: ``cohort-diff <command> --help``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from cohort_diff import compare, engine, registry
+
+
+def _list(args: argparse.Namespace) -> None:
+    for d in registry.builtin().values():
+        if args.condition and d.condition != args.condition:
+            continue
+        print(f"{d.name:<16} {d.condition:<12} {d.description}")
+
+
+def _run(args: argparse.Namespace) -> None:
+    con = engine.connect(args.data)
+    ids = sorted(engine.run(con, registry.load(args.definition)))
+    out = "\n".join(["hadm_id", *map(str, ids)]) + "\n"
+    if args.out:
+        Path(args.out).write_text(out)
+        print(f"{len(ids)} admissions -> {args.out}")
+    else:
+        sys.stdout.write(out)
+
+
+def _compare(args: argparse.Namespace) -> None:
+    defs = [registry.load(n) for n in args.definitions]
+    if args.condition:
+        defs = [d for d in registry.builtin().values() if d.condition == args.condition]
+    if len(defs) < 2:
+        raise ValueError("compare needs at least two definitions")
+    con = engine.connect(args.data)
+    cohorts = {d.name: engine.run(con, d) for d in defs}
+    admissions = engine.admissions_frame(con)
+    uncertainty = (
+        compare.bootstrap_pairs(cohorts, admissions, n_boot=args.bootstrap, seed=args.seed)
+        if args.bootstrap > 0
+        else None
+    )
+    report = compare.to_markdown(
+        compare.overlap_table(cohorts),
+        compare.describe(cohorts, admissions),
+        title=f"cohort-diff: {', '.join(cohorts)}",
+        uncertainty=uncertainty,
+    )
+    if args.out:
+        Path(args.out).write_text(report)
+    print(report)
+
+
+def _synth(args: argparse.Namespace) -> None:
+    from cohort_diff.synth import SynthConfig, generate
+
+    hosp = Path(args.out) / "hosp"
+    hosp.mkdir(parents=True, exist_ok=True)
+    for name, frame in generate(SynthConfig(n_patients=args.patients, seed=args.seed)).items():
+        frame.to_csv(hosp / f"{name}.csv.gz", index=False)
+    print(f"wrote synthetic MIMIC-shaped tables to {hosp} (synthetic data, not real patients)")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cohort-diff", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("list", help="show built-in definitions")
+    p.add_argument("--condition")
+    p.set_defaults(func=_list)
+
+    p = sub.add_parser("run", help="admissions meeting one definition")
+    p.add_argument("definition", help="built-in name or path to a .sql file")
+    p.add_argument("--data", required=True)
+    p.add_argument("--out")
+    p.set_defaults(func=_run)
+
+    p = sub.add_parser("compare", help="overlap and downstream differences between definitions")
+    p.add_argument("definitions", nargs="*", help="two or more names or .sql paths")
+    p.add_argument("--condition", help="compare every built-in definition of this condition")
+    p.add_argument("--data", required=True)
+    p.add_argument("--out", help="write the markdown report here")
+    p.add_argument("--bootstrap", type=int, default=1000, help="resamples (0 = skip)")
+    p.add_argument("--seed", type=int, default=0)
+    p.set_defaults(func=_compare)
+
+    p = sub.add_parser("synth", help="write synthetic MIMIC-shaped tables")
+    p.add_argument("--out", required=True)
+    p.add_argument("--patients", type=int, default=2000)
+    p.add_argument("--seed", type=int, default=0)
+    p.set_defaults(func=_synth)
+
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except (FileNotFoundError, KeyError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cohort_diff/compare.py

@@ -0,0 +1,184 @@
+"""Compare cohorts: overlap, who is in them, and how a downstream result moves.
+
+The downstream result is deliberately simple and common in papers: the odds
+ratio between cohort membership and in-hospital mortality. If that number
+changes a lot between definitions of "the same" condition, so would the
+conclusions of any study built on it.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from itertools import combinations
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class OddsRatio:
+    estimate: float
+    low: float
+    high: float
+
+
+def jaccard(a: set[int], b: set[int]) -> float:
+    """Size of the intersection over size of the union; 1.0 when both are empty."""
+    union = a | b
+    return len(a & b) / len(union) if union else 1.0
+
+
+def overlap_table(cohorts: dict[str, set[int]]) -> pd.DataFrame:
+    """One row per pair of definitions."""
+    rows = []
+    for (na, a), (nb, b) in combinations(cohorts.items(), 2):
+        rows.append(
+            {
+                "a": na,
+                "b": nb,
+                "n_a": len(a),
+                "n_b": len(b),
+                "both": len(a & b),
+                "only_a": len(a - b),
+                "only_b": len(b - a),
+                "jaccard": round(jaccard(a, b), 3),
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def odds_ratio(exposed: np.ndarray, outcome: np.ndarray) -> OddsRatio:
+    """Woolf (log) 95% interval, with a 0.5 continuity correction if any cell is 0."""
+    e, y = exposed.astype(bool), outcome.astype(bool)
+    cells = np.array([(e & y).sum(), (e & ~y).sum(), (~e & y).sum(), (~e & ~y).sum()], dtype=float)
+    if (cells == 0).any():
+        cells = cells + 0.5
+    a, b, c, d = cells
+    log_or = math.log((a * d) / (b * c))
+    se = math.sqrt(1 / a + 1 / b + 1 / c + 1 / d)
+    return OddsRatio(math.exp(log_or), math.exp(log_or - 1.96 * se), math.exp(log_or + 1.96 * se))
+
+
+def _weighted_or(weights: np.ndarray, exposed: np.ndarray, outcome: np.ndarray) -> float:
+    """Odds ratio from a 2x2 table of summed weights (Haldane 0.5 if any cell is 0)."""
+    cells = np.array(
+        [
+            weights @ (exposed & outcome),
+            weights @ (exposed & ~outcome),
+            weights @ (~exposed & outcome),
+            weights @ (~exposed & ~outcome),
+        ],
+        dtype=float,
+    )
+    if (cells == 0).any():
+        cells = cells + 0.5
+    a, b, c, d = cells
+    return float((a * d) / (b * c))
+
+
+def bootstrap_pairs(
+    cohorts: dict[str, set[int]],
+    admissions: pd.DataFrame,
+    n_boot: int = 1000,
+    seed: int = 0,
+) -> pd.DataFrame:
+    """95% percentile intervals, per pair of definitions, for the Jaccard index and
+    for the ratio of their mortality odds ratios (OR of a / OR of b).
+
+    Patients are resampled, not admissions: one patient's admissions are not
+    independent. A patient drawn k times contributes each of their admissions k times.
+    A ratio of ORs whose interval excludes 1 means the two definitions give
+    different answers to "is this condition associated with mortality, and how much".
+    """
+    patients, patient_idx = np.unique(admissions["subject_id"].to_numpy(), return_inverse=True)
+    n_patients = len(patients)
+    died = admissions["hospital_expire_flag"].to_numpy().astype(bool)
+    member = {n: admissions["hadm_id"].isin(ids).to_numpy() for n, ids in cohorts.items()}
+    pairs = list(combinations(member, 2))
+    jac = np.empty((len(pairs), n_boot))
+    ratio = np.empty((len(pairs), n_boot))
+    rng = np.random.default_rng(seed)
+    for r in range(n_boot):
+        drawn = np.bincount(rng.integers(0, n_patients, n_patients), minlength=n_patients)
+        weights = drawn[patient_idx].astype(float)
+        for k, (na, nb) in enumerate(pairs):
+            a, b = member[na], member[nb]
+            union = weights @ (a | b)
+            jac[k, r] = (weights @ (a & b)) / union if union > 0 else 1.0
+            ratio[k, r] = _weighted_or(weights, a, died) / _weighted_or(weights, b, died)
+    rows = []
+    for k, (na, nb) in enumerate(pairs):
+        a, b = member[na], member[nb]
+        point = odds_ratio(a, died).estimate / odds_ratio(b, died).estimate
+        j_low, j_high = np.percentile(jac[k], [2.5, 97.5])
+        r_low, r_high = np.percentile(ratio[k], [2.5, 97.5])
+        rows.append(
+            {
+                "a": na,
+                "b": nb,
+                "jaccard": round(jaccard(cohorts[na], cohorts[nb]), 3),
+                "jaccard_low": round(float(j_low), 3),
+                "jaccard_high": round(float(j_high), 3),
+                "or_ratio": round(point, 2),
+                "or_ratio_low": round(float(r_low), 2),
+                "or_ratio_high": round(float(r_high), 2),
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def describe(cohorts: dict[str, set[int]], admissions: pd.DataFrame) -> pd.DataFrame:
+    """Size, prevalence, demographics and the mortality odds ratio per definition."""
+    rows = []
+    n_total = len(admissions)
+    for name, ids in cohorts.items():
+        member = admissions["hadm_id"].isin(ids).to_numpy()
+        sub = admissions[member]
+        ratio = odds_ratio(member, admissions["hospital_expire_flag"].to_numpy())
+        rows.append(
+            {
+                "definition": name,
+                "n": int(member.sum()),
+                "prevalence": round(member.mean(), 4) if n_total else float("nan"),
+                "age_mean": round(float(sub["age"].mean()), 1) if len(sub) else float("nan"),
+                "female_pct": round(float((sub["gender"] == "F").mean() * 100), 1)
+                if len(sub)
+                else float("nan"),
+                "mortality_pct": round(float(sub["hospital_expire_flag"].mean() * 100), 1)
+                if len(sub)
+                else float("nan"),
+                "mortality_or": round(ratio.estimate, 2),
+                "or_low": round(ratio.low, 2),
+                "or_high": round(ratio.high, 2),
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def to_markdown(
+    overlap: pd.DataFrame,
+    description: pd.DataFrame,
+    title: str,
+    uncertainty: pd.DataFrame | None = None,
+) -> str:
+    def table(frame: pd.DataFrame) -> str:
+        header = "| " + " | ".join(frame.columns) + " |"
+        sep = "| " + " | ".join("---" for _ in frame.columns) + " |"
+        body = [
+            "| " + " | ".join(str(v) for v in row) + " |" for row in frame.itertuples(index=False)
+        ]
+        return "\n".join([header, sep, *body])
+
+    text = (
+        f"# {title}\n\n## Cohorts\n\n{table(description)}\n\n"
+        f"## Pairwise overlap\n\n{table(overlap)}\n\n"
+        "Odds ratios: in-hospital mortality for members vs non-members, Woolf 95% CI.\n"
+    )
+    if uncertainty is not None:
+        text += (
+            f"\n## Uncertainty (patient-level bootstrap)\n\n{table(uncertainty)}\n\n"
+            "95% percentile intervals. or_ratio = mortality OR of a / OR of b; "
+            "an interval excluding 1 means the definitions disagree on the association.\n"
+        )
+    return text

cohort_diff/definitions/aki_icd.sql

@@ -0,0 +1,8 @@
+-- name: aki_icd
+-- condition: aki
+-- description: Any AKI diagnosis code on the admission (ICD-10 N17.*, ICD-9 584.*).
+-- reference: Common administrative-data definition; codes are assigned after discharge.
+SELECT DISTINCT hadm_id
+FROM diagnoses_icd
+WHERE (icd_version = 10 AND icd_code LIKE 'N17%')
+   OR (icd_version = 9 AND icd_code LIKE '584%')

cohort_diff/definitions/aki_kdigo_48h.sql

@@ -0,0 +1,20 @@
+-- name: aki_kdigo_48h
+-- condition: aki
+-- description: Serum creatinine rises by >= 0.3 mg/dL within 48 hours, within one admission.
+-- reference: KDIGO 2012 AKI guideline, creatinine criterion 1 (urine-output criterion not used).
+WITH cr AS (
+    SELECT l.hadm_id, l.charttime, l.valuenum
+    FROM labevents l
+    JOIN d_labitems d ON d.itemid = l.itemid
+    WHERE lower(d.label) = 'creatinine' AND d.fluid = 'Blood'
+      AND l.valuenum IS NOT NULL AND l.hadm_id IS NOT NULL
+)
+SELECT DISTINCT later.hadm_id
+FROM cr AS later
+JOIN cr AS earlier
+  ON earlier.hadm_id = later.hadm_id
+ AND earlier.charttime < later.charttime
+ AND earlier.charttime >= later.charttime - INTERVAL 48 HOUR
+-- Round the difference: in floating point 1.2 - 0.9 = 0.29999999999999993,
+-- which would silently miss a true 0.3 mg/dL rise.
+WHERE round(later.valuenum - earlier.valuenum, 6) >= 0.3

cohort_diff/definitions/aki_kdigo_7d.sql

@@ -0,0 +1,22 @@
+-- name: aki_kdigo_7d
+-- condition: aki
+-- description: Serum creatinine >= 1.5 x the lowest value in the prior 7 days, within one admission.
+-- reference: KDIGO 2012 AKI guideline, creatinine criterion 2 (baseline = in-admission minimum).
+WITH cr AS (
+    SELECT l.hadm_id, l.charttime, l.valuenum
+    FROM labevents l
+    JOIN d_labitems d ON d.itemid = l.itemid
+    WHERE lower(d.label) = 'creatinine' AND d.fluid = 'Blood'
+      AND l.valuenum IS NOT NULL AND l.hadm_id IS NOT NULL
+),
+flagged AS (
+    SELECT later.hadm_id
+    FROM cr AS later
+    JOIN cr AS earlier
+      ON earlier.hadm_id = later.hadm_id
+     AND earlier.charttime < later.charttime
+     AND earlier.charttime >= later.charttime - INTERVAL 7 DAY
+    GROUP BY later.hadm_id, later.charttime, later.valuenum
+    HAVING round(later.valuenum - 1.5 * min(earlier.valuenum), 6) >= 0
+)
+SELECT DISTINCT hadm_id FROM flagged

cohort_diff/definitions/dm_hba1c.sql

@@ -0,0 +1,9 @@
+-- name: dm_hba1c
+-- condition: diabetes
+-- description: Any HbA1c >= 6.5% during the admission.
+-- reference: ADA diagnostic threshold for HbA1c (a single in-hospital value, so an approximation).
+SELECT DISTINCT l.hadm_id
+FROM labevents l
+JOIN d_labitems d ON d.itemid = l.itemid
+WHERE lower(d.label) IN ('% hemoglobin a1c', 'hemoglobin a1c')
+  AND l.valuenum >= 6.5 AND l.hadm_id IS NOT NULL

cohort_diff/definitions/dm_icd.sql

@@ -0,0 +1,8 @@
+-- name: dm_icd
+-- condition: diabetes
+-- description: Any diabetes diagnosis code (ICD-10 E10-E14, ICD-9 250.*).
+-- reference: Common administrative-data definition.
+SELECT DISTINCT hadm_id
+FROM diagnoses_icd
+WHERE (icd_version = 10 AND substr(icd_code, 1, 3) IN ('E10', 'E11', 'E13', 'E14'))
+   OR (icd_version = 9 AND icd_code LIKE '250%')

cohort_diff/definitions/dm_meds.sql

@@ -0,0 +1,10 @@
+-- name: dm_meds
+-- condition: diabetes
+-- description: Any glucose-lowering medication ordered (insulin, metformin, sulfonylureas, DPP-4 inhibitors, SGLT2 inhibitors, GLP-1 agonists).
+-- reference: Medication-based phenotype; insulin for stress hyperglycemia will over-capture.
+SELECT DISTINCT hadm_id
+FROM prescriptions
+WHERE hadm_id IS NOT NULL AND regexp_matches(
+    lower(drug),
+    'insulin|metformin|glipizide|glyburide|glimepiride|sitagliptin|linagliptin|empagliflozin|dapagliflozin|canagliflozin|liraglutide|semaglutide|dulaglutide'
+)

cohort_diff/definitions/readmit30_any.sql

@@ -0,0 +1,12 @@
+-- name: readmit30_any
+-- condition: readmission
+-- description: Index admissions followed by any admission of the same patient within 30 days of discharge.
+-- reference: The simplest definition used in many MIMIC papers.
+WITH ordered AS (
+    SELECT hadm_id, dischtime,
+           lead(admittime) OVER (PARTITION BY subject_id ORDER BY admittime) AS next_admit
+    FROM admissions
+)
+SELECT hadm_id
+FROM ordered
+WHERE next_admit IS NOT NULL AND next_admit <= dischtime + INTERVAL 30 DAY

cohort_diff/definitions/readmit30_excl.sql

@@ -0,0 +1,17 @@
+-- name: readmit30_excl
+-- condition: readmission
+-- description: As readmit30_any, but excludes index admissions ending in death, hospice or discharge against advice, and planned (elective) readmissions.
+-- reference: Inspired by the CMS Hospital Readmissions Reduction Program exclusions (simplified).
+WITH ordered AS (
+    SELECT hadm_id, dischtime, hospital_expire_flag, discharge_location,
+           lead(admittime) OVER (PARTITION BY subject_id ORDER BY admittime) AS next_admit,
+           lead(admission_type) OVER (PARTITION BY subject_id ORDER BY admittime) AS next_type
+    FROM admissions
+)
+SELECT hadm_id
+FROM ordered
+WHERE next_admit IS NOT NULL
+  AND next_admit <= dischtime + INTERVAL 30 DAY
+  AND hospital_expire_flag = 0
+  AND coalesce(discharge_location, '') NOT IN ('HOSPICE', 'AGAINST ADVICE', 'DIED')
+  AND upper(coalesce(next_type, '')) NOT LIKE '%ELECTIVE%'

cohort_diff/engine.py

@@ -0,0 +1,80 @@
+"""Run cohort definitions with DuckDB over MIMIC-IV-shaped tables.
+
+DuckDB reads the demo's ``.csv.gz`` files in place, so nothing has to be
+loaded into a server first.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import duckdb
+import pandas as pd
+
+from cohort_diff.registry import Definition
+
+TABLES = ("patients", "admissions", "labevents", "d_labitems", "diagnoses_icd", "prescriptions")
+OPTIONAL = {"prescriptions"}
+
+
+def _find(root: Path, table: str) -> Path | None:
+    for candidate in (
+        root / "hosp" / f"{table}.csv.gz",
+        root / "hosp" / f"{table}.csv",
+        root / f"{table}.csv.gz",
+        root / f"{table}.csv",
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def connect(data: str | Path | dict[str, pd.DataFrame]) -> duckdb.DuckDBPyConnection:
+    """An in-memory DuckDB connection with one view per MIMIC table.
+
+    ``data`` is a MIMIC-IV root (containing ``hosp/``), a flat CSV directory, or a
+    dict of DataFrames (used by the tests).
+    """
+    con = duckdb.connect()
+    if isinstance(data, dict):
+        for name, frame in data.items():
+            con.register(f"_{name}", frame)
+            con.execute(f"CREATE VIEW {name} AS SELECT * FROM _{name}")
+        return con
+    root = Path(data)
+    for table in TABLES:
+        path = _find(root, table)
+        if path is None:
+            if table in OPTIONAL:
+                con.execute(
+                    f"CREATE VIEW {table} AS SELECT NULL::BIGINT AS subject_id, "
+                    "NULL::BIGINT AS hadm_id, NULL::TIMESTAMP AS starttime, "
+                    "NULL::TIMESTAMP AS stoptime, NULL::VARCHAR AS drug WHERE false"
+                )
+                continue
+            raise FileNotFoundError(f"{table}: expected {root}/hosp/{table}.csv.gz")
+        # Views can't take bound parameters, so quote the path as an SQL literal.
+        literal = str(path).replace("'", "''")
+        con.execute(
+            f"CREATE VIEW {table} AS SELECT * FROM read_csv_auto('{literal}', header = true)"
+        )
+    return con
+
+
+def run(con: duckdb.DuckDBPyConnection, definition: Definition) -> set[int]:
+    """The admissions (``hadm_id``) that meet a definition."""
+    rows = con.execute(definition.sql).fetchall()
+    return {int(r[0]) for r in rows if r[0] is not None}
+
+
+def admissions_frame(con: duckdb.DuckDBPyConnection) -> pd.DataFrame:
+    """One row per admission with the fields used to describe cohorts."""
+    return con.execute(
+        """
+        SELECT a.hadm_id, a.subject_id, a.hospital_expire_flag,
+               date_diff('hour', a.admittime, a.dischtime) / 24.0 AS los_days,
+               p.anchor_age + (year(a.admittime) - p.anchor_year) AS age,
+               p.gender
+        FROM admissions a JOIN patients p ON p.subject_id = a.subject_id
+        """
+    ).df()

cohort_diff/registry.py

@@ -0,0 +1,56 @@
+"""Cohort definitions: SQL files with a small metadata header.
+
+Each file in ``cohort_diff/definitions`` starts with ``-- key: value`` lines
+(``name``, ``condition``, ``description``, ``reference``) followed by one query
+that returns a single column, ``hadm_id``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+REQUIRED_KEYS = ("name", "condition", "description", "reference")
+
+
+@dataclass(frozen=True)
+class Definition:
+    name: str
+    condition: str
+    description: str
+    reference: str
+    sql: str
+
+
+def parse(text: str) -> Definition:
+    meta: dict[str, str] = {}
+    body: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not body and stripped.startswith("--") and ":" in stripped:
+            key, value = stripped[2:].split(":", 1)
+            meta[key.strip()] = value.strip()
+        elif stripped or body:
+            body.append(line)
+    missing = [k for k in REQUIRED_KEYS if k not in meta]
+    if missing:
+        raise ValueError(f"definition header missing {missing}")
+    return Definition(sql="\n".join(body).strip(), **{k: meta[k] for k in REQUIRED_KEYS})
+
+
+def builtin() -> dict[str, Definition]:
+    """All definitions shipped with the package, keyed by name."""
+    folder = resources.files("cohort_diff") / "definitions"
+    defs = [parse(f.read_text()) for f in folder.iterdir() if f.name.endswith(".sql")]
+    return {d.name: d for d in sorted(defs, key=lambda d: d.name)}
+
+
+def load(name_or_path: str) -> Definition:
+    """A built-in definition by name, or a user's ``.sql`` file by path."""
+    if name_or_path.endswith(".sql"):
+        return parse(Path(name_or_path).read_text())
+    defs = builtin()
+    if name_or_path not in defs:
+        raise KeyError(f"unknown definition {name_or_path!r}; known: {', '.join(defs)}")
+    return defs[name_or_path]

cohort_diff/synth.py

@@ -0,0 +1,188 @@
+# Copied from ehr-asof (same author) so this repo stays self-contained.
+"""Synthetic data shaped like MIMIC-IV's hosp module.
+
+The generator exists so the code and tests run anywhere. It is not a model of
+real patients: it plants the two timing problems the project studies, so
+every number it produces must be labelled *synthetic*.
+
+1. Lab results become available (``storetime``) after the sample is taken
+   (``charttime``). Some labs, such as cultures, take hours to days.
+2. Diagnosis codes carry no timestamp. They are assigned at discharge, and
+   sicker patients, including those who die, receive more severe codes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+# (itemid, label, fluid, category, mean, sd, effect of severity, median delay in hours)
+LAB_ITEMS: list[tuple[int, str, str, str, float, float, float, float]] = [
+    (50912, "Creatinine", "Blood", "Chemistry", 1.0, 0.3, 0.6, 1.5),
+    (50971, "Potassium", "Blood", "Chemistry", 4.1, 0.4, 0.3, 1.5),
+    (50983, "Sodium", "Blood", "Chemistry", 139.0, 3.0, -2.0, 1.5),
+    (51301, "White Blood Cells", "Blood", "Hematology", 8.0, 2.5, 3.0, 1.0),
+    (51222, "Hemoglobin", "Blood", "Hematology", 12.5, 1.5, -1.0, 1.0),
+    (50813, "Lactate", "Blood", "Blood Gas", 1.4, 0.5, 1.2, 0.5),
+    (50852, "% Hemoglobin A1c", "Blood", "Chemistry", 5.7, 0.8, 0.2, 30.0),
+    (51003, "Troponin T", "Blood", "Chemistry", 0.02, 0.02, 0.15, 3.0),
+]
+
+# ICD-10 codes; the last group is assigned mostly to patients who die.
+COMMON_CODES = ["I10", "E119", "E785", "N179", "J189", "I509", "K219", "F329"]
+TERMINAL_CODES = ["R6521", "I469", "Z515"]  # septic shock, cardiac arrest, palliative care
+
+
+@dataclass(frozen=True)
+class SynthConfig:
+    n_patients: int = 2000
+    admissions_per_patient: float = 1.4
+    seed: int = 0
+    start: str = "2150-01-01"
+
+
+def generate(config: SynthConfig | None = None) -> dict[str, pd.DataFrame]:
+    """Return MIMIC-IV-shaped tables: patients, admissions, labevents, d_labitems,
+    diagnoses_icd and prescriptions."""
+    cfg = config or SynthConfig()
+    rng = np.random.default_rng(cfg.seed)
+    start = pd.Timestamp(cfg.start)
+
+    subject_ids = np.arange(10_000_000, 10_000_000 + cfg.n_patients)
+    patients = pd.DataFrame(
+        {
+            "subject_id": subject_ids,
+            "gender": rng.choice(["F", "M"], size=cfg.n_patients),
+            "anchor_age": rng.integers(18, 91, size=cfg.n_patients),
+            "anchor_year": 2150,
+            "anchor_year_group": "2017 - 2019",
+            "dod": pd.NaT,
+        }
+    )
+    frailty = rng.normal(0, 1, size=cfg.n_patients)
+
+    adm_rows = []
+    hadm_id = 20_000_000
+    for i, sid in enumerate(subject_ids):
+        n_adm = 1 + rng.poisson(cfg.admissions_per_patient - 1)
+        t = start + pd.Timedelta(days=float(rng.uniform(0, 365)))
+        for _ in range(n_adm):
+            hadm_id += 1
+            severity = 0.7 * frailty[i] + rng.normal(0, 1) + 0.02 * (patients.anchor_age[i] - 60)
+            los_hours = float(
+                np.clip(rng.lognormal(np.log(96) + 0.25 * severity, 0.6), 30, 60 * 24)
+            )
+            p_death = 1 / (1 + np.exp(-(-3.6 + 1.4 * severity)))
+            died = bool(rng.random() < p_death)
+            admit = t + pd.Timedelta(minutes=int(rng.integers(0, 24 * 60)))
+            disch = admit + pd.Timedelta(hours=los_hours)
+            adm_rows.append(
+                {
+                    "subject_id": sid,
+                    "hadm_id": hadm_id,
+                    "admittime": admit,
+                    "dischtime": disch,
+                    "deathtime": disch if died else pd.NaT,
+                    "admission_type": rng.choice(
+                        ["EW EMER.", "URGENT", "ELECTIVE"], p=[0.6, 0.25, 0.15]
+                    ),
+                    "admission_location": "EMERGENCY ROOM",
+                    "discharge_location": "DIED"
+                    if died
+                    else rng.choice(["HOME", "SNF", "HOSPICE"], p=[0.75, 0.2, 0.05]),
+                    "hospital_expire_flag": int(died),
+                    "latent_severity": severity,
+                }
+            )
+            if died:
+                break  # no admissions after death
+            t = disch + pd.Timedelta(days=float(rng.exponential(60)))
+    admissions = pd.DataFrame(adm_rows)
+
+    lab_rows = []
+    labevent_id = 0
+    for adm in admissions.itertuples(index=False):
+        los = (adm.dischtime - adm.admittime).total_seconds() / 3600
+        n_draws = max(1, int(los // 12))
+        for k in range(n_draws):
+            draw = adm.admittime + pd.Timedelta(hours=float(k * 12 + rng.uniform(0, 4)))
+            # severity drifts upward towards death
+            drift = 1.5 * (k / max(n_draws - 1, 1)) if adm.hospital_expire_flag else 0.0
+            for itemid, _label, _fluid, _cat, mu, sd, eff, delay in LAB_ITEMS:
+                if itemid == 50852 and k > 0:
+                    continue  # HbA1c once per admission
+                if rng.random() < 0.15:
+                    continue
+                labevent_id += 1
+                value = mu + 0.5 * eff * (adm.latent_severity + drift) + rng.normal(0, sd)
+                value = max(value, 0.01)
+                store = draw + pd.Timedelta(hours=float(rng.lognormal(np.log(delay), 0.8)))
+                lab_rows.append(
+                    {
+                        "labevent_id": labevent_id,
+                        "subject_id": adm.subject_id,
+                        "hadm_id": adm.hadm_id,
+                        "specimen_id": labevent_id,
+                        "itemid": itemid,
+                        "charttime": draw,
+                        "storetime": store if rng.random() > 0.02 else pd.NaT,
+                        "value": f"{value:.2f}",
+                        "valuenum": round(value, 2),
+                        "valueuom": "",
+                        "flag": None,
+                    }
+                )
+    labevents = pd.DataFrame(lab_rows)
+
+    d_labitems = pd.DataFrame(
+        [(i, lab, fl, cat) for i, lab, fl, cat, *_ in LAB_ITEMS],
+        columns=["itemid", "label", "fluid", "category"],
+    )
+
+    dx_rows = []
+    rx_rows = []
+    for adm in admissions.itertuples(index=False):
+        codes: list[str] = []
+        for code in COMMON_CODES:
+            p = 1 / (1 + np.exp(-(-1.8 + 0.5 * adm.latent_severity)))
+            if rng.random() < p:
+                codes.append(code)
+        if adm.hospital_expire_flag:
+            codes += [c for c in TERMINAL_CODES if rng.random() < 0.7]
+        elif rng.random() < 0.03:
+            codes.append(rng.choice(TERMINAL_CODES))
+        for seq, code in enumerate(codes, start=1):
+            dx_rows.append(
+                {
+                    "subject_id": adm.subject_id,
+                    "hadm_id": adm.hadm_id,
+                    "seq_num": seq,
+                    "icd_code": code,
+                    "icd_version": 10,
+                }
+            )
+        if "E119" in codes and rng.random() < 0.8:
+            rx_rows.append(
+                {
+                    "subject_id": adm.subject_id,
+                    "hadm_id": adm.hadm_id,
+                    "starttime": adm.admittime + pd.Timedelta(hours=6),
+                    "stoptime": adm.dischtime,
+                    "drug": rng.choice(["Metformin", "Insulin", "Glipizide"]),
+                }
+            )
+    diagnoses_icd = pd.DataFrame(dx_rows)
+    prescriptions = pd.DataFrame(
+        rx_rows, columns=["subject_id", "hadm_id", "starttime", "stoptime", "drug"]
+    )
+
+    return {
+        "patients": patients,
+        "admissions": admissions.drop(columns="latent_severity"),
+        "labevents": labevents,
+        "d_labitems": d_labitems,
+        "diagnoses_icd": diagnoses_icd,
+        "prescriptions": prescriptions,
+    }

cohort_diff-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: cohort-diff
+Version: 0.1.0
+Summary: How different are 'the same' EHR cohorts? Run published definitions side by side on MIMIC-IV and diff them.
+Author: Eric Yang
+Author-email: Eric Yang <159638721+yangpings@users.noreply.github.com>
+License-Expression: MIT
+Requires-Dist: duckdb>=1.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# cohort-diff
+
+**Keywords:** EHR · MIMIC-IV · cohort definitions · phenotyping · acute kidney injury · diabetes · 30-day readmission · reproducibility · odds ratio · Jaccard index · bootstrap confidence intervals
+
+**Skills:** Python · SQL · DuckDB · pandas · NumPy · patient-level bootstrap · uv packaging · PyPI (Trusted Publishing) · GitHub Actions CI · pytest · Hypothesis (property-based testing) · test oracles · mypy (strict) · ruff · AI-assisted engineering (Claude Code with CLAUDE.md, tests first, AI log)
+
+How different are "the same" EHR cohorts? `cohort-diff` runs several definitions of one condition side by side on MIMIC-IV-shaped data and reports how much the cohorts, and the results built on them, disagree.
+
+## Description
+
+A cohort definition is a modelling decision, but papers usually report it in a sentence. Two studies that both say "AKI patients in MIMIC-IV" may share only a fraction of their admissions: one counts discharge diagnosis codes, another a creatinine rise within 48 hours, another a rise over 7 days. A finding such as "AKI is associated with higher in-hospital mortality" can change size with the definition. `cohort-diff` stores each definition as a versioned SQL file with its source, runs them on DuckDB directly over MIMIC's `.csv.gz` files, and reports overlap, who is in each cohort, and how a typical downstream association moves.
+
+## Objective
+
+1. Build a tested, pip-installable library that runs cohort definitions as reviewable SQL and checks each one against an independent implementation.
+2. Measure how much definitions of the same condition (AKI, diabetes, 30-day readmission) disagree, in membership and in a downstream result (the odds ratio between membership and in-hospital mortality), with confidence intervals.
+3. *(Extension, branch `cohort-diff-llm`.)* Measure how often a large language model, given a paper's methods text, drafts a cohort definition that passes the same oracle tests as the hand-written one.
+
+## Hypotheses
+
+- **H1.** Definitions of the same condition select substantially different admissions (pairwise Jaccard well below 1).
+- **H2.** Code-based and lab-based definitions differ systematically: codes under-capture, and lab rules with fixed thresholds over-capture when measurements are frequent and noisy.
+- **H3.** The mortality odds ratio reported for "the same" condition changes materially with the definition: for some pairs, the 95% interval of the ratio of their odds ratios excludes 1.
+- **H4.** A definition limits which questions its cohort can answer (for example, readmission exclusions that remove every death).
+- **H5.** *(Extension.)* LLM-drafted definitions often run without error but fail the oracle tests at clinically important details (thresholds, time windows, specimen type, boundary conditions), so tests, not inspection, decide whether a draft can be used.
+
+## Samples
+
+| Dataset | Access | Size | Role |
+| --- | --- | --- | --- |
+| Synthetic, MIMIC-shaped (`cohort-diff synth`, seed 0) | Generated | 2,000 patients, 2,738 admissions | Known-structure validation; numbers say nothing about real patients |
+| MIMIC-IV Clinical Database Demo v2.2 | Open (ODbL) | 100 patients, 275 admissions | End-to-end run on real EHR data |
+
+The demo shares the full MIMIC-IV schema, so the same definitions run on full MIMIC-IV (credentialed) unchanged.
+
+## Methods
+
+- **Definitions as data.** Each definition is one SQL file in `src/cohort_diff/definitions/` with a header (`name`, `condition`, `description`, `reference`) and returns one column, `hadm_id`. Adding a definition does not touch Python.
+- **Built-in definitions.**
+
+| Name | Condition | Rule |
+| --- | --- | --- |
+| `aki_icd` | AKI | ICD-10 N17.* or ICD-9 584.* on the admission |
+| `aki_kdigo_48h` | AKI | Creatinine rises ≥ 0.3 mg/dL within 48 h (KDIGO 2012, criterion 1) |
+| `aki_kdigo_7d` | AKI | Creatinine ≥ 1.5 × the lowest value in the prior 7 days (KDIGO 2012, criterion 2) |
+| `dm_icd` | Diabetes | ICD-10 E10/E11/E13/E14 or ICD-9 250.* |
+| `dm_hba1c` | Diabetes | Any HbA1c ≥ 6.5% during the admission |
+| `dm_meds` | Diabetes | Any glucose-lowering medication |
+| `readmit30_any` | Readmission | Any admission within 30 days of discharge |
+| `readmit30_excl` | Readmission | As above, excluding deaths, hospice, discharge against advice and elective readmissions (inspired by CMS HRRP, simplified) |
+
+- **Engine.** DuckDB, in process, reads the MIMIC tables in place (demo folder layout or flat CSVs) as views. Lab items are found by label and fluid, not by itemid.
+- **Correctness.** Every rule-based definition is compared with an independent, deliberately slow pandas implementation (a test oracle written with loops rather than joins), on the synthetic data and on hundreds of random creatinine series generated by Hypothesis. Hand-picked regression tests pin threshold edge cases that both implementations could get wrong together.
+- **Comparison.** For every pair of definitions: admissions in both, in only one, and the Jaccard index |A ∩ B| / |A ∪ B|. For each cohort: size, prevalence, mean age, % female, in-hospital mortality.
+- **Downstream result.** Unadjusted odds ratio between membership and in-hospital mortality, with a Woolf 95% CI (log OR ± 1.96·√(1/a + 1/b + 1/c + 1/d)); 0.5 is added to every cell when any cell is 0 (Haldane–Anscombe).
+- **Uncertainty.** Patient-level bootstrap (1,000 resamples; a patient drawn k times contributes all their admissions k times) gives 95% percentile intervals for each pair's Jaccard index and for the ratio of their mortality odds ratios (OR of a / OR of b). An interval for the ratio that excludes 1 means the two definitions disagree about the association, beyond sampling noise. A test checks that patients, not admissions, are resampled.
+- **Scale check.** Wall time of `compare` for each condition, on the demo and (once credentialed) on full MIMIC-IV, on one laptop.
+- **Extension: LLM-drafted definitions** *(planned, branch `cohort-diff-llm`)*. An LLM receives a paper's methods text and the table and column names only (never patient data) and returns a definition through JSON-schema structured output. Each draft is graded by the same oracle and property tests, and by exact agreement with the hand-written definition on synthetic data. Pass rates for 3+ models on a 20-item labeled set, with 95% intervals; every failure is categorized.
+- **Engineering.** Strict typing, lint and tests on Python 3.11–3.13 in CI; the wheel is built in CI; releases go to PyPI by Trusted Publishing from version tags.
+
+## Results
+
+### Synthetic data (2,000 patients, 2,738 admissions, seed 0)
+
+| Definition | n | Prevalence | Mortality among members | Mortality OR [95% CI] |
+| --- | --- | --- | --- | --- |
+| aki_icd | 400 | 14.6% | 16.8% | 3.06 [2.24, 4.19] |
+| aki_kdigo_48h | 2,139 | 78.2% | 9.2% | 4.23 [2.44, 7.33] |
+| aki_kdigo_7d | 2,033 | 74.3% | 8.4% | 1.48 [1.04, 2.10] |
+| dm_icd | 438 | 16.0% | 15.8% | 2.84 [2.09, 3.87] |
+| dm_hba1c | 374 | 13.7% | 10.4% | 1.48 [1.03, 2.14] |
+| dm_meds | 355 | 13.0% | 16.1% | 2.77 [2.00, 3.84] |
+| readmit30_any | 296 | 10.8% | 0.0% | not meaningful (no deaths by construction) |
+| readmit30_excl | 242 | 8.8% | 0.0% | not meaningful (no deaths by construction) |
+
+Pairwise overlap and disagreement in the mortality association (patient-level bootstrap, 1,000 resamples, 95% intervals):
+
+| Pair | Jaccard [95% CI] | Ratio of mortality ORs [95% CI] |
+| --- | --- | --- |
+| aki_icd vs aki_kdigo_48h | 0.160 [0.145, 0.176] | 0.72 [0.33, 1.26] |
+| aki_icd vs aki_kdigo_7d | 0.142 [0.127, 0.157] | **2.08 [1.29, 3.37]** |
+| aki_kdigo_48h vs aki_kdigo_7d | 0.883 [0.869, 0.896] | **2.87 [1.87, 5.15]** |
+| dm_hba1c vs dm_icd | 0.099 [0.078, 0.121] | **0.52 [0.31, 0.83]** |
+| dm_hba1c vs dm_meds | 0.093 [0.072, 0.116] | **0.54 [0.32, 0.86]** |
+| dm_icd vs dm_meds | 0.811 [0.776, 0.847] | 1.03 [0.88, 1.21] |
+| readmit30_any vs readmit30_excl | 0.818 [0.771, 0.860] | not meaningful (no deaths in either cohort) |
+
+Bold: the interval excludes 1, so the two definitions disagree about the mortality association beyond sampling noise.
+
+- **Code vs lab definitions barely overlap** (Jaccard 0.09–0.16), while two lab rules (KDIGO 48 h vs 7 d) or two code-like rules (ICD vs medications) overlap 81–88%.
+- **High overlap does not mean the same answer.** The two KDIGO definitions share 88% of admissions, yet their mortality ORs differ about threefold (ratio 2.87 [1.87, 5.15]).
+- **Different-looking ORs can be compatible.** `aki_icd` (3.06) and `aki_kdigo_48h` (4.23) look different, but the interval for their ratio includes 1.
+- **KDIGO-48h flags 78% of synthetic admissions**: the generator draws creatinine about every 12 h with noise (SD 0.3 mg/dL), and a 0.3 mg/dL rule fires on noise when labs are frequent. Whether real data shows the same is what the demo and full MIMIC-IV can answer.
+- **Readmission cohorts contain no deaths by construction** (an admission followed by another one cannot end in death), so their mortality ORs come only from the 0.5 zero-cell correction. The definition limits which questions the cohort can answer.
+
+### MIMIC-IV demo (real data: 100 patients, 275 admissions)
+
+| Definition | n | Prevalence | Mortality among members | Mortality OR [95% CI] |
+| --- | --- | --- | --- | --- |
+| aki_icd | 70 | 25.5% | 15.7% | 9.37 [2.88, 30.51] |
+| aki_kdigo_48h | 69 | 25.1% | 15.9% | 9.58 [2.94, 31.20] |
+| aki_kdigo_7d | 53 | 19.3% | 20.8% | 14.27 [4.34, 46.97] |
+| dm_icd | 111 | 40.4% | 4.5% | 0.73 [0.24, 2.19] |
+| dm_hba1c | 17 | 6.2% | 0.0% | 0.45 [0.03, 7.82] (no deaths; zero-cell correction) |
+| dm_meds | 135 | 49.1% | 5.9% | 1.20 [0.42, 3.40] |
+| readmit30_any | 53 | 19.3% | 0.0% | not meaningful (no deaths by construction) |
+| readmit30_excl | 49 | 17.8% | 0.0% | not meaningful (no deaths by construction) |
+
+| Pair | Jaccard [95% CI] | Ratio of mortality ORs [95% CI] |
+| --- | --- | --- |
+| aki_icd vs aki_kdigo_48h | 0.376 [0.263, 0.494] | 0.98 [0.25, 3.23] |
+| aki_icd vs aki_kdigo_7d | 0.309 [0.189, 0.440] | 0.66 [0.17, 2.48] |
+| aki_kdigo_48h vs aki_kdigo_7d | 0.564 [0.447, 0.679] | 0.67 [0.20, 2.35] |
+| dm_hba1c vs dm_icd | 0.113 [0.071, 0.171] | 0.62 [0.17, 5.56] (zero-cell) |
+| dm_hba1c vs dm_meds | 0.126 [0.079, 0.176] | 0.38 [0.09, 1.91] (zero-cell) |
+| dm_icd vs dm_meds | 0.608 [0.461, 0.715] | 0.61 [0.15, 1.51] |
+| readmit30_any vs readmit30_excl | 0.925 [0.852, 1.000] | not meaningful |
+
+- **Real definitions also select different patients.** The AKI definitions have similar prevalence (19–25%) but share only 31–56% of their combined admissions. Diabetes by HbA1c ≥ 6.5% (6% of admissions) overlaps the code and medication definitions at Jaccard 0.11–0.13.
+- **The medication phenotype captures the most** (49% of admissions vs 40% by codes), consistent with insulin given for stress hyperglycemia; every HbA1c-defined admission is also in the medication cohort.
+- **KDIGO-48h flags 25% of demo admissions, not the 78% seen on synthetic data**, so the synthetic over-capture came from the generator's frequent, noisy creatinine, not from the rule itself.
+- **No disagreement in the mortality association can be shown at this size.** The AKI ORs range from 9.4 to 14.3 and the diabetes ORs from 0.45 to 1.20, but every ratio interval includes 1 and some are 20-fold wide.
+
+With 100 patients, cohorts are small and intervals wide; these numbers show the tool runs on real data, not how much definitions disagree in practice.
+
+### Scale check
+
+Full MIMIC-IV (about 546,000 admissions) will be timed once credentialed.
+
+| Data | Condition | Admissions | Wall time (s) | Machine |
+| --- | --- | --- | --- | --- |
+| MIMIC-IV demo | aki / diabetes / readmission | 275 | 1.6 / 1.5 / 1.3 (includes 1,000 bootstrap resamples and Python start-up) | Intel i7-12800HX, 64 GB RAM, Windows |
+
+### Extension: LLM-drafted definitions (planned)
+
+Not started. Planned on branch `cohort-diff-llm` after v0.1.0: pass rates of LLM-drafted definitions on the oracle tests for 3+ models on a 20-item labeled set, with 95% intervals and every failure categorized.
+
+### Correctness
+
+27 tests pass with 99% line coverage on Python 3.11–3.13 (CI). Two deliberate breaks show what each kind of test catches:
+
+| Deliberate break | Caught by | Not caught by |
+| --- | --- | --- |
+| Remove the rounding from the KDIGO 0.3 mg/dL comparison in both the SQL and the oracle | The hand-picked boundary test (0.9 → 1.2 and 1.1 → 1.4 missed) | Every SQL-vs-oracle test, because both shared the bug |
+| KDIGO window 48 h → 24 h | SQL vs oracle on synthetic data, and the Hypothesis property test (shrunk to creatinine 1.0 then 2.0 mg/dL, 25 hours apart) | (nothing missed) |
+
+## Discussion
+
+On synthetic data, where the structure is known, definitions of the same condition overlap little when they use different sources (codes vs labs, Jaccard 0.09–0.16; H1), and four of six pairs disagree about the mortality association beyond sampling noise (ratio intervals excluding 1; H3). High overlap does not guarantee agreement: the two KDIGO rules share 88% of admissions but their ORs differ about threefold.
+
+The open demo shows the same pattern in membership on real data: AKI definitions with almost identical prevalence share at most 56% of their admissions, and diabetes by HbA1c overlaps the other definitions at about 0.12 (H1). The medication phenotype captures the most admissions, as expected (H2). For AKI, H2 was not supported on the demo: the lab rule flagged the same share as the codes (25%), and the synthetic data's 78% came from the generator. Whether the mortality association itself changes with the definition (H3) cannot be tested with 100 patients: every interval for the ratio of ORs includes 1. Readmission definitions exclude deaths by construction, so they cannot answer a mortality question at all (H4).
+
+**Strengths.** Definitions are versioned, cited SQL rather than prose; each is checked against an independent implementation and by property tests; known-structure validation on synthetic data; installable with `pip`; reproducible by anyone from open data, a lock file and CI on Python 3.11–3.13.
+
+## Limitations
+
+- **No real-world estimate of disagreement.** The demo has 100 patients; its cohorts and intervals are too small to say how much definitions disagree in practice.
+- **Synthetic structure is planted.** Overlaps on synthetic data reflect the generator's assumptions, not real coding or lab practice.
+- **KDIGO is creatinine-only** (no urine output) with an in-admission baseline; many studies use pre-admission baselines.
+- **Readmission definitions are simplified**; the CMS planned-readmission algorithm is far more detailed.
+- **The odds ratio is unadjusted.** It shows how a reported association can move with the definition, not a causal effect.
+
+## Trial and error
+
+What went wrong while building this, and what changed as a result. Analysis problems come first because they affect results; engineering problems follow because they affect reproducibility.
+
+### Analysis and data
+
+| Problem | Why it matters | How it was handled |
+| --- | --- | --- |
+| A creatinine rise of exactly 0.3 mg/dL can be missed: in floating point, 1.2 − 0.9 = 0.29999999999999993 | KDIGO's 0.3 mg/dL threshold is clinically exact; a naive `>= 0.3` silently drops true AKI cases | The SQL and the oracle round the difference to 6 decimals. Removing the rounding from *both* left every SQL-vs-oracle test green (shared bug); only the hand-picked boundary test failed, on 0.9 → 1.2 and 1.1 → 1.4 (0.7 → 1.0 happens to round correctly) |
+| KDIGO-48h flagged 78% of synthetic admissions but 25% of demo admissions | A planted generator artifact (creatinine every 12 h with SD 0.3 mg/dL noise) looked like a property of the rule | Reported both; the synthetic over-capture is attributed to the generator, and synthetic overlaps are used only to validate the tool |
+| `dm_hba1c` has no deaths on the demo (17 admissions) | Its odds ratio and every ratio involving it come only from the 0.5 zero-cell correction | Flagged as zero-cell in the Results tables and not interpreted |
+| A wrong time window (24 h instead of KDIGO's 48 h) still produces a plausible-looking cohort | Window edges are where cohort SQL is most often wrong, and a smaller cohort doesn't look broken | Deliberately changing the window to 24 h failed two tests: SQL vs oracle on synthetic data (admissions missing from the SQL cohort), and the Hypothesis property test, which shrank the failure to the minimal case: creatinine 1.0 then 2.0 mg/dL, 25 hours apart |
+
+### Engineering
+
+| Part | What went wrong | Cause | Fix and lesson |
+| --- | --- | --- | --- |
+| Setup | The parent lab repository saw the whole Level 1 folder (both projects and the MIMIC-IV demo data) as untracked files | The parent's `.gitignore` had no rule for that folder, although earlier notes said it did | Added the folder to the parent's `.gitignore` before any commit; nothing had been committed. Lesson: verify ignore rules with `git check-ignore -v` and `git status`, not from notes |
+| CLI | The Part 5 commit had 2 files instead of 3: the CI workflow still lacked the release job | One of three files to replace was skipped; the commit itself succeeded, so nothing looked wrong | Caught by `git show --stat HEAD` before pushing; replaced the workflow and folded it in with `git commit --amend`. Lesson: compare the commit's file list with the list you expected before `git push` |
+
+## Conclusions
+
+"The same" cohort is often not the same patients: on real MIMIC-IV demo data, AKI definitions agree on at most 56% of their combined admissions and diabetes definitions on as little as 11%. `cohort-diff` makes that difference measurable, with each definition as tested, cited SQL and paired, patient-level intervals for overlap and for the downstream association. Whether those differences change published associations on real data is the question for full MIMIC-IV, where the same code runs unchanged.
+
+## Repository layout
+
+| Path | What it does |
+| --- | --- |
+| `src/cohort_diff/definitions/` | One SQL file per cohort definition, with a metadata header |
+| `src/cohort_diff/registry.py` | Finds and parses definitions (built-in or a path) |
+| `src/cohort_diff/engine.py` | DuckDB views over MIMIC tables (folder or DataFrames) |
+| `src/cohort_diff/compare.py` | Jaccard, overlap table, cohort description, mortality odds ratio, patient-level bootstrap, markdown report |
+| `src/cohort_diff/synth.py` | MIMIC-shaped synthetic data |
+| `src/cohort_diff/cli.py` | `list`, `run`, `synth`, `compare` |
+| `tests/` | Unit, oracle and property-based (Hypothesis) tests |
+| `CLAUDE.md` | Project rules for AI coding agents (commands, testing, data safety) |
+| `docs/AI_LOG.md` | What was delegated to AI tools, what they got wrong, and how it was caught |
+
+## Reproduce
+
+```bash
+uv sync
+uv run cohort-diff synth --out data/synth --patients 2000 --seed 0
+uv run cohort-diff list
+uv run cohort-diff compare --condition aki --data data/synth --out reports/aki.md
+uv run cohort-diff compare --condition aki --data path/to/mimic-iv-clinical-database-demo-2.2
+```
+
+Development: `uv run ruff format --check src tests`, `uv run ruff check src tests`, `uv run mypy src` (strict), `uv run pytest`, `uv build`.
+
+## Citations
+
+- Johnson, A., Bulgarelli, L., Pollard, T., Horng, S., Celi, L. A., & Mark, R. (2023). MIMIC-IV Clinical Database Demo (version 2.2). PhysioNet. RRID:SCR_007345. https://doi.org/10.13026/dp1f-ex47
+- Johnson, A. E. W., Bulgarelli, L., Shen, L., et al. (2023). MIMIC-IV, a freely accessible electronic health record dataset. *Scientific Data*, 10, 1. https://doi.org/10.1038/s41597-022-01899-x
+- Pollard, T., Moody, B. E., Lehman, L., Gow, B., Fernandes, C., Xie, C., Johnson, A., Mark, R. G., & Heldt, T. (2026). PhysioNet as a global platform for biomedical research. *Nature Health*. https://doi.org/10.1038/s44360-026-00096-z
+- Kidney Disease: Improving Global Outcomes (KDIGO) Acute Kidney Injury Work Group (2012). KDIGO Clinical Practice Guideline for Acute Kidney Injury. *Kidney International Supplements*, 2(1), 1–138.
+
+## License
+
+Code: MIT. The MIMIC-IV demo data is distributed by PhysioNet under the Open Data Commons Open Database License v1.0 and is not included in this repository.

cohort_diff-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+cohort_diff/__init__.py,sha256=8Yl71OOa_VT0iHnDTQArsiPzQ54CQrzLmKAlE5PDl6I,450
+cohort_diff/cli.py,sha256=--abpuaLO7WzSr2LpFk0txQx6x_LnaVVMu9kixuYKW8,3789
+cohort_diff/compare.py,sha256=DlQov-ybxoTgPFr8TZvMkotZcIEi_vpJO5kwJpsg-Ys,7074
+cohort_diff/definitions/aki_icd.sql,sha256=CWR_rDPlBpBtSAqT4M7-o1R2FeUa1vS8wfTy74ZyGEI,351
+cohort_diff/definitions/aki_kdigo_48h.sql,sha256=fxKiEPrK1r8onBLYTQRam4XXnLPzIc0p78XGPYkRbBY,871
+cohort_diff/definitions/aki_kdigo_7d.sql,sha256=i6D1HUE0udUeWgC6rzPmJ9-gfmyD-wI9ooxR9tTQXWU,890
+cohort_diff/definitions/dm_hba1c.sql,sha256=JhQiPuQrmr_cAyt5Gqjbi2HBRfaVeIkhET5y3BNWzfk,394
+cohort_diff/definitions/dm_icd.sql,sha256=zqa-SKdzQwcnoGN689yFIF-K6H1JezHzW6XlZ3DUS24,343
+cohort_diff/definitions/dm_meds.sql,sha256=hrfzDDH_zMYqsncmqkJhY9kMVDLcROaYShDZw7huy_c,545
+cohort_diff/definitions/readmit30_any.sql,sha256=7sPIGDZAXPBnyaxUBO2l9L6kqcuusWXFS-P_qATFFbw,487
+cohort_diff/definitions/readmit30_excl.sql,sha256=L-QrwG4NcmeAR3C4V8fLl-Jfc1MZqyi45-SXICzND5o,883
+cohort_diff/engine.py,sha256=niEgEN9LskyowVuzvyLm7tLl3sckvkbrpYatDwRp0VM,2854
+cohort_diff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cohort_diff/registry.py,sha256=XnNeJxFj8fJnryVScxQncijieM7KKfDiRzcarOZg0cs,1920
+cohort_diff/synth.py,sha256=lEaU-zgpNiCvPYxuk3s_J1wm7kUx9iE7QEro12Gc8OI,7843
+cohort_diff-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+cohort_diff-0.1.0.dist-info/entry_points.txt,sha256=sxn9Wc8qX3S86s8GeFcvO9EcEgMufnuSakFWrX5Zu9c,54
+cohort_diff-0.1.0.dist-info/METADATA,sha256=1KC8v-z8-yJl7yI8v2AMy2_C5f6khpnTGzhP1_pLJvs,20781
+cohort_diff-0.1.0.dist-info/RECORD,,

cohort_diff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

cohort_diff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cohort-diff = cohort_diff.cli:main
+