feature: MIMIC-IV Replay Scenario Generator

2026-06-25 13:35:09 +08:00
parent 069881991a
commit a8964381a2
29 changed files with 916019 additions and 8 deletions
@@ -18,6 +18,7 @@ Think of it as a flight simulator, but for clinical decision support.
 8. [Creating Your Own Scenarios](#8-creating-your-own-scenarios)
 9. [Troubleshooting](#9-troubleshooting)
 10. [Ward Outage Scenario (Climate Resilience)](#10-ward-outage-scenario-climate-resilience)
+11. [MIMIC-IV Real Patient Data](#11-mimic-iv-real-patient-data)

 ---

@@ -61,7 +62,7 @@ That's it! Read on for more detail.

 ## 3. Available Commands

-The simulator has four commands. All are run with `dotnet run --project VigilCare.Simulator -- <command>`.
+The simulator has six commands. All are run with `dotnet run --project VigilCare.Simulator -- <command>`.

 ### replay -- Run a scenario against the API

@@ -137,6 +138,62 @@ dotnet run --project VigilCare.Simulator -- dry-run \
  VigilCare.Simulator/Scenarios/List/cardiac-arrest-post-mi-01.json
 ```

+### mimic-list -- Browse available MIMIC-IV patients and ICU stays
+
+```bash
+dotnet run --project VigilCare.Simulator -- mimic-list <mimic-data-dir> [options]
+```
+
+Displays a table of all ICU stays in the MIMIC-IV dataset with patient demographics, care unit, length of stay, and outcome. Does **not** contact the API.
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--subject-id <int>` | Filter to a specific patient |
+| `--stay-id <int>` | Filter to a specific ICU stay |
+
+**Example:**
+
+```bash
+dotnet run --project VigilCare.Simulator -- mimic-list docs/MIMIC-IV/
+```
+
+### mimic-generate -- Generate a scenario from real MIMIC-IV data
+
+```bash
+dotnet run --project VigilCare.Simulator -- mimic-generate <mimic-data-dir> --stay-id <int> [options]
+```
+
+Reads MIMIC-IV CSV files and generates a VigilCare scenario JSON from a specific ICU stay. The generated file is fully compatible with `replay`, `validate`, and `dry-run`. Does **not** contact the API.
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--stay-id <int>` | (required) | ICU stay ID to generate scenario for |
+| `--max-hours <int>` | full stay | Limit scenario duration (real ICU stays can be days/weeks) |
+| `--no-medications` | off | Exclude medication events |
+| `--no-labs` | off | Exclude lab observations |
+| `--output <path>` | `Scenarios/List/mimic-s{stayId}.json` | Custom output file path |
+| `--validate` | off | Run scenario validation after generation |
+
+**Example -- generate a 24-hour CVICU scenario:**
+
+```bash
+dotnet run --project VigilCare.Simulator -- mimic-generate docs/MIMIC-IV/ \
+  --stay-id 32604416 --max-hours 24 --validate
+```
+
+Then replay it:
+
+```bash
+dotnet run --project VigilCare.Simulator -- replay \
+  VigilCare.Simulator/Scenarios/List/mimic-s32604416.json --speed 0 --poll
+```
+
+See [MIMIC-IV Real Patient Data](#11-mimic-iv-real-patient-data) for the full guide.
+
 ---

 ## 4. Understanding Scenarios
@@ -489,3 +546,75 @@ The `--gateway` flag targets `http://localhost:5081` automatically. `--encounter
 - Critical potassium alert created on gateway at T+45 min while central is down
 - Ack recorded locally at T+50 min with `acknowledged_by` = `RN-Wu`
 - After reconnect: central has observations, alert, and ack; no duplicate paging logs
+
+---
+
+## 11. MIMIC-IV Real Patient Data
+
+The simulator can generate scenarios from **real de-identified ICU data** from MIT's MIMIC-IV dataset (PhysioNet). This bridges the gap from synthetic scenarios to actual clinical records — a critical validation step for scoring engines and alert logic.
+
+The MIMIC-IV CSV files in `docs/MIMIC-IV/` contain 100 patients, 140 ICU stays, 668K chart events, and 107K lab events. The generator reads these files and produces standard scenario JSON files that replay through VigilCare's full scoring pipeline (NEWS2, SOFA, GCS, qSOFA, trend detection, alerting).
+
+### Quick start
+
+```bash
+# 1. Browse available ICU stays
+dotnet run --project VigilCare.Simulator -- mimic-list docs/MIMIC-IV/
+
+# 2. Generate a 24-hour scenario from a CVICU patient
+dotnet run --project VigilCare.Simulator -- mimic-generate docs/MIMIC-IV/ \
+  --stay-id 32604416 --max-hours 24 --validate
+
+# 3. Preview the timeline
+dotnet run --project VigilCare.Simulator -- dry-run \
+  VigilCare.Simulator/Scenarios/List/mimic-s32604416.json
+
+# 4. Replay against the live API
+dotnet run --project VigilCare.Simulator -- replay \
+  VigilCare.Simulator/Scenarios/List/mimic-s32604416.json --speed 0 --poll
+```
+
+### What gets generated
+
+The generator maps MIMIC-IV data to VigilCare observations:
+
+| MIMIC Source | VigilCare Codes |
+|---|---|
+| **Vital signs** (chartevents) | HEART_RATE, RESP_RATE, SYSTOLIC_BP, DIASTOLIC_BP, TEMP_C, SPO2, FIO2_PCT |
+| **GCS** (chartevents, text labels) | GCS_EYE, GCS_VERBAL, GCS_MOTOR |
+| **Labs** (labevents) | CREATININE_MG_DL, PLATELET_K_UL, BILIRUBIN_MG_DL, LACTATE_MMOL_L, WBC_K_UL, POTASSIUM_MEQ_L, GLUCOSE_MG_DL, PAO2_MMHG |
+| **Prescriptions** | Medication events (drug name, dose, route) |
+
+The generated scenario has no `expectedOutcomes` — these are exploratory replays. The alerts and scores that fire are the real output, driven by actual patient trajectories.
+
+### Useful options
+
+| Option | Effect |
+|--------|--------|
+| `--max-hours 24` | Cap the scenario at 24 hours (real ICU stays can be weeks) |
+| `--no-medications` | Exclude medication events for a cleaner vitals-only replay |
+| `--no-labs` | Exclude lab observations (vitals + GCS only) |
+| `--validate` | Run `ScenarioValidator` after generation and print results |
+| `--output my-file.json` | Write to a custom path instead of `Scenarios/List/` |
+
+### Data handling notes
+
+- **GCS:** MIMIC stores GCS as text labels ("Obeys Commands", "To Speech", etc.). The generator reads the numeric `valuenum` column; if missing, falls back to a text-to-numeric lookup dictionary.
+- **Temperature:** Fahrenheit readings (item 223761) are converted to Celsius. Celsius readings (item 223762) pass through.
+- **Blood pressure:** When both non-invasive (NBP) and arterial (ABP) readings exist at the same time, the generator keeps non-invasive and discards arterial. ABP is used only when no NBP is available.
+- **Cluster limits:** The VigilCare API accepts at most 10 observations per batch. When a MIMIC timestamp has more than 10 readings, the generator keeps vital signs first and spills labs to the next minute offset.
+- **Patient identity:** De-identified names (`MIMIC-{subjectId}` / `S{hadmId}`). Date of birth approximated from `anchor_age` and `anchor_year`.
+
+### Finding interesting patients
+
+Use `mimic-list` with filters to find specific cases:
+
+```bash
+# Find all stays for a specific patient
+dotnet run --project VigilCare.Simulator -- mimic-list docs/MIMIC-IV/ --subject-id 10005817
+
+# Look for a specific stay
+dotnet run --project VigilCare.Simulator -- mimic-list docs/MIMIC-IV/ --stay-id 32604416
+```
+
+The table shows care unit, length of stay, and whether the patient expired -- useful for finding clinically interesting trajectories to replay.