From ff7142f4842629dfcb80b398a09cd8ed682d889e Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 1/6] docs(mimic-iii): explain SpO2 itemids 646 vs 220277 Answer #1957: zero rows are often CareVue/MetaVision mix, not missing SpO2. Co-authored-by: Cursor --- mimic-iii/docs/SPO2.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 mimic-iii/docs/SPO2.md diff --git a/mimic-iii/docs/SPO2.md b/mimic-iii/docs/SPO2.md new file mode 100644 index 00000000..fd1038bd --- /dev/null +++ b/mimic-iii/docs/SPO2.md @@ -0,0 +1,33 @@ +# SpO2 / oxygen saturation in MIMIC-III + +Neonatal and adult ICU cohorts often look for pulse oximetry SpO2 in +`chartevents`. Zero rows for a cohort usually means **itemid / carevue vs +metavision mismatch** or an empty window — not a missing “SpO2 table.” + +See [issue #1957](https://github.com/MIT-LCP/mimic-code/issues/1957). + +## Common itemids + +| ITEMID | Label (approx.) | Notes | +|--------|-----------------|-------| +| 646 | SpO2 | CareVue-era charting | +| 220277 | O2 saturation pulseoxymetry | MetaVision-era charting | + +MIMIC-III mixes CareVue and MetaVision stays. A neonatal sepsis cohort that +only hits one era can legitimately return **zero** rows for the other itemid. + +## Practical guidance + +1. Query **both** 646 and 220277 (and inspect `d_items` for related O2 sat + labels) before concluding data are missing. +2. Drop first-day / sepsis filters temporarily to confirm the itemids fire at + all for your `icustay_id` set. +3. For **arterial** saturation, look in `labevents` (SaO2 / ABG panels), which + is a different concept from pulse ox SpO2. +4. MIMIC-IV uses a different `itemid` namespace (`icu.d_items`); do not reuse + 646/220277 there without checking the IV dictionary. + +## Related + +- MIMIC-IV chartevents timing: `mimic-iv/docs/CHARTEVENTS_TIMING.md` (when present) +- Oxygen delivery device rows: concepts under `measurement/oxygen_delivery` From 73c9d835d9a321044a78fd2bf5f9abe966c8728e Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 2/6] docs: link README(s) to MIMIC-III SpO2 notes Surface #1957 from module and repository entrypoints. Co-authored-by: Cursor --- README.md | 4 ++++ mimic-iii/README.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/README.md b/README.md index 53fe9f9f..fae79fe1 100644 --- a/README.md +++ b/README.md @@ -114,3 +114,7 @@ By committing your code to the [MIMIC Code Repository](https://github.com/mit-lc ### Coding style Please refer to the [style guide](https://github.com/MIT-LCP/mimic-code/blob/main/styleguide.md) for guidelines on formatting your code for the repository. + +### MIMIC-III notes + +- [SpO2 itemids](mimic-iii/docs/SPO2.md) diff --git a/mimic-iii/README.md b/mimic-iii/README.md index 4a4c5445..ea5f2fba 100644 --- a/mimic-iii/README.md +++ b/mimic-iii/README.md @@ -17,3 +17,7 @@ The repository is organized as follows: * [tutorials](/mimic-iii/tutorials) - Similar to the notebooks folder, but focuses on explaining concepts to new users \* A Makefile build system has been created to facilitate the building of the MIMIC database, and optionally contributed views from the community. Please refer to the [Makefile guide](/mimic-iii/Makefile.md) for more details. + +## SpO2 / oxygen saturation + +See [docs/SPO2.md](docs/SPO2.md) for CareVue vs MetaVision itemids (#1957). From ce8d112cf01fff52da29cac805be927824f3a712 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 3/6] docs(mimic-iii): add documentation helper-query folder Home for #1957 availability SQL outside derived concepts. Co-authored-by: Cursor --- mimic-iii/concepts/documentation/README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 mimic-iii/concepts/documentation/README.md diff --git a/mimic-iii/concepts/documentation/README.md b/mimic-iii/concepts/documentation/README.md new file mode 100644 index 00000000..b6d8d4a6 --- /dev/null +++ b/mimic-iii/concepts/documentation/README.md @@ -0,0 +1,4 @@ +# Documentation helper queries (MIMIC-III) + +Ad-hoc SQL for data-availability questions. Not part of the official derived +concept build. From 47f163af96222a29913b326ee3709594a2309ff1 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 4/6] docs(mimic-iii): add SpO2 itemid availability count query Give #1957 reporters a concrete CareVue vs MetaVision check. Co-authored-by: Cursor --- .../concepts/documentation/spo2_itemid_counts.sql | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 mimic-iii/concepts/documentation/spo2_itemid_counts.sql diff --git a/mimic-iii/concepts/documentation/spo2_itemid_counts.sql b/mimic-iii/concepts/documentation/spo2_itemid_counts.sql new file mode 100644 index 00000000..590f085b --- /dev/null +++ b/mimic-iii/concepts/documentation/spo2_itemid_counts.sql @@ -0,0 +1,11 @@ +-- Count SpO2-like chartevents for CareVue (646) vs MetaVision (220277). +-- Useful when a neonatal cohort returns 0 rows for one era (#1957). + +SELECT + ce.itemid, + COUNT(*) AS n_rows, + COUNT(DISTINCT ce.icustay_id) AS n_stays +FROM mimiciii.chartevents AS ce +WHERE ce.itemid IN (646, 220277) +GROUP BY ce.itemid +ORDER BY ce.itemid; From 8b74987cf5f282547f9d3bde199590b5f9346af7 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 5/6] docs(mimic-iii): sample SpO2 pull for a stay list Help validate #1957 cohorts before blaming missing pulse ox. Co-authored-by: Cursor --- mimic-iii/concepts/documentation/spo2_for_icustays.sql | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 mimic-iii/concepts/documentation/spo2_for_icustays.sql diff --git a/mimic-iii/concepts/documentation/spo2_for_icustays.sql b/mimic-iii/concepts/documentation/spo2_for_icustays.sql new file mode 100644 index 00000000..f86bc9aa --- /dev/null +++ b/mimic-iii/concepts/documentation/spo2_for_icustays.sql @@ -0,0 +1,8 @@ +-- Template: SpO2 rows for a list of icustay_id values (both common itemids). + +SELECT ce.icustay_id, ce.itemid, ce.charttime, ce.valuenum, ce.valueuom +FROM mimiciii.chartevents AS ce +WHERE ce.itemid IN (646, 220277) + AND ce.icustay_id IN (/* your icustay_id list */) +ORDER BY ce.icustay_id, ce.charttime +LIMIT 100; From 25e0ca45fec5b5cbfe62e5c3e4cb2ea7af07bafd Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:50:52 +0300 Subject: [PATCH 6/6] docs(mimic-iii): clarify we will not invent a silent SpO2 merge table Keep #1957 guidance as documentation, not a hidden ETL rewrite. Co-authored-by: Cursor --- mimic-iii/docs/SPO2.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/mimic-iii/docs/SPO2.md b/mimic-iii/docs/SPO2.md index fd1038bd..5fa45275 100644 --- a/mimic-iii/docs/SPO2.md +++ b/mimic-iii/docs/SPO2.md @@ -31,3 +31,10 @@ only hits one era can legitimately return **zero** rows for the other itemid. - MIMIC-IV chartevents timing: `mimic-iv/docs/CHARTEVENTS_TIMING.md` (when present) - Oxygen delivery device rows: concepts under `measurement/oxygen_delivery` + +## What this repository will not change + +We will not invent a unified “neonatal SpO2” derived table that silently merges +eras without documenting itemids. Prefer explicit `IN (646, 220277)` (plus any +extra labels you validate) in analysis code. +