icuflow 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
icuflow/__init__.py ADDED
@@ -0,0 +1,30 @@
1
+ """icuflow — the parts of a clinical prediction pipeline that are easy to get wrong.
2
+
3
+ Three of them, packaged because they are re-implemented badly in most clinical
4
+ prediction code:
5
+
6
+ splits grouping by patient, so a subject never spans train and test
7
+ calibration turning a score into a probability that means what it says
8
+ alarms comparing alerting systems at matched sensitivity
9
+
10
+ Designed to sit alongside PyHealth and RHealth rather than replace them: the
11
+ functions take and return plain arrays, so they drop into an existing task
12
+ pipeline without adopting a framework.
13
+ """
14
+
15
+ from .splits import (GroupSplit, group_kfold, split_by_subject,
16
+ assert_no_subject_leak)
17
+ from .calibration import (IsotonicCalibrator, PlattCalibrator, ece,
18
+ reliability_table)
19
+ from .alarms import (alarm_stats, threshold_at_sensitivity,
20
+ compare_at_matched_sensitivity)
21
+ from .tasks import horizon_label, sliding_windows
22
+
23
+ __version__ = "0.1.0"
24
+
25
+ __all__ = [
26
+ "GroupSplit", "group_kfold", "split_by_subject", "assert_no_subject_leak",
27
+ "IsotonicCalibrator", "PlattCalibrator", "ece", "reliability_table",
28
+ "alarm_stats", "threshold_at_sensitivity", "compare_at_matched_sensitivity",
29
+ "horizon_label", "sliding_windows", "__version__",
30
+ ]
icuflow/alarms.py ADDED
@@ -0,0 +1,56 @@
1
+ """Alarm-burden comparison at matched sensitivity.
2
+
3
+ Any alerting system can cut false alarms by catching fewer events. Comparing
4
+ two systems at whatever operating point each happens to sit on is the most
5
+ common way an alerting result is made to look better than it is, so this module
6
+ only compares at a sensitivity you have to name.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import numpy as np
12
+
13
+
14
+ def threshold_at_sensitivity(y, scores, target: float = 0.80) -> float:
15
+ y = np.asarray(y)
16
+ s = np.asarray(scores, float)
17
+ pos = s[y == 1]
18
+ if len(pos) == 0:
19
+ return float("nan")
20
+ return float(np.quantile(pos, 1.0 - target))
21
+
22
+
23
+ def alarm_stats(y, scores, threshold: float) -> dict:
24
+ y = np.asarray(y)
25
+ s = np.asarray(scores, float)
26
+ pred = s >= threshold
27
+ tp = int(np.sum(pred & (y == 1)))
28
+ fp = int(np.sum(pred & (y == 0)))
29
+ fn = int(np.sum(~pred & (y == 1)))
30
+ tn = int(np.sum(~pred & (y == 0)))
31
+ return {
32
+ "threshold": float(threshold),
33
+ "tp": tp, "fp": fp, "fn": fn, "tn": tn,
34
+ "sensitivity": tp / (tp + fn) if (tp + fn) else 0.0,
35
+ "specificity": tn / (tn + fp) if (tn + fp) else 0.0,
36
+ "ppv": tp / (tp + fp) if (tp + fp) else 0.0,
37
+ "false_alerts": fp,
38
+ "false_alerts_per_100": 100.0 * fp / len(y) if len(y) else 0.0,
39
+ }
40
+
41
+
42
+ def compare_at_matched_sensitivity(y, baseline_scores, model_scores,
43
+ target: float = 0.80) -> dict:
44
+ """Set both systems to the same sensitivity, then count false alerts."""
45
+ b = alarm_stats(y, baseline_scores,
46
+ threshold_at_sensitivity(y, baseline_scores, target))
47
+ m = alarm_stats(y, model_scores,
48
+ threshold_at_sensitivity(y, model_scores, target))
49
+ denom = b["false_alerts"] or 1
50
+ return {
51
+ "target_sensitivity": target,
52
+ "baseline": b,
53
+ "model": m,
54
+ "false_alert_reduction_pct": 100.0 * (b["false_alerts"] - m["false_alerts"]) / denom,
55
+ "sensitivity_gap": m["sensitivity"] - b["sensitivity"],
56
+ }
icuflow/calibration.py ADDED
@@ -0,0 +1,101 @@
1
+ """Calibration: making a score mean what it says.
2
+
3
+ A model can rank patients correctly and still emit numbers that are not
4
+ probabilities. A clinician acting on "82% risk" needs that to be right 82% of
5
+ the time, so calibration is reported beside discrimination, never instead of it.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import numpy as np
11
+
12
+
13
+ class PlattCalibrator:
14
+ """Logistic (Platt) scaling. Parametric, data-efficient, assumes sigmoid."""
15
+
16
+ def __init__(self, max_iter: int = 200, lr: float = 0.1):
17
+ self.a, self.b = 1.0, 0.0
18
+ self.max_iter, self.lr = max_iter, lr
19
+
20
+ def fit(self, scores, y):
21
+ s = np.asarray(scores, float)
22
+ y = np.asarray(y, float)
23
+ s = (s - s.mean()) / (s.std() + 1e-12)
24
+ self._mu, self._sd = float(np.mean(scores)), float(np.std(scores) + 1e-12)
25
+ for _ in range(self.max_iter):
26
+ p = 1 / (1 + np.exp(-(self.a * s + self.b)))
27
+ ga = float(np.mean((p - y) * s))
28
+ gb = float(np.mean(p - y))
29
+ self.a -= self.lr * ga
30
+ self.b -= self.lr * gb
31
+ return self
32
+
33
+ def transform(self, scores):
34
+ s = (np.asarray(scores, float) - self._mu) / self._sd
35
+ return 1 / (1 + np.exp(-(self.a * s + self.b)))
36
+
37
+
38
+ class IsotonicCalibrator:
39
+ """Isotonic regression via pool-adjacent-violators.
40
+
41
+ Non-parametric, so it fixes the S-shaped miscalibration boosted trees
42
+ reliably produce. Costs more data than Platt, which is the trade.
43
+ """
44
+
45
+ def __init__(self):
46
+ self.x_ = None
47
+ self.y_ = None
48
+
49
+ def fit(self, scores, y):
50
+ s = np.asarray(scores, float)
51
+ t = np.asarray(y, float)
52
+ order = np.argsort(s, kind="mergesort")
53
+ s, t = s[order], t[order]
54
+
55
+ # PAVA: merge adjacent blocks until the fit is non-decreasing.
56
+ vals = list(t)
57
+ weights = [1.0] * len(t)
58
+ i = 0
59
+ while i < len(vals) - 1:
60
+ if vals[i] <= vals[i + 1] + 1e-12:
61
+ i += 1
62
+ continue
63
+ w = weights[i] + weights[i + 1]
64
+ v = (vals[i] * weights[i] + vals[i + 1] * weights[i + 1]) / w
65
+ vals[i:i + 2] = [v]
66
+ weights[i:i + 2] = [w]
67
+ if i > 0:
68
+ i -= 1
69
+ fitted, k = [], 0
70
+ for v, w in zip(vals, weights):
71
+ fitted.extend([v] * int(round(w)))
72
+ self.x_ = s
73
+ self.y_ = np.asarray(fitted[:len(s)], float)
74
+ return self
75
+
76
+ def transform(self, scores):
77
+ if self.x_ is None:
78
+ raise RuntimeError("fit before transform")
79
+ return np.interp(np.asarray(scores, float), self.x_, self.y_)
80
+
81
+
82
+ def reliability_table(y, p, bins: int = 10) -> list:
83
+ y = np.asarray(y, float)
84
+ p = np.asarray(p, float)
85
+ edges = np.linspace(0, 1, bins + 1)
86
+ out = []
87
+ for i in range(bins):
88
+ lo, hi = edges[i], edges[i + 1]
89
+ m = (p >= lo) & (p < hi if i < bins - 1 else p <= hi)
90
+ if m.any():
91
+ out.append({"bin_lo": float(lo), "bin_hi": float(hi),
92
+ "n": int(m.sum()),
93
+ "predicted": float(p[m].mean()),
94
+ "observed": float(y[m].mean())})
95
+ return out
96
+
97
+
98
+ def ece(y, p, bins: int = 10) -> float:
99
+ rows = reliability_table(y, p, bins)
100
+ n = len(np.asarray(y))
101
+ return float(sum(r["n"] / n * abs(r["predicted"] - r["observed"]) for r in rows))
icuflow/cli.py ADDED
@@ -0,0 +1,73 @@
1
+ """icuflow command line: check a split, or score a set of predictions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import csv
7
+ import json
8
+ import sys
9
+
10
+ import numpy as np
11
+
12
+ from .alarms import compare_at_matched_sensitivity
13
+ from .calibration import ece, reliability_table
14
+ from .splits import assert_no_subject_leak, SubjectLeakError, split_by_subject
15
+
16
+
17
+ def _read_csv(path):
18
+ with open(path, newline="", encoding="utf8") as fh:
19
+ return list(csv.DictReader(fh))
20
+
21
+
22
+ def cmd_check_split(args) -> int:
23
+ rows = _read_csv(args.csv)
24
+ subj = np.array([r[args.subject_col] for r in rows])
25
+ split = np.array([r[args.split_col] for r in rows])
26
+ try:
27
+ assert_no_subject_leak(subj, split == "train", split == "test")
28
+ except SubjectLeakError as exc:
29
+ print(f"LEAK: {exc}", file=sys.stderr)
30
+ return 1
31
+ print(f"ok: {len(np.unique(subj))} subjects, no overlap between splits")
32
+ return 0
33
+
34
+
35
+ def cmd_score(args) -> int:
36
+ rows = _read_csv(args.csv)
37
+ y = np.array([int(float(r[args.label_col])) for r in rows])
38
+ p = np.array([float(r[args.score_col]) for r in rows])
39
+ out = {"n": len(y), "event_rate": float(y.mean()),
40
+ "ece": ece(y, p), "reliability": reliability_table(y, p)}
41
+ if args.baseline_col:
42
+ b = np.array([float(r[args.baseline_col]) for r in rows])
43
+ out["matched_sensitivity"] = compare_at_matched_sensitivity(
44
+ y, b, p, args.target_sensitivity)
45
+ json.dump(out, sys.stdout, indent=2)
46
+ print()
47
+ return 0
48
+
49
+
50
+ def main(argv=None) -> int:
51
+ ap = argparse.ArgumentParser(prog="icuflow", description=__doc__)
52
+ sub = ap.add_subparsers(dest="cmd", required=True)
53
+
54
+ a = sub.add_parser("check-split", help="fail if a subject spans train and test")
55
+ a.add_argument("csv")
56
+ a.add_argument("--subject-col", default="subject_id")
57
+ a.add_argument("--split-col", default="split")
58
+ a.set_defaults(fn=cmd_check_split)
59
+
60
+ b = sub.add_parser("score", help="calibration and alarm metrics for predictions")
61
+ b.add_argument("csv")
62
+ b.add_argument("--label-col", default="label")
63
+ b.add_argument("--score-col", default="score")
64
+ b.add_argument("--baseline-col", default=None)
65
+ b.add_argument("--target-sensitivity", type=float, default=0.80)
66
+ b.set_defaults(fn=cmd_score)
67
+
68
+ args = ap.parse_args(argv)
69
+ return args.fn(args)
70
+
71
+
72
+ if __name__ == "__main__":
73
+ raise SystemExit(main())
icuflow/splits.py ADDED
@@ -0,0 +1,65 @@
1
+ """Subject-grouped splitting.
2
+
3
+ The most common defect in clinical prediction code, and the one that most
4
+ inflates published numbers: splitting rows instead of patients. Two windows
5
+ from one admission share a baseline, a trajectory and often the label, so a
6
+ random row split lets the model memorise the patient.
7
+
8
+ `assert_no_subject_leak` exists so that this can be a test in a pipeline rather
9
+ than a convention someone remembers.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass
15
+
16
+ import numpy as np
17
+
18
+
19
+ class SubjectLeakError(AssertionError):
20
+ """Raised when the same subject appears in two folds."""
21
+
22
+
23
+ @dataclass
24
+ class GroupSplit:
25
+ train: np.ndarray # boolean mask
26
+ test: np.ndarray
27
+
28
+ def sizes(self) -> tuple:
29
+ return int(self.train.sum()), int(self.test.sum())
30
+
31
+
32
+ def split_by_subject(subjects, test_frac: float = 0.3,
33
+ seed: int = 0) -> GroupSplit:
34
+ subjects = np.asarray(subjects)
35
+ uniq = np.unique(subjects)
36
+ rng = np.random.default_rng(seed)
37
+ order = rng.permutation(len(uniq))
38
+ n_test = max(1, int(round(len(uniq) * test_frac)))
39
+ test_ids = set(uniq[order[:n_test]].tolist())
40
+ test = np.fromiter((s in test_ids for s in subjects), bool, len(subjects))
41
+ return GroupSplit(train=~test, test=test)
42
+
43
+
44
+ def group_kfold(subjects, n_splits: int = 5, seed: int = 0) -> list:
45
+ """K folds that never split a subject across them."""
46
+ subjects = np.asarray(subjects)
47
+ uniq = np.unique(subjects)
48
+ rng = np.random.default_rng(seed)
49
+ order = rng.permutation(len(uniq))
50
+ folds = np.array_split(uniq[order], n_splits)
51
+ out = []
52
+ for f in folds:
53
+ ids = set(f.tolist())
54
+ test = np.fromiter((s in ids for s in subjects), bool, len(subjects))
55
+ out.append(GroupSplit(train=~test, test=test))
56
+ return out
57
+
58
+
59
+ def assert_no_subject_leak(subjects, train_mask, test_mask) -> None:
60
+ subjects = np.asarray(subjects)
61
+ shared = set(subjects[train_mask].tolist()) & set(subjects[test_mask].tolist())
62
+ if shared:
63
+ raise SubjectLeakError(
64
+ f"{len(shared)} subject(s) appear in both train and test, "
65
+ f"e.g. {sorted(shared)[:5]}")
icuflow/tasks.py ADDED
@@ -0,0 +1,53 @@
1
+ """Task construction in the shape PyHealth and RHealth pipelines expect.
2
+
3
+ Both frameworks model a task as: take a patient record, emit samples. These
4
+ helpers cover the two steps every ICU horizon task needs and that every project
5
+ rewrites -- windowing a series, and labelling a prediction horizon without
6
+ leaking the present into the future.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import numpy as np
12
+
13
+
14
+ def sliding_windows(n: int, window: int, stride: int = 1):
15
+ """Yield (start, end) index pairs. End is exclusive."""
16
+ if window <= 0 or stride <= 0:
17
+ raise ValueError("window and stride must be positive")
18
+ for a in range(0, max(0, n - window + 1), stride):
19
+ yield a, a + window
20
+
21
+
22
+ def horizon_label(events, index: int, horizon_steps: int,
23
+ exclude_active: bool = True):
24
+ """Does an event occur in the horizon strictly after `index`?
25
+
26
+ Returns None when the row should be dropped, which happens when the event
27
+ is already active. Predicting an event in progress is not early warning,
28
+ and including those rows inflates every metric that follows.
29
+ """
30
+ ev = np.asarray(events, bool)
31
+ if exclude_active and ev[index]:
32
+ return None
33
+ future = ev[index + 1: index + 1 + horizon_steps]
34
+ if len(future) < horizon_steps:
35
+ return None # not enough follow-up to label honestly
36
+ return int(future.any())
37
+
38
+
39
+ def build_horizon_task(subjects, series_by_subject, events_by_subject,
40
+ featurise, horizon_steps: int, min_history: int = 4):
41
+ """Assemble X, y, subject arrays for a horizon-prediction task."""
42
+ X, y, subj = [], [], []
43
+ for s in subjects:
44
+ ev = np.asarray(events_by_subject[s], bool)
45
+ n = len(ev)
46
+ for i in range(min_history, n):
47
+ lab = horizon_label(ev, i, horizon_steps)
48
+ if lab is None:
49
+ continue
50
+ X.append(featurise(series_by_subject[s], i))
51
+ y.append(lab)
52
+ subj.append(s)
53
+ return np.asarray(X, float), np.asarray(y, int), np.asarray(subj)
@@ -0,0 +1,129 @@
1
+ Metadata-Version: 2.4
2
+ Name: icuflow
3
+ Version: 0.1.0
4
+ Summary: Leak-safe cohort splitting, calibration and alarm metrics for clinical prediction, in the shape PyHealth and RHealth tasks expect.
5
+ Author: Wenke Du
6
+ License: MIT
7
+ Project-URL: Source, https://github.com/evelyyyyynnnnn/2.0-Healthcare-Ai-Systems
8
+ Keywords: clinical,icu,pyhealth,calibration,early-warning
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
14
+ Requires-Python: >=3.9
15
+ Description-Content-Type: text/markdown
16
+ Requires-Dist: numpy>=1.24
17
+ Provides-Extra: pyhealth
18
+ Requires-Dist: pyhealth>=1.1.4; extra == "pyhealth"
19
+ Provides-Extra: dev
20
+ Requires-Dist: pytest>=7.0; extra == "dev"
21
+ Requires-Dist: scikit-learn>=1.3; extra == "dev"
22
+
23
+ # icuflow
24
+
25
+ > An installable package for the three parts of a clinical prediction pipeline that are easiest to get wrong: subject-grouped splits, calibration, and alarm comparison at matched sensitivity.
26
+
27
+ **Repository:** `2.0-Healthcare-Ai-Systems` &middot; **Pillar:** Healthcare Safety
28
+
29
+ ## Status
30
+
31
+ Working code, **29 passing tests**, and one measured run on real ICU charting.
32
+ Earlier versions of this page said the experiments ran on synthetic subjects;
33
+ the reportable run does not.
34
+
35
+ `icuflow` 0.1.0 is an installable package with 14 exports and a working CLI
36
+ (`check-split`, `score`). It is **not published to PyPI** — `published` is
37
+ `false` in the results file — so it has no download count and no users, and
38
+ neither is claimed.
39
+
40
+ **What it measures.** Using the **PhysioNet MIMIC-IV open-access demo**, the same cohort, features and model are split two ways. A random **row-level** split reports **AUROC 0.9058**. A **subject-grouped** split reports **0.4989** — chance. The reported figure is inflated by **81.57%**, and the honest one says the model learned nothing.
41
+
42
+ Cohort: 97 subjects, 134 stays, 37 readmissions, 22,512 rows, positive rate
43
+ 0.02838. about 100 ICU stays. The direction of the leakage effect is
44
+ meaningful; its magnitude, from a cohort this small, is not a population
45
+ estimate.
46
+
47
+ Last reportable run: `2026-09-06T23:57:16+00:00`
48
+
49
+ ## Quick start
50
+
51
+ ```bash
52
+ pip install -r requirements.txt
53
+ python -m pytest tests/ -q # 29 tests
54
+ python -m data.fetch # needs the sources in docs/DATA.md
55
+ python -m src.demo --real # the measured run -> results/latest-real.json
56
+ ```
57
+
58
+ ## Layout
59
+
60
+ ```
61
+ README.md
62
+ data/
63
+ |-- README.md
64
+ |-- manifests/
65
+ |-- sample/
66
+ docs/
67
+ |-- DATA.md
68
+ |-- METHOD.md
69
+ icuflow/
70
+ |-- __init__.py
71
+ |-- alarms.py
72
+ |-- calibration.py
73
+ |-- cli.py
74
+ |-- splits.py
75
+ |-- tasks.py
76
+ icuflow.egg-info/
77
+ |-- PKG-INFO
78
+ |-- SOURCES.txt
79
+ |-- dependency_links.txt
80
+ |-- entry_points.txt
81
+ |-- requires.txt
82
+ |-- top_level.txt
83
+ pyproject.toml
84
+ requirements.txt
85
+ results/
86
+ |-- README.md
87
+ |-- latest.json
88
+ src/
89
+ |-- .gitkeep
90
+ |-- __init__.py
91
+ |-- demo.py
92
+ |-- site.py
93
+ |-- sitekit.py
94
+ tests/
95
+ |-- .gitkeep
96
+ |-- test_icuflow.py
97
+ website/
98
+ |-- README.md
99
+ |-- index.html
100
+ ```
101
+
102
+ - `src/` &mdash; the implementation.
103
+ - `tests/` &mdash; pytest suite. These guard behaviour, not just imports.
104
+ - `results/latest.json` &mdash; the output of the last demo run. Every figure quoted
105
+ anywhere in this project traces back to this file.
106
+ - `website/` &mdash; a self-contained static site, deployable to Vercel by copying the
107
+ folder into its own repository. See `website/README.md`.
108
+
109
+ ## The website
110
+
111
+ `website/` has no build step. To deploy it independently:
112
+
113
+ ```bash
114
+ cp -r website/ ../my-4-pyhealth-rhealth-extension-site && cd ../my-4-pyhealth-rhealth-extension-site
115
+ git init && git add -A && git commit -m "site"
116
+ vercel deploy --prod
117
+ ```
118
+
119
+ The page is regenerated from `results.json` on every `python -m src.demo`, so the
120
+ figures on the site and the figures the code produces cannot drift apart. Do not edit
121
+ numbers on the page by hand.
122
+
123
+ ## Honesty note
124
+
125
+ Everything in this project runs on clearly-labelled synthetic or authored data.
126
+ Swap in the real source and the same pipeline reports real numbers &mdash; that is
127
+ what the structure is for. Until that happens, nothing here should be cited as a
128
+ measured result, and the site's closing section states explicitly what the project
129
+ does not establish.
@@ -0,0 +1,11 @@
1
+ icuflow/__init__.py,sha256=YjmvnMLcpb5WFxUdO7ZrKeVDDg2bnQ42PB0kPzTebU4,1311
2
+ icuflow/alarms.py,sha256=YXL_tbhT37t43u31NpfiWcE6wHqU35iAiYaTsXbD7nw,2044
3
+ icuflow/calibration.py,sha256=ARQU3fbipxZ0ZjOCZcLBBFm5H4wpypkxEmcwNv4n41E,3378
4
+ icuflow/cli.py,sha256=SkO25QdUcXzO0nqL3wQLpTeoQ-XiuNe1HAwK_Ze59q4,2409
5
+ icuflow/splits.py,sha256=7C8JOeAwH8mG5A1mtZJYUcQR99j7yZ9rb560v7ZwX00,2183
6
+ icuflow/tasks.py,sha256=_aMfkrXGNtDa_tdEBzckUbm3drDRasfXeoZqrIjyO0w,2069
7
+ icuflow-0.1.0.dist-info/METADATA,sha256=2qzNaBPSyvLkEmpTVoDeKZVIhOS9iQJbDpgGT7K-HRA,4335
8
+ icuflow-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
9
+ icuflow-0.1.0.dist-info/entry_points.txt,sha256=sineV8ZnaOPaBT1ijavQk-xLjmlkGZfxfnN0NuZHFZ4,45
10
+ icuflow-0.1.0.dist-info/top_level.txt,sha256=aYSQacuZ3d2sd0_dLJE5_lki39UVRkTdsCXaJXgCofg,8
11
+ icuflow-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ icuflow = icuflow.cli:main
@@ -0,0 +1 @@
1
+ icuflow