From 095074d7dab4dcf1fedf5cf421e8fa30b582ebc3 Mon Sep 17 00:00:00 2001 From: Alistair Johnson Date: Sat, 2 May 2026 22:36:45 -0400 Subject: [PATCH 1/2] port over content --- docs/IV/about/schema-overview.md | 149 +++++++++++++++++++++++++++++++ docs/IV/index.md | 5 +- docs/IV/modules/note/index.md | 16 +++- docs/IV/tutorials/first-query.md | 114 +++++++++++++++++++++++ docs/faq/data.md | 61 +++++++++++++ docs/faq/how-to-get-access.md | 88 ++++++++++++++++++ docs/faq/index.md | 20 +++++ 7 files changed, 445 insertions(+), 8 deletions(-) create mode 100644 docs/IV/about/schema-overview.md create mode 100644 docs/IV/tutorials/first-query.md create mode 100644 docs/faq/data.md create mode 100644 docs/faq/how-to-get-access.md create mode 100644 docs/faq/index.md diff --git a/docs/IV/about/schema-overview.md b/docs/IV/about/schema-overview.md new file mode 100644 index 00000000..7ba684e9 --- /dev/null +++ b/docs/IV/about/schema-overview.md @@ -0,0 +1,149 @@ +--- +title: Schema overview +layout: default +nav_order: 20 +parent: About MIMIC-IV +grand_parent: MIMIC-IV +description: An overview of the modular structure of MIMIC-IV, including the identifier system, module characteristics, and patterns for cross-module analysis. +--- + +# MIMIC-IV schema overview +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Understanding the overall structure and organization of the MIMIC-IV database is crucial for effective analysis. + +## Modular design + +MIMIC-IV uses a modular design. The hospital (`hosp`) module contains data acquired from the hospital wide electronic health record. The ICU (`icu`) module contains data from the clinical information system used within the ICU. Additional modules (ED, CXR, ECG, Note) extend MIMIC-IV with data from other systems. + +## Core identifier system + +The database uses a hierarchical identifier system: + +### Patient level +{% include subject_id.md %} + +### Hospital admission level +{% include hadm_id.md %} + +### Unit stay level +{% include stay_id.md %} + +## Data flow through the hospital + +Understanding how patients move through the hospital helps in understanding the data: + +1. **Patient arrives** → `subject_id` assigned +2. **Hospital admission** → `hadm_id` assigned +3. **Unit transfer** → `stay_id` assigned (ICU, ED, etc.) +4. **Data collection** → Events recorded with appropriate IDs + +## Module characteristics + +### Hospital (hosp) module +- **Purpose**: Hospital-wide EHR data +- **Key tables**: `patients`, `admissions`, `transfers`, `labevents`, `prescriptions`, `diagnoses_icd` +- **Coverage**: All hospital patients +- **Granularity**: Order/event-level + +### ICU module +- **Purpose**: Intensive care monitoring +- **Key tables**: `chartevents`, `inputevents`, `outputevents`, `procedureevents` +- **Coverage**: ICU patients only +- **Granularity**: Hour-to-hour or more frequent + +### Emergency department (ED) module +- **Purpose**: Emergency department care +- **Key tables**: `edstays`, `triage`, `vitalsign`, `medrecon`, `pyxis`, `diagnosis` +- **Coverage**: ED patients only +- **Granularity**: Visit-level and event-level + +### Note module +- **Purpose**: De-identified free-text clinical notes +- **Key tables**: `discharge`, `radiology` (and their detail tables) +- **Coverage**: Subset of hospitalized patients +- **Granularity**: Note-level + +### CXR module +- **Purpose**: Chest x-ray images and reports linked to MIMIC-IV +- **Key tables**: lookup tables linking `subject_id` to `study_id` and `dicom_id` +- **Coverage**: ED patients with chest radiographs +- **Granularity**: Study- and image-level + +### ECG module +- **Purpose**: Diagnostic 12-lead ECG waveforms and machine measurements +- **Key tables**: `record_list`, `machine_measurements`, `waveform_note_links` +- **Coverage**: Subset of patients with ECG recordings +- **Granularity**: Study-level + +## Data relationships + +### One-to-many relationships +- One patient → Many admissions +- One admission → Many diagnoses +- One admission → Many lab results +- One ICU stay → Many vital sign measurements + +### Cross-module linking +Patients can be followed across modules using identifiers: + +```sql +-- Link patient demographics to ICU data +SELECT p.gender, c.valuenum AS heart_rate +FROM `physionet-data.mimiciv_hosp.patients` p +JOIN `physionet-data.mimiciv_hosp.admissions` a ON p.subject_id = a.subject_id +JOIN `physionet-data.mimiciv_icu.icustays` i ON a.hadm_id = i.hadm_id +JOIN `physionet-data.mimiciv_icu.chartevents` c ON i.stay_id = c.stay_id +WHERE c.itemid = 220045 -- Heart rate +``` + +## Temporal considerations + +### Time precision +- **Hosp**: Usually day or hour precision +- **ICU**: Minute-level precision common +- **ED**: Varies by event type + +For more on how time is represented in MIMIC-IV, including `charttime` vs. `storetime` and date shifting, see the [Core concepts](/docs/iv/about/concepts/) page. + +## Common analysis patterns + +### Patient cohort selection +1. Start with the `patients` table for demographics +2. Join to `admissions` for admission criteria +3. Add module-specific criteria as needed + +### Longitudinal analysis +1. Identify patient population +2. Extract events from relevant modules +3. Align timestamps for temporal analysis + +### Outcome assessment +1. Define outcome from appropriate module +2. Link back to patient characteristics +3. Account for censoring and follow-up + +## Best practices + +### Query design +- Always include appropriate time filters +- Be mindful of data volume in the ICU module +- Use indexed columns for joins when possible + +### Data validation +- Check for reasonable value ranges +- Validate identifier linkages +- Account for missing data patterns + +--- + +{: .note } +> This schema overview provides the foundation for understanding MIMIC-IV. Each module has its own detailed documentation with table-specific information. diff --git a/docs/IV/index.md b/docs/IV/index.md index 5fc4f3bc..6b4d9487 100644 --- a/docs/IV/index.md +++ b/docs/IV/index.md @@ -9,7 +9,7 @@ MIMIC-IV is a relational database containing real hospital stays for patients ad The database is intended to support a wide variety of research in healthcare. MIMIC-IV builds upon the success of [MIMIC-III](/docs/iii), and incorporates numerous improvements over MIMIC-III. -MIMIC-IV is separated into "modules" to reflect the provenance of the data. There are currently five modules: +MIMIC-IV is separated into "modules". There are currently five modules: - [hosp](/docs/iv/modules/hosp) - hospital level data for patients: labs, micro, and electronic medication administration - [icu](/docs/iv/modules/icu) - ICU level data. These are the event tables, and are identical in structure to MIMIC-III (chartevents, etc) @@ -17,9 +17,6 @@ MIMIC-IV is separated into "modules" to reflect the provenance of the data. Ther - [cxr](/docs/iv/modules/cxr) - lookup tables and meta-data from MIMIC-CXR, allowing linking to MIMIC-IV - [note](/docs/iv/modules/note) - deidentified free-text clinical notes -{: .warning } -> MIMIC-Note is currently not publicly available and the structure is subject to change. - All patients across all datasets are in the [hosp](/docs/iv/modules/hosp) module. However, not all ICU patients have ED data, not all ICU patients have CXRs, not all ED patients have hospital data, and so on. Within an individual dataset, there are also incomplete tables as certain electronic systems did not exist in the past, particularly the eMAR system. Tables for each module are detailed in the respective sections. diff --git a/docs/IV/modules/note/index.md b/docs/IV/modules/note/index.md index ce702fec..5dd2f9b6 100644 --- a/docs/IV/modules/note/index.md +++ b/docs/IV/modules/note/index.md @@ -2,12 +2,20 @@ title: Note layout: default nav_order: 80 -description: '(NOT PUBLICLY AVAILABLE): The Note module contains deidentified free-text - clinical notes for hospitalized patients.' +description: The Note module contains deidentified free-text clinical notes for hospitalized + patients, including discharge summaries and radiology reports. has_children: true parent: MIMIC-IV --- -{: .warning } -> MIMIC-Note is currently not publicly available and the structure is subject to change. +The Note module (MIMIC-IV-Note) contains deidentified free-text clinical notes for hospitalized patients. As of MIMIC-IV-Note v2.2, the module includes notes from the hospital wide EHR. The module contains: + +- **discharge** - Discharge summaries +- **discharge_detail** - Information related to discharge summaries +- **radiology** - Radiology reports +- **radiology_detail** - Information related to radiology reports + +All notes have been deidentified to protect patient privacy while preserving clinical content for research. Deidentified entities are replaced with three underscores (`___`). + +The Note module is published separately on PhysioNet: [MIMIC-IV-Note](https://physionet.org/content/mimic-iv-note/). It can be linked to the rest of MIMIC-IV via `subject_id` and `hadm_id`. diff --git a/docs/IV/tutorials/first-query.md b/docs/IV/tutorials/first-query.md new file mode 100644 index 00000000..b2a1c56c --- /dev/null +++ b/docs/IV/tutorials/first-query.md @@ -0,0 +1,114 @@ +--- +title: Your first MIMIC query +layout: default +nav_order: 5 +parent: Tutorials +grand_parent: MIMIC-IV +description: A walkthrough of writing your first SQL queries against MIMIC-IV, covering patient counts, demographics, and joining the admissions table. +--- + +# Your first MIMIC query +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Learn how to write your first query against the MIMIC-IV database. This tutorial assumes you have already gained access to MIMIC data. + +## Prerequisites + +- Access to MIMIC data (see [Getting Started](/docs/gettingstarted/)) +- Basic SQL knowledge +- Access to a query environment (BigQuery, PostgreSQL, etc.) + +## Understanding the basic structure + +MIMIC-IV is organized into modules. Let's start with the most fundamental table: `patients` in the `hosp` module. + +### The patients table + +The `patients` table contains basic demographic information. Each row corresponds to a single patient, identified by their `subject_id`. + +{% include subject_id.md %} + +## Your first query + +Let's count how many patients are in the database: + +```sql +SELECT COUNT(*) AS total_patients +FROM `physionet-data.mimiciv_hosp.patients`; +``` + +{: .note } +> This example uses BigQuery syntax. Adjust the table name format for your platform. + +### Expected result + +You should see roughly 300,000+ patients in MIMIC-IV. + +## Exploring patient demographics + +Let's look at the gender distribution: + +```sql +SELECT + gender, + COUNT(*) AS count, + ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER(), 2) AS percentage +FROM `physionet-data.mimiciv_hosp.patients` +GROUP BY gender +ORDER BY count DESC; +``` + +## Adding hospital admissions + +Now let's join with the `admissions` table to see admission patterns: + +```sql +SELECT + p.gender, + COUNT(DISTINCT a.hadm_id) AS total_admissions, + COUNT(DISTINCT p.subject_id) AS unique_patients, + ROUND(COUNT(DISTINCT a.hadm_id) / COUNT(DISTINCT p.subject_id), 2) AS avg_admissions_per_patient +FROM `physionet-data.mimiciv_hosp.patients` p +JOIN `physionet-data.mimiciv_hosp.admissions` a + ON p.subject_id = a.subject_id +GROUP BY p.gender; +``` + +### Key concepts + +- {% include subject_id.md %} +- {% include hadm_id.md %} + +## Next steps + +Now that you've run your first queries: + +1. **Explore other tables** - Try querying [ICU stays](/docs/iv/modules/icu/icustays/) +2. **Learn the schema** - Review the [schema overview](/docs/iv/about/schema-overview/) +3. **Try BigQuery** - Read the longer [BigQuery tutorial](/docs/iv/tutorials/bigquery/) + +## Common issues + +### Query timeout +If your query times out, try adding `LIMIT 1000` to test on a smaller dataset first. + +### Permission errors +Ensure you've properly signed the data use agreement for the modules you're querying. + +### Different platforms +- **PostgreSQL**: Remove backticks and use `schema.table` format +- **AWS**: Use appropriate S3 bucket references +- **Local**: Adjust paths to your local database + +--- + +{: .highlight } +> **Well done!** You've successfully run your first MIMIC queries. Understanding these basic patterns will help you tackle more complex analyses. diff --git a/docs/faq/data.md b/docs/faq/data.md new file mode 100644 index 00000000..4b01d69a --- /dev/null +++ b/docs/faq/data.md @@ -0,0 +1,61 @@ +--- +title: Using MIMIC data +layout: default +nav_order: 20 +parent: FAQ +--- + +# Using MIMIC data + +{: .note } +> **Can't find your question?** Search through the [issues on GitHub](https://github.com/MIT-LCP/mimic-code/issues). + +## How do I link patients across modules? + +Understanding how to join data across different MIMIC modules and tables. + +### Key Identifiers + +#### Patient Level +- `subject_id`: Unique patient identifier across all modules +- Links: All tables contain this identifier + +#### Hospital Admission Level +- `hadm_id`: Hospital admission identifier +- Links: Hospital and ICU modules + +#### ICU Stay Level +- `stay_id`: ICU stay identifier +- Links: ICU-specific tables + +### Common Linking Patterns + +#### Hospital to ICU Data +```sql +-- Example: Link admissions to ICU stays +SELECT a.*, i.* +FROM mimiciv_hosp.admissions a +LEFT JOIN mimiciv_icu.icustays i + ON a.hadm_id = i.hadm_id; +``` + +#### Patient Demographics +```sql +-- Example: Add patient demographics to any analysis +SELECT analysis.*, p.gender, p.anchor_age +FROM your_analysis_table analysis +LEFT JOIN mimiciv_hosp.patients p + ON analysis.subject_id = p.subject_id; +``` + +### Module-Specific Linking + +Patients can be linked across distinct MIMIC databases using their identifier. Databases which can currently be linked include MIMIC-IV, MIMIC-IV-ED, MIMIC-IV-ECG, MIMIC-IV-Note, and MIMIC-CXR. + +- **Hospital (hosp)**: `subject_id`, `hadm_id` +- **ICU**: `subject_id`, `hadm_id`, `stay_id` +- **Emergency Department (ED)**: `subject_id`, `hadm_id` + - the `hadm_id` in the MIMIC-IV-ED *edstays* table is the hospitalization immediately *after* the ED stay +- **Chest X-ray (CXR)**: `subject_id` in MIMIC-IV is equal to the `PatientID` metadata element in the DICOM headers of the chest x-rays in MIMIC-CXR +- **ECG**: `subject_id` links to MIMIC-IV; `note_id` links cardiologist notes in the MIMIC-IV-Note module +- **Note**: `subject_id`, `hadm_id` diff --git a/docs/faq/how-to-get-access.md b/docs/faq/how-to-get-access.md new file mode 100644 index 00000000..6ad4dff8 --- /dev/null +++ b/docs/faq/how-to-get-access.md @@ -0,0 +1,88 @@ +--- +title: How do I access MIMIC? +layout: default +nav_order: 10 +parent: FAQ +--- + +# How do I get access to MIMIC? + +Getting access to MIMIC data requires completing human subjects training and signing a data use agreement. Here is the step-by-step process: + +## Step 1: Complete PhysioNet Credentialing + +1. **Create a PhysioNet account** at [physionet.org](https://physionet.org) +2. **Complete the credentialing process**: + - Take the required training course in human subjects research + - Provide your institutional affiliation + - Submit reference information (required for students/postdocs) +3. **Wait for approval**. Please be patient, we try to process applications within 1-2 weeks. + +{: .important } +> **Students and Postdocs**: You must provide your supervisor's contact information as a reference. Do not list yourself as a reference. + +## Step 2: Sign the Data Use Agreement + +Once credentialed: + +1. **Log in** to your PhysioNet account +2. **Navigate** to the dataset page you need: + - [MIMIC-IV](https://physionet.org/content/mimiciv/) + - [MIMIC-IV-Note](https://physionet.org/content/mimic-iv-note/) + - [MIMIC-IV-ED](https://physionet.org/content/mimic-iv-ed/) + - [MIMIC-IV-ECG](https://physionet.org/content/mimic-iv-ecg/) + - [MIMIC-CXR](https://physionet.org/content/mimic-cxr/) + - [MIMIC-III](https://physionet.org/content/mimiciii/) +3. **Review and sign** the Data Use Agreement (DUA) +4. **Download** or access data through cloud platforms + +## Step 3: Choose Your Access Method + +### Cloud Access (Recommended) +- **Google Cloud (BigQuery)**: Easiest for SQL queries +- **AWS**: Available for MIMIC-III +- **Google Cloud Storage**: Direct access to data within GCP + +### Local Download +- Download individual CSV files +- Set up a local PostgreSQL database +- Requires more setup but provides full control + +## Common Questions + +### How long does credentialing take? +Typically 1-2 weeks if all information is complete. Incomplete applications may be delayed or rejected. + +### Can I access data immediately after signing the DUA? +Yes, for cloud platforms. Local download may take additional time depending on file sizes. + +### Do I need separate access for each dataset? +Yes, you need to sign separate DUAs for MIMIC-III, MIMIC-IV, MIMIC-CXR, MIMIC-IV-Note, MIMIC-IV-ED, and MIMIC-IV-ECG. + +## Troubleshooting + +### Application Rejected +- Ensure all required fields are completed +- Provide a valid institutional email address (not required, but helpful) +- Include the correct CITI training: make sure it is "Data or Specimens Only Research" +- Include the CITI *Completion Report*, not just the certificate +- Include proper reference information +- Contact credentialing at PhysioNet if issues persist + +### Can't Find Reference Information +- Use your supervisor or department head +- Must be someone who can verify your affiliation +- Should not be yourself or a peer student + +## Next Steps + +Once you have access: + +1. **Start with the [Getting Started guide](/docs/gettingstarted/)** to set up your access method +2. **Understand the data** - Read the [Core concepts](/docs/IV/about/concepts/) page +3. **Join the community** - Follow the [Community guidelines](/docs/community/) + +--- + +{: .highlight } +> Remember: The Data Use Agreement is legally binding. Make sure you understand and can comply with all terms before signing. diff --git a/docs/faq/index.md b/docs/faq/index.md new file mode 100644 index 00000000..5ed6db0e --- /dev/null +++ b/docs/faq/index.md @@ -0,0 +1,20 @@ +--- +title: FAQ +layout: default +nav_order: 15 +has_children: true +--- + +# Frequently Asked Questions + +Common questions about MIMIC data access, usage, and analysis. + +## Quick Answers + +- **[How do I get access?](/docs/faq/how-to-get-access/)** - Step-by-step access process +- **[How do I link patients across modules?](/docs/faq/data/)** - Cross-module joins + +--- + +{: .note } +> **Can't find your question?** Search through the [issues](https://github.com/MIT-LCP/mimic-code/issues) and [discussions](https://github.com/MIT-LCP/mimic-code/discussions) on the MIMIC Code Repository. From 454adf509168473119838915412614a75772d5d3 Mon Sep 17 00:00:00 2001 From: Alistair Johnson Date: Sun, 3 May 2026 08:07:55 -0400 Subject: [PATCH 2/2] update citation --- docs/about/acknowledgments.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/about/acknowledgments.md b/docs/about/acknowledgments.md index 2d70656c..36a2cdae 100644 --- a/docs/about/acknowledgments.md +++ b/docs/about/acknowledgments.md @@ -15,16 +15,20 @@ If you use our data, code, or algorithms, please provide a citation to this proj If you use MIMIC-IV in your work, please cite this project: -> Johnson, A., Bulgarelli, L., Pollard, T., Horng, S., Celi, L. A., & Mark, R. (2021). MIMIC-IV (version 1.0). PhysioNet. https://doi.org/10.13026/s6n6-xd98. +> Johnson AE, Bulgarelli L, Shen L, Gayles A, Shammout A, Horng S, Pollard TJ, Hao S, Moody B, Gow B, Lehman LW. MIMIC-IV, a freely accessible electronic health record dataset. Scientific data. 2023 Jan 3;10(1):1. BibTeX entry: ``` -@misc{johnson2020mimic, - title={MIMIC-IV (version 1.0)}, - author={Johnson, A and Bulgarelli, L and Pollard, T and Horng, S and Celi, LA and Mark, R}, - year={2020}, - publisher={PhysioNet} +@article{johnson2023mimic, + title={MIMIC-IV, a freely accessible electronic health record dataset}, + author={Johnson, Alistair EW and Bulgarelli, Lucas and Shen, Lu and Gayles, Alvin and Shammout, Ayad and Horng, Steven and Pollard, Tom J and Hao, Sicheng and Moody, Benjamin and Gow, Brian and others}, + journal={Scientific data}, + volume={10}, + number={1}, + pages={1}, + year={2023}, + publisher={Nature Publishing Group UK London} } ```