mimic-event-stream 0.1.0

Role-tagged, causally-ordered clinical event streams from MIMIC-IV and EHRSHOT.

mimic-event-stream

Turn per-table clinical records into one causally-ordered, role-tagged event stream per patient — every event tagged condition (a measurement), action (an intervention), or label (a clinician inference) — with an admission-scoped leakage guard. MIMIC-IV and EHRSHOT (OMOP) share one Event model and ordering.

The package contains code only — no patient data. MIMIC-IV and EHRSHOT are separately licensed (PhysioNet credentialed access / EHRSHOT DUA); point the loader at your own licensed copy.

Install

pip install mimic-event-stream

Quick start

from mimic_event_stream import DemoLoader, build_stream, render_timeline

loader = DemoLoader(root="/path/to/mimic-iv-clinical-database-demo")
stream = build_stream(loader, subject_id=loader.subject_ids[0])
for ev in stream[:20]:
    print(ev.event_time, ev.role.name, ev.value)

print(render_timeline(loader, loader.subject_ids[0], max_events=40))

EHRSHOT (OMOP flat timeline):

from mimic_event_stream import build_ehrshot_stream, load_ehrshot_patient

rows = load_ehrshot_patient("EHRSHOT_ASSETS/data/ehrshot.csv", patient_id=123)
stream = build_ehrshot_stream(rows, patient_id=123)

Point the loader with the WMB_MIMIC4_DEMO_DIR env var, or pass root= directly. For full MIMIC-IV (18 GB labevents, 40 GB chartevents), use the size-agnostic DuckDBLoader (subject-filtered scans, Parquet-cached):

from mimic_event_stream.duckdb_loader import DuckDBLoader, sample_icu_subjects

subjects = sample_icu_subjects("/path/to/mimic-iv", n=200)
loader = DuckDBLoader("/path/to/mimic-iv", subjects, cache_dir="/scratch/cache")

The Event model

Each Event carries subject_id, visit_id, event_time, an honest time_resolution, a role (condition < action < label on ties), the source table, and a pre-rendered value. Events sort by (event_time, resolution, role, source, seq) for a deterministic causal order; admission-level labels are re-anchored after the last real event of their admission so a discharge diagnosis can never precede a same-admission measurement (the leakage guard).

Development

git clone https://github.com/josh-freeman/mimic-event-stream
cd mimic-event-stream
uv sync --extra dev
WMB_MIMIC4_DEMO_DIR=/path/to/demo pytest tests/ -q

The repository also contains research code under tte/ (bulk QA benchmarks, RL) and recommendation_qa/ — these are not part of the published package.

License

MIT (code only — see LICENSE). Not affiliated with or endorsed by PhysioNet or MIT-LCP.