diff --git a/README.md b/README.md index 53fe9f9f..5e9bb148 100644 --- a/README.md +++ b/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) diff --git a/mimic-iv/README.md b/mimic-iv/README.md index 919b196c..42231b91 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, `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 diff --git a/mimic-iv/buildmimic/TABLE_NOTES.md b/mimic-iv/buildmimic/TABLE_NOTES.md new file mode 100644 index 00000000..6f680d15 --- /dev/null +++ b/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). 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). +