port over content

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.

docs/IV/index.md

@@ -9,17 +9,14 @@ 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)
 - [ed](/docs/iv/modules/ed) - data from the emergency department
 - [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.

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`.

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.

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}
 }
 ```
 

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`