docs(mimic-iv): table notes for race, OMR units, and d_labitems

README.md

@@ -19,7 +19,7 @@ This repository contains code for the following databases on PhysioNet:
 - 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
 
-The repository contains one top-level folder containing community developed code for each datasets:
+The repository contains one top-level folder containing community developed code for each dataset:
 
 - [mimic-iii](/mimic-iii) - build scripts for MIMIC-III, derived concepts which are available on the `physionet-data.mimiciii_derived` dataset on BigQuery, and tutorials.
 - [mimic-iv](/mimic-iv) - build scripts for MIMIC-IV, derived concepts which are available on release-specific datasets such as `physionet-data.mimiciv_3_1_derived` on BigQuery, and tutorials.
@@ -34,7 +34,7 @@ Each subfolder has a README with further detail regarding its content.
 
 MIMIC-III is available on AWS (and MIMIC-IV will be available in the future). Use the below Launch Stack button to deploy access to the MIMIC-III dataset into your AWS account.  This will give you real-time access to the MIMIC-III data in your AWS account without having to download a copy of the MIMIC-III dataset.  It will also deploy a Jupyter Notebook with access to the content of this GitHub repository in your AWS account.    Prior to launching this, please login to the [MIMIC PhysioNet website](https://mimic.mit.edu/), [input your AWS account number](https://physionet.org/settings/cloud/), and [request access to the MIMIC-III Clinical Database on AWS](https://physionet.org/projects/mimiciii/1.4/request_access/2).  
 
-To start this deployment, click the Launch Stack button.  On the first screen, the template link has already been specified, so just click next.  On the second screen, provide a Stack name (letters and numbers) and click next, on the third screen, just click next.  On the forth screen, at the bottom, there is a box that says **I acknowledge that AWS CloudFormation might create IAM resources.**.  Check that box, and then click **Create**.  Once the Stack has complete deploying, look at the **Outputs** tab of the AWS CloudFormation console for links to your Jupyter Notebooks instance.
+To start this deployment, click the Launch Stack button.  On the first screen, the template link has already been specified, so just click next.  On the second screen, provide a Stack name (letters and numbers) and click next, on the third screen, just click next.  On the fourth screen, at the bottom, there is a box that says **I acknowledge that AWS CloudFormation might create IAM resources.**.  Check that box, and then click **Create**.  Once the Stack has complete deploying, look at the **Outputs** tab of the AWS CloudFormation console for links to your Jupyter Notebooks instance.
 
 [![cloudformation-launch-stack](/mimic-iii/buildmimic/aws-athena/cloudformation-launch-stack.png)](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=MIMIC&templateURL=https://aws-bigdata-blog.s3.amazonaws.com/artifacts/biomedical-informatics-studies/mimic-iii-athena.yaml)
 

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, `d_labitems`, qualitative lab `NEG`/`POS` values, and `labevents.valueuom` drift.
 * [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

mimic-iv/buildmimic/TABLE_NOTES.md

@@ -0,0 +1,86 @@
+# 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).
+
+## `labevents` qualitative `NEG` / `POS` values
+
+Many lab rows are qualitative rather than numeric. In those cases:
+
+- `valuenum` is often **null**
+- `value` (and sometimes `comments`) holds a categorical result such as `NEG`, `POS`, `NEGATIVE`, or `POSITIVE`
+
+Treat `NEG` / `NEGATIVE` as a **valid negative finding** for that assay (for example, little or no glucose detected on a urine dipstick), not as a failed or missing test. The same applies when `value` is null but `comments` contains `NEG.` — that comment is still the recorded result.
+
+Numeric analyses should filter on `valuenum IS NOT NULL` (and usually a sensible `valueuom`) so qualitative rows are excluded deliberately rather than dropped as errors.
+
+See also: [GitHub issue #1938](https://github.com/MIT-LCP/mimic-code/issues/1938).
+
+## `labevents.valueuom` inconsistency for some itemids
+
+For a given `itemid`, `valueuom` is usually stable, but a minority of rows use a different unit string (or null) than the majority. Reported examples include:
+
+| `itemid` | Common unit | Also seen |
+| --- | --- | --- |
+| `51249` (MCHC) | `g/dL` | `%` |
+| `50889` (C-Reactive Protein) | `mg/L` | null / blank |
+
+This is a source-data / charting inconsistency, not a join bug. Practical approaches:
+
+1. Prefer rows whose `valueuom` matches the modal unit for that `itemid` (concept scripts often do this).
+2. Convert carefully when units are known equivalents; do **not** mix `%` and `g/dL` for MCHC without a validated conversion.
+3. Treat blank `valueuom` as unknown rather than assuming the dictionary default.
+
+See also: [GitHub issue #1922](https://github.com/MIT-LCP/mimic-code/issues/1922).

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).
+
 <!-- 
 * You can follow the tutorial to run each file individually. Windows users can follow along [here](https://mimic.mit.edu/docs/gettingstarted/local/install-mimic-locally-windows.html), while *nix/Mac OS X users can follow along [here](https://mimic.mit.edu/docs/gettingstarted/local/install-mimic-locally-ubuntu.html)