Metadata-Version: 2.4
Name: mimic-event-stream
Version: 0.1.0
Summary: Role-tagged, causally-ordered clinical event streams from MIMIC-IV and EHRSHOT.
Keywords: mimic,mimic-iv,ehrshot,omop,clinical,ehr,event-stream,healthcare
Author-email: Josh Freeman <freemanjosh1000@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=12.0
Requires-Dist: duckdb>=1.5
Requires-Dist: pytest>=7 ; extra == "dev"
Project-URL: Homepage, https://github.com/josh-freeman/mimic-event-stream
Project-URL: Issues, https://github.com/josh-freeman/mimic-event-stream/issues
Project-URL: Repository, https://github.com/josh-freeman/mimic-event-stream
Provides-Extra: dev

# 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

```bash
pip install mimic-event-stream
```

## Quick start

```python
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):

```python
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):

```python
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

```bash
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.

