docs(mimic-iv-ed): timing notes for pyxis/prescriptions vs edstays.intime (#1910)

README.md

@@ -16,6 +16,7 @@ This repository contains code for the following databases on PhysioNet:
 - [MIMIC-IV](https://physionet.org/content/mimiciv/) - hospital and critical care data for patients admitted to the ED or ICU between 2008 - 2019
 - [MIMIC-IV-Note](https://physionet.org/content/mimic-iv-note) - deidentified free-text clinical notes
 - [MIMIC-IV-ED](https://physionet.org/content/mimic-iv-ed/) - emergency department data for individuals attending the ED between 2011 - 2019
+- [ED timing caveats](mimic-iv-ed/docs/TIMING_NOTES.md) — pyxis/prescription times vs `edstays.intime`
 - MIMIC-IV Waveforms (TBD) - this dataset has yet to be published.
 - [MIMIC-CXR](https://physionet.org/content/mimic-cxr/) - chest x-ray imaging and deidentified free-text radiology reports for patients admitted to the ED from 2012 - 2016
 

mimic-iv-ed/README.md

@@ -1,3 +1,7 @@
 # MIMIC-IV-ED
 
-MIMIC-IV-ED is a publicly available database of emergency department visit data. You can read more about the dataset on [the PhysioNet project page](https://mimic.mit.edu/docs/iv/modules/ed/).
+MIMIC-IV-ED is a publicly available database of emergency department visit data. You can read more about the dataset on [the PhysioNet project page](https://mimic.mit.edu/docs/iv/modules/ed/).
+
+## Timing caveats
+
+`edstays.intime` is an administrative ED registration time. Pyxis and prescription timestamps can legitimately fall slightly before that window — see [docs/TIMING_NOTES.md](docs/TIMING_NOTES.md).

mimic-iv-ed/concepts/README.md

@@ -0,0 +1,5 @@
+# MIMIC-IV-ED helper concepts
+
+Small documentation-oriented queries that illustrate known data quirks.
+These are **not** part of the official MIMIC-IV derived concept build
+(`mimic-iv/concepts`); run them ad hoc against a local or BigQuery copy.

mimic-iv-ed/concepts/prescriptions_near_edstay.sql

@@ -0,0 +1,18 @@
+-- Flag hospital prescriptions near an ED stay whose starttime precedes intime.
+-- Join is intentionally loose (subject_id + hadm_id) — same caveat as #1910.
+
+SELECT
+  e.stay_id,
+  e.intime,
+  e.outtime,
+  pr.starttime,
+  pr.stoptime,
+  pr.drug
+FROM ed.edstays AS e
+INNER JOIN hosp.prescriptions AS pr
+  ON e.subject_id = pr.subject_id
+ AND e.hadm_id IS NOT DISTINCT FROM pr.hadm_id
+WHERE pr.starttime < e.intime
+  AND pr.starttime >= e.intime - INTERVAL '6 hours'
+ORDER BY e.stay_id, pr.starttime
+LIMIT 100;

mimic-iv-ed/concepts/pyxis_before_intime.sql

@@ -0,0 +1,14 @@
+-- Count Pyxis rows whose charttime falls before the linked ED stay intime.
+-- Useful as a sensitivity check when building ED medication cohorts (#1910).
+-- Dialect: PostgreSQL / BigQuery-compatible with minor cast tweaks.
+
+SELECT
+  COUNT(*) AS pyxis_rows,
+  COUNT(*) FILTER (WHERE p.charttime < e.intime) AS before_intime,
+  COUNT(*) FILTER (
+    WHERE p.charttime < e.intime
+      AND p.charttime >= e.intime - INTERVAL '2 hours'
+  ) AS before_intime_within_2h
+FROM ed.pyxis AS p
+INNER JOIN ed.edstays AS e
+  ON p.stay_id = e.stay_id;

mimic-iv-ed/docs/TIMING_NOTES.md

@@ -0,0 +1,71 @@
+# MIMIC-IV-ED timing caveats
+
+Researchers sometimes see `ed.pyxis.charttime` or `hosp.prescriptions.starttime`
+values that fall **before** `ed.edstays.intime` for the same stay. That pattern
+is expected in the raw data and is usually **not** a join bug.
+
+This note summarizes how those clocks differ and how to treat them. It does not
+change any ETL scripts — only documents behavior already present in the public
+files. See also [issue #1910](https://github.com/MIT-LCP/mimic-code/issues/1910).
+
+## Clocks involved
+
+| Source | Column(s) | What it usually represents |
+|--------|-----------|----------------------------|
+| `ed.edstays` | `intime` / `outtime` | ED stay registration window from the ADT / ED tracking system |
+| `ed.pyxis` | `charttime` | Pyxis (automated dispensing cabinet) event time |
+| `hosp.prescriptions` | `starttime` / `stoptime` | Order start/stop as recorded in the pharmacy / order system |
+| `ed.medrecon` | `charttime` | Medication reconciliation documentation time |
+| `ed.vitalsign` | `charttime` | Documented vital-sign observation time |
+
+These systems are **not** forced onto a single synchronized clock in the
+released tables. Small negative offsets (event slightly before `intime`) are
+common; large offsets need case-by-case review.
+
+## Why events can precede `edstays.intime`
+
+Common, non-exclusive explanations:
+
+1. **Registration lag.** Care (triage meds, Pyxis pulls) can start before the
+   ED stay row is fully registered, so ADT `intime` is later than the clinical
+   action.
+2. **System clocks differ.** Pyxis, pharmacy, and ADT may stamp with different
+   device or server times; MIMIC does not re-align them.
+3. **Order times ≠ administration times.** `prescriptions.starttime` is an
+   **order** time. It can be entered retrospectively, copied from prior orders,
+   or set for a planned start that is not the first Pyxis dispense.
+4. **Linkage across modules.** Joining ED stays to `hosp.prescriptions` via
+   `subject_id` / `hadm_id` can pull hospital-ward orders that are temporally
+   near the ED window but not strictly inside it.
+
+None of these are labeled in the public schema as "manual" vs "automatic" — the
+tables do not expose that provenance flag.
+
+## Practical guidance
+
+- Treat `edstays.intime`/`outtime` as the **administrative** ED window, not a
+  hard clinical filter that every charted event must satisfy.
+- Prefer `ed.pyxis.charttime` when studying **dispensing** in the ED; prefer
+  `prescriptions` when studying **orders**; do not assume they agree.
+- If you need "events during the ED stay," decide explicitly whether to:
+  - keep events with `charttime < intime` within a small tolerance (e.g. 1–2 h),
+  - drop them, or
+  - flag them for sensitivity analysis.
+- Do **not** rewrite `intime` from the earliest Pyxis time without documenting
+  the rule — that invents a derived stay definition.
+
+## Related reading
+
+- PhysioNet MIMIC-IV ED module overview: <https://mimic.mit.edu/docs/iv/modules/ed/>
+- Table pages for `edstays` and `pyxis` under that module
+- Analogous ICU charting lag is discussed for `chartevents` (events after
+  `outtime` / before `intime` appear in raw ICU data as well)
+
+## What this repository will not change
+
+MIMIC-Code does **not** rewrite `edstays.intime` from Pyxis or prescription
+minima. Correcting institutional clock skew belongs in a derived concept with
+an explicit rule, not in the build scripts that load the PhysioNet CSV files.
+Questions about BIDMC bedside workflow beyond what the tables encode belong on
+the PhysioNet forum, not as silent ETL patches here.
+