How to Convert MIMIC-IV to MEDS: Three Open-Source Routes and a Five-Minute Demo

TL;DR. There are three maintained open-source ways to turn MIMIC-IV into MEDS, the Medical Event Data Standard used for EHR foundation models. If you only need MEDS, use MIMIC_IV_MEDS, the MEDS community's own ETL: one command. If you already have MIMIC-IV 2.2 or an OMOP database, meds_etl converts either. If you need MEDS and OMOP together, a link from every event back to its source row, or a separate time for when each fact became available, use EHR2Trace, which I wrote with colleagues. Below are the commands for each, and a full EHR2Trace run on the open MIMIC-IV demo that converts in about two minutes.

What MEDS looks like

A MEDS dataset is a folder of Parquet shards in which each row is one event for one subject: subject_id, time, code and, when there is one, numeric_value. A metadata/ folder describes the codes, the dataset and the train, tuning and held-out splits. Every subject's events sit in one shard, sorted by time. The format is deliberately minimal, so tools that read it (task extraction, tokenizers, foundation-model training code) work on any dataset converted to it.

The work in converting MIMIC-IV is deciding what each event is: which column is the time, how to build a code from an item ID and a unit, what to do with rows that have no time. Each route below makes those decisions in a different place.

Route 1: MIMIC_IV_MEDS on MEDS-Extract

The MEDS project maintains a MIMIC-IV ETL as a package that contains no Python: one YAML file describes every table, and MEDS-Extract runs it.

pip install MIMIC_IV_MEDS
# The open demo (v2.2), no credentials needed:
meds-extract-run spec=MIMIC-IV output_dir=$MEDS_OUTPUT_DIR dataset_key=demo
# The full release (v3.1), downloaded from PhysioNet with your credentials:
export DATASET_DOWNLOAD_USERNAME=$PHYSIONET_USERNAME
export DATASET_DOWNLOAD_PASSWORD=$PHYSIONET_PASSWORD
meds-extract-run spec=MIMIC-IV output_dir=$MEDS_OUTPUT_DIR

Its README budgets about 32 minutes and 20 GB of RAM for the full extraction, plus the download (9.9 GiB, rate-limited by PhysioNet). If you already have the files, pass do_download=false input_dir=.... Because it is the community's reference ETL, results built on it are easier to compare with other MEDS work.

Route 2: meds_etl

meds_etl ships two converters: one for MIMIC-IV and one for OMOP.

pip install meds_etl
meds_etl_mimic  /path/to/mimic-iv-2.2  /path/to/output      # MIMIC-IV 2.2 only
meds_etl_omop   /path/to/omop_csvs     /path/to/output      # any OMOP CDM export

The OMOP converter is the useful part if your institution already runs an OMOP database: you get MEDS without writing a source-specific ETL. Per its README, the MIMIC converter supports MIMIC-IV 2.2 only.

Route 3: EHR2Trace, MEDS and OMOP from one layer

EHR2Trace first builds a canonical layer of patient events, then writes OMOP CDM 5.4 and MEDS 0.4 from it, so identity, time and unit decisions are made once and both outputs agree. Every MEDS row keeps the source table and row IDs it came from, and an available_time next to time. After writing, it validates what it wrote.

git clone https://github.com/Yangxinyee/ehr2trace && cd ehr2trace
python3 -m venv .venv && .venv/bin/pip install -r requirements.lock -e ".[dev]"
wget -r -N -c -np -nH --cut-dirs=1 -P data https://physionet.org/files/mimic-iv-demo/2.2/
python3 tools/prepare_mimiciv.py --mimic-root data/mimic-iv-demo/2.2 --out prepared/mimiciv
export MIMICIV_DATA_ROOT=$PWD/prepared EHR_WORK_ROOT=$PWD/work OFFLINE_MODE=1
for step in inspect ingest identity canonical omop meds validate; do
  .venv/bin/ehr2trace $step -d datasets/mimiciv.yaml
done

The repository runs exactly this on every push. Timings from one of those runs, on a standard two-core GitHub Actions runner:

The MEDS output has 971,550 events for 100 subjects and 6,529 codes, split 77 / 10 / 13 into train, tuning and held-out. The OMOP output has 788,079 measurement rows, 87,082 drug exposures and 4,506 condition occurrences, among others.

Two things in the run are worth knowing before you rely on it:

• Concept IDs are 0 until you install a vocabulary. The repository ships no SNOMED, LOINC or RxNorm. Download them from Athena and set OMOP_VOCAB_DIR; until then every source value is kept and every term goes to a review queue rather than being mapped silently. For OHDSI analyses that need high concept coverage on MIMIC-IV today, the official OHDSI MIMIC ETL maps far more.
• One check fails on MIMIC-IV, on purpose. The default validate run reports 43 passed, 10 skipped and 1 failed; validate --all, which adds one slower check that rereads every source file, runs all 55 and reports 44 passed. The failure says five lab codes mix units with no conversion between them; MCHC (item 51249), for example, appears in both g/L and %. The converter reports this rather than picking one.

To follow one patient from raw rows to the outputs: ehr2trace trace -d datasets/mimiciv.yaml --patient <key>.

The time column you will want later

MIMIC-IV records many facts after the event they describe. Diagnosis codes are assigned at discharge; a lab is collected at one time and resulted at another. If a diagnosis is placed at the admission time, a model asked to predict at hour six can see what was only known at discharge. On the full MIMIC-IV, in-hospital mortality prediction six hours after admission scored AUROC 0.965 with diagnoses back-filled to admission, 0.829 with inputs restricted to what was available at the time, and 0.642 when the back-filled model was tested on the realistic inputs.

EHR2Trace writes available_time on every MEDS row; in the demo, 71% of events have an availability later than their event time. When you build model inputs, filter on it:

import polars as pl

events = pl.scan_parquet("work/mimiciv/meds/data/**/*.parquet")
as_of = events.filter(
    pl.col("available_time").is_null() | (pl.col("available_time") <= prediction_time)
)

Whatever converter you use, check how it times diagnoses and results before you train on its output.

Which one to use

EHR2Trace is research software from one team (v0.7.0), and its paper is a preprint. The comparison above is drawn from each project's public documentation; corrections are welcome as issues on the EHR2Trace repository.

FAQ

What is the fastest way to convert MIMIC-IV to MEDS? Install the MIMIC_IV_MEDS package and run meds-extract-run spec=MIMIC-IV output_dir=.... It is the MEDS community's own MIMIC-IV ETL, built on MEDS-Extract. Add dataset_key=demo to convert the open 100-patient demo without PhysioNet credentials.

Can I get MEDS and OMOP from MIMIC-IV at the same time? Yes. EHR2Trace builds both OMOP CDM 5.4 and MEDS 0.4 from one canonical event layer, so patient identity, time and unit decisions are made once and the two outputs agree. On the MIMIC-IV demo the conversion took about two minutes on a two-core GitHub Actions runner.

How do I avoid time leakage when building prediction tasks from MIMIC-IV? Use when each fact became available, not only when the event happened. Diagnoses in MIMIC-IV are coded at discharge, so attaching them to the admission time lets a model see the future. EHR2Trace stores an available_time column on every MEDS row; filter on available_time <= prediction time when building inputs.

Do I need PhysioNet credentials to try this? Not for the MIMIC-IV demo (100 patients, Open Data Commons licence). The full MIMIC-IV release requires a credentialed PhysioNet account and the data use agreement.