docs(mimic-iii): SpO2 itemids for CareVue vs MetaVision (#1957)

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)

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).

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.

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;

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;

mimic-iii/docs/SPO2.md

@@ -0,0 +1,40 @@
+# 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`
+
+## 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.
+