From c88749bd8bf90dfb0c0e58ebc32b2ffdc742f521 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 13:15:55 +0300 Subject: [PATCH 1/6] docs(mimic-iv): add TABLE_NOTES for race, OMR units, and d_labitems Documents admissions.race (not ethnicity), OMR unit conventions, and d_labitems duplicate/Delete rows. Addresses #1919, #1918, and #1937. Co-authored-by: Cursor --- mimic-iv/buildmimic/TABLE_NOTES.md | 56 ++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 mimic-iv/buildmimic/TABLE_NOTES.md diff --git a/mimic-iv/buildmimic/TABLE_NOTES.md b/mimic-iv/buildmimic/TABLE_NOTES.md new file mode 100644 index 00000000..1643f593 --- /dev/null +++ b/mimic-iv/buildmimic/TABLE_NOTES.md @@ -0,0 +1,56 @@ +# MIMIC-IV table notes + +Supplementary documentation for common questions about MIMIC-IV hosp tables. +These notes complement the [MIMIC-IV website documentation](https://mimic.mit.edu/docs/iv/modules/hosp/). + +## `admissions.race` (not `ethnicity`) + +MIMIC-IV stores patient race in the **`race`** column of `mimiciv_hosp.admissions`. +MIMIC-III used an `ethnicity` column for a similar purpose; MIMIC-IV renamed the field +to `race` to reflect the underlying source data. + +Some older website text incorrectly referred to this field as `ethnicity` under the +insurance/language/marital status section. The column name in the CSV files, PostgreSQL +schema, and BigQuery tables is **`race`**. + +See also: [GitHub issue #1919](https://github.com/MIT-LCP/mimic-code/issues/1919). + +## `omr` measurement units + +The `omr` table stores outpatient measurements (BMI, height, weight, blood pressure, +and related vitals). Units are **not** stored in a separate column; they are implied +by `result_name`. + +| `result_name` pattern | Unit for `result_value` | +| --- | --- | +| `BMI (kg/m2)` | kg/m² | +| `Height (Inches)` | inches | +| `Weight (Lbs)` | pounds (lbs) | +| `Blood Pressure` | mmHg (systolic/diastolic in `result_value`, e.g. `120/80`) | +| `BMI` | kg/m² (same as the parenthetical form) | +| `Height` | inches (same as `Height (Inches)`) | +| `Weight` | pounds (same as `Weight (Lbs)`) | + +The short forms (`BMI`, `Height`, `Weight`) are legacy aliases for the same +measurements as the parenthetical names. When both appear for a patient, prefer the +row whose `result_name` includes the unit in parentheses for clarity. + +See also: [GitHub issue #1918](https://github.com/MIT-LCP/mimic-code/issues/1918). + +## `d_labitems` duplicate labels and "Delete" rows + +`d_labitems` is a dictionary table: each `itemid` identifies a distinct lab concept +in `labevents`. **Different itemids with the same label, fluid, and category are not +guaranteed to be interchangeable.** They often reflect distinct source codes that were +mapped separately during ETL, retired concepts, or corrected definitions. + +Rows whose label is **`Delete`** are placeholders for itemids that were removed or +deprecated in the source system. They may still appear in `labevents` for historical +records. Do not treat "Delete" as a clinically meaningful lab name; inspect +`labevents` for the corresponding `itemid` or consult `d_labitems` for the fluid and +category context. + +When harmonizing labs across itemids, compare value distributions and `valueuom` in +`labevents` rather than assuming semantic equivalence from the dictionary label alone. + +See also: [GitHub issue #1937](https://github.com/MIT-LCP/mimic-code/issues/1937). From 4e61bc2d48978af7d7b6b5ef424b99dbe903b322 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 13:15:55 +0300 Subject: [PATCH 2/6] docs(mimic-iv): link build READMEs to TABLE_NOTES Co-authored-by: Cursor --- mimic-iv/README.md | 2 +- mimic-iv/buildmimic/postgres/README.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/mimic-iv/README.md b/mimic-iv/README.md index 919b196c..76e5de54 100644 --- a/mimic-iv/README.md +++ b/mimic-iv/README.md @@ -1,6 +1,6 @@ # MIMIC-IV Concepts -* [buildmimic](/mimic-iv/buildmimic) - Scripts to build MIMIC-IV in various relational database management system (RDMS), in particular [postgres](/mimic-iv/buildmimic/postgres) is a popular open source option +* [buildmimic](/mimic-iv/buildmimic) - Scripts to build MIMIC-IV in various relational database management systems (RDBMS), in particular [postgres](/mimic-iv/buildmimic/postgres) is a popular open source option. See [TABLE_NOTES.md](/mimic-iv/buildmimic/TABLE_NOTES.md) for notes on `race`, OMR units, and `d_labitems`. * [concepts](/mimic-iv/concepts) - SQL scripts to extract data from MIMIC-IV including demographics, organ failure scores, severity of illness scores, durations of treatment, and so on. These concepts are written in the BigQuery dialect. * [concepts_postgres](/mimic-iv/concepts_postgres) - above concepts converted to the PostgreSQL dialect * [concepts_duckdb](/mimic-iv/concepts_duckdb) - above concepts converted to the DuckDB dialect diff --git a/mimic-iv/buildmimic/postgres/README.md b/mimic-iv/buildmimic/postgres/README.md index 5ab28c2c..189975ac 100644 --- a/mimic-iv/buildmimic/postgres/README.md +++ b/mimic-iv/buildmimic/postgres/README.md @@ -3,6 +3,9 @@ The scripts in this folder create the schema for MIMIC-IV and load the data into the appropriate tables for PostgreSQL v10+. If you are having trouble, take a look at the common issues in the FAQ at the bottom of this page. +For notes on commonly asked questions about `admissions.race`, `omr` units, and +`d_labitems` duplicates, see [TABLE_NOTES.md](../TABLE_NOTES.md). +