mimic-explorer 0.1.3

A locally installable EHR research sandbox for the MIMIC-IV dataset

MIMIC Explorer

A locally installable EHR research sandbox for the MIMIC-IV clinical dataset.

Features

• EHR Viewer — Patient search, encounter detail, clinical timeline
• Dashboards — Demographics, utilization, lab/medication summaries, data completeness
• Research Workbench — Cohort builder with criteria engine, structured search, CSV/JSON export
• FHIR R4 API — On-the-fly transformation to FHIR resources with search and $everything

Installation

pip install mimic-explorer

This installs MIMIC Explorer and all its dependencies:

• Django 6.x + Django REST Framework — REST API backend
• DuckDB — High-performance analytical queries over clinical data
• fhir.resources — FHIR R4 resource validation and serialization
• orjson — Fast JSON serialization
• django-cors-headers — CORS support for local development

Python 3.10 or later is required. No external database server is needed.

Note: If mimic-explorer is not recognized after installation, your Python Scripts directory may not be on your system PATH. You can always use the module form instead:

python -m mimic_explorer

Both mimic-explorer and python -m mimic_explorer accept the same flags (--test, --version, --port, --data, etc.).

Quick Start

With MIMIC-IV data

pip install mimic-explorer
mimic-explorer              # or: python -m mimic_explorer

Your browser will open to http://localhost:8765. The setup wizard guides you through selecting your MIMIC-IV data folder, validating files, and importing. Start with a small patient limit (100--1,000) to test quickly, then use supplement import to add more data later.

Without MIMIC-IV data (demo with test fixtures)

A synthetic dataset with 10 fictional patients is included for testing and demonstration. This data is entirely made up and contains no real patient information.

pip install mimic-explorer
mimic-explorer --data tests/fixtures/mimic-iv-test/   # or: python -m mimic_explorer --data ...

Or start the app normally and point the setup wizard at the tests/fixtures/mimic-iv-test/ folder.

Example API calls

Once data is imported, you can query the REST and FHIR APIs:

# List patients
curl http://localhost:8765/api/patients/

# Patient detail
curl http://localhost:8765/api/patients/10001/

# Patient timeline
curl http://localhost:8765/api/patients/10001/timeline/

# FHIR Patient resource
curl http://localhost:8765/fhir/Patient/mimic-10001/

# FHIR lab observations
curl "http://localhost:8765/fhir/Observation/?category=laboratory&patient=mimic-10001"

# FHIR $everything (all resources for a patient)
curl http://localhost:8765/fhir/Patient/mimic-10001/\$everything

Prerequisites

• Python 3.10+
• MIMIC-IV dataset — requires credentialed access via PhysioNet

Obtaining MIMIC-IV Data

MIMIC-IV is a freely available dataset, but access requires completion of a credentialing process:

1. Create a PhysioNet account
2. Complete the required CITI training course on human subjects research
3. Sign the data use agreement for MIMIC-IV
4. Download the CSV files (typically as .csv.gz)

The credentialing process typically takes 1--2 weeks. You can use the included synthetic test dataset in the meantime to explore the application.

Expected Data Structure

MIMIC Explorer expects the standard MIMIC-IV directory layout from PhysioNet. Files can be .csv or .csv.gz.

mimic-iv/
├── hosp/                          ← Required
│   ├── patients.csv.gz            Demographics (subject_id, gender, age, date of death)
│   ├── admissions.csv.gz          Hospital admissions (times, type, location, insurance)
│   ├── diagnoses_icd.csv.gz       ICD diagnosis codes per admission
│   ├── procedures_icd.csv.gz      ICD procedure codes per admission
│   ├── labevents.csv.gz           Lab results (value, units, reference ranges)
│   ├── prescriptions.csv.gz       Medication orders (drug, dose, route, timing)
│   ├── d_labitems.csv.gz          Reference: lab item IDs → names
│   ├── d_icd_diagnoses.csv.gz     Reference: ICD diagnosis code descriptions
│   ├── d_icd_procedures.csv.gz    Reference: ICD procedure code descriptions
│   ├── transfers.csv.gz           (optional) Ward transfers
│   └── emar.csv.gz                (optional) Medication administration records
├── icu/                           ← Optional
│   ├── icustays.csv.gz            ICU stays (care unit, LOS, in/out times)
│   ├── chartevents.csv.gz         Vital signs (HR, BP, SpO2, temp, RR)
│   └── d_items.csv.gz             Reference: chart item IDs → names
└── note/                          ← Optional (separate PhysioNet download)
    ├── discharge.csv.gz           Discharge summary notes (free text)
    └── radiology.csv.gz           Radiology report notes (free text)

All files are linked by subject_id (patient) and hadm_id (hospital admission). The importer loads patients first, then joins all downstream data against existing patients — if you set a patient limit, everything is automatically scoped.

Sample Test Dataset

A synthetic dataset with 10 fictional patients is included at tests/fixtures/mimic-iv-test/ for testing and demonstration. This data is entirely made up and does not contain any real patient information.

tests/fixtures/mimic-iv-test/
├── hosp/       10 patients, 12 admissions, labs, meds, diagnoses, procedures
├── icu/        ICU stays, vital signs (chartevents)
└── note/       3 discharge notes

You can also run the automated test suite against this data:

mimic-explorer --test              # or: python -m mimic_explorer --test

All 62 tests run against this synthetic dataset using an in-memory DuckDB instance — no MIMIC-IV access is required to verify the installation.

Architecture

Layer	Technology
Backend	Django + Django REST Framework
Frontend	React 18 + TypeScript + Tailwind CSS
App Database	SQLite (WAL mode)
Clinical Database	DuckDB
FHIR	On-the-fly R4 transformation (no stored resources)

Security

Warning: MIMIC Explorer is designed as a single-user local application. It binds to localhost only and makes no external network calls. There is no authentication layer — never expose this application to the public internet or a shared network.

• DEBUG mode is off by default. Set MIMIC_DEBUG=true to enable it during development.
• CORS_ALLOW_ALL_ORIGINS is off by default. It is automatically enabled in debug mode, or can be forced with MIMIC_CORS_ALL=true.
• The server binds to 127.0.0.1 only and ALLOWED_HOSTS is restricted to localhost and 127.0.0.1.

If you are working with real MIMIC-IV data (which contains de-identified but sensitive clinical information), ensure your machine has appropriate access controls and disk encryption enabled per your institution's data use agreement.

Documentation

Full API reference with all endpoints, parameters, and response shapes: docs/API.md

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, testing, and PR guidelines.

Citation

If you use MIMIC Explorer in your research, please cite it:

@software{nawab2025mimic_explorer,
  title  = {MIMIC Explorer},
  author = {Nawab, Khalid},
  year   = {2025},
  url    = {https://github.com/khalidnawab/mimic-explorer}
}

See CITATION.cff for the full citation metadata.

Author

Khalid Nawab — [e-mail]

Development assisted by Claude Code (Anthropic).

License

MIT