OneEHR

OneEHR is a Python package for longitudinal EHR experiments. It uses standardized EHR tables and a TOML experiment config to run preprocessing, model training, testing, analysis, and figures across conventional ML/DL models and LLM or agent systems.

What OneEHR Provides

• Three-table EHR input contract: dynamic.csv, optional static.csv, and optional label.csv
• 42 built-in model architectures: tabular ML, recurrent and non-recurrent DL, irregular-time, multimodal, KG-enhanced, EHR-specialized, and survival models
• One run directory per experiment: preprocessing artifacts, checkpoints, predictions, metrics, analysis JSON, and figures
• Dataset converters: MIMIC-III, MIMIC-IV, and eICU converters for common clinical prediction tasks
• Medical code utilities: ICD-9/10 parsing, CCS grouping, ATC hierarchy, and code mapping helpers
• Analysis modules: comparison metrics, bootstrap confidence intervals, feature importance, fairness, calibration, statistical tests, and missing-data summaries
• Plot commands: ROC, PR, calibration, confusion, forest, fairness, missing-data, decision-curve, significance, cohort-flow, and training-curve figures

Install

OneEHR requires Python 3.12+.

pip install oneehr
oneehr --help

Install from a source checkout:

git clone https://github.com/MedX-PKU/OneEHR.git
cd OneEHR
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[test]"
uv run oneehr --help

Optional extras:

pip install "oneehr[survival]"  # lifelines support for survival analysis
pip install lime                # optional LIME interpretability support

Quickstart

Run the bundled TJH COVID-19 ICU example from a source checkout:

uv run python examples/tjh/convert.py

CONFIG=examples/tjh/mortality_patient.toml
uv run oneehr preprocess --config "$CONFIG"
uv run oneehr train      --config "$CONFIG"
uv run oneehr test       --config "$CONFIG"
uv run oneehr analyze    --config "$CONFIG"
uv run oneehr plot       --config "$CONFIG" --style nature

The run is written to runs/tjh/:

runs/tjh/
    manifest.json
    preprocess/
    train/
    test/
    analyze/
    figures/

Use the Python API with the config path:

import oneehr

config_path = "examples/tjh/mortality_patient.toml"

preprocess_result = oneehr.preprocess(config_path)
train_result = oneehr.train(config_path)
test_result = oneehr.test(config_path)
analysis_result = oneehr.analyze(config_path)

print(preprocess_result.run_dir)
print(test_result.metrics_path)
print(analysis_result.modules_run)

Input Data

OneEHR expects plain CSV files:

dynamic.csv: patient_id, event_time, code, value
static.csv:  patient_id, <patient-level covariates...>
label.csv:   patient_id, label_time, label_code, label_value

Example TOML:

[dataset]
dynamic = "data/dynamic.csv"
static = "data/static.csv"
label = "data/label.csv"

[task]
kind = "binary"
prediction_mode = "patient"

[[models]]
name = "xgboost"

[[models]]
name = "gru"

[output]
root = "runs"
run_name = "my_experiment"

See Data Model and Configuration for the full contract.

CLI Workflow

oneehr preprocess --config experiment.toml
oneehr train      --config experiment.toml
oneehr test       --config experiment.toml
oneehr analyze    --config experiment.toml
oneehr plot       --config experiment.toml

Dataset conversion:

oneehr convert --dataset mimic3 --raw-dir /path/to/mimic3 --output-dir data/mimic3 --task mortality
oneehr convert --dataset mimic4 --raw-dir /path/to/mimic4 --output-dir data/mimic4 --task mortality
oneehr convert --dataset eicu   --raw-dir /path/to/eicu   --output-dir data/eicu   --task mortality

Models

Models with static branches use patient-level static features when static.csv is provided. KG-enhanced models use the built-in lightweight_auto KG preset unless kg_source = "external" and external_kg_path are provided.

Documentation

Full documentation: medx-pku.github.io/OneEHR

• Installation
• Quickstart
• Data Model
• Core Workflows
• CLI Reference
• Configuration
• Models
• Artifacts
• Dataset Converters
• Medical Codes

Run the documentation site locally:

uv run --group docs mkdocs serve

Build the static site:

uv run --group docs mkdocs build

Development

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[test]"
pytest tests/ -v
ruff check oneehr tests

See CONTRIBUTING.md for contribution guidelines.