PORT — Pediatric Operative Risk Transformer

Generative EHR foundation model adapted from ETHOS to predict intraoperative deterioration (IoD) in pediatric surgery, with LoRA fine-tuning on MEDS-format event timelines from a single institution.

This repository contains the model code, baselines, the data-preparation pipeline, and the IoD labeling code used in the study. It is a reference implementation: reproducing the full results additionally requires (i) institutional EHR data under a data use agreement and (ii) a cluster with H200- or A100-class GPUs.

---

Repository layout

iod_labeling/        IoD1-IoD5 label definitions + free-text (LLM-ensemble) refinement
datapreprocessing/   raw source tables -> MEDS parquet (12 tables)
pipeline/            MEDS -> patient-level train/val/test splits and tokenizer shards
experiments/vocab/   vocabulary reconstruction (hierarchical ICD-10, ATC mapping, socioeconomic fields)
ethos/               PORT model: configs, dataset wrappers, pre-training, inference, LoRA fine-tuning
baselines/           ASA score, LR / XGBoost (manual and MEDS features), tuned BiLSTM
evaluation/          AUROC / AUPRC / Brier / ECE, occlusion analysis, PPV subgroup analysis

iod_labeling/ is self-contained and documented separately in iod_labeling/README.md; it is the component most useful to adapt when defining intraoperative deterioration on a different dataset. The upstream ETHOS package is consumed via pip install -e ethos-ares/ and is not vendored.

---

Placeholder paths

Scripts use placeholder paths that must be substituted before running:

Placeholder	Meaning
/path/to/CHD_RAW	Raw EHR .rpt / .csv extracts
/path/to/CHD_MEDS	Working directory for derived MEDS parquets, splits, and model outputs
/path/to/ethos-ares	Local clone of ipolharvard/ethos-ares
${HF_HOME}	HuggingFace cache (used only by the LLM mapping and note-filter steps)

One-shot substitution:

grep -rl '/path/to/CHD_MEDS' . | xargs sed -i 's|/path/to/CHD_MEDS|/your/actual/path|g'

CHD_DATA_ROOT is also recognised as an environment variable by baselines/lstm.py.

---

Pipeline

# Environment
conda create -n ethos python=3.12
conda activate ethos
pip install -r requirements.txt
git clone https://github.com/ipolharvard/ethos-ares.git
pip install -e ethos-ares/

# 1. IoD label (see iod_labeling/README.md)
python iod_labeling/iod_to_outcome.py
python iod_labeling/iod2_audit.py
for m in llama qwen medgemma; do python iod_labeling/iod2_llm_filter.py --model "$m"; done
python iod_labeling/iod2_ensemble.py

# 2. Raw EHR -> MEDS parquet (one run per source table)
for f in datapreprocessing/meds_scripts/*_to_meds.py; do python "$f"; done

# 3. Merge, split, prepare tokenizer shards
python pipeline/merge_meds.py
python pipeline/create_splits.py
python pipeline/prepare_ethos_data.py

# 4. Vocabulary reconstruction
python experiments/vocab/preprocess_icd10_hier.py
python experiments/vocab/preprocess_ses.py
python experiments/vocab/preprocess_cutoffs.py
python experiments/vocab/preprocess_integrate.py
for f in experiments/vocab/stream_a_atc/0*.py; do python "$f"; done   # LLM ATC mapping

# 5. Tokenize, pre-train, zero-shot inference
bash ethos/tokenize.sh
bash ethos/train.sh        # 8 x H200 recommended
bash ethos/infer.sh

# 6. PORT fine-tuning (LoRA on the frozen backbone)
for seed in 42 123 456; do
    python ethos/finetune.py --lora --lora_r 8 --lora_alpha 16 \
        --loss_type unweighted_bce --seed "$seed"
done

# 7. Baselines
python -m baselines.asa_baseline
python -m baselines.logreg_xgb_tuned
python -m baselines.lstm_tuned

# 8. Evaluation
python -m evaluation.evaluate
python -m evaluation.occlusion_analysis
python -m evaluation.ppv_subgroup_analysis

The shell wrappers under ethos/ target an interactive multi-GPU node; adapt them to your scheduler as needed.

---

License

Code is released under the MIT License (see LICENSE). The EHR data are not redistributable.

---

Acknowledgements

Built on ETHOS and the MEDS standard. Drug-class mapping and the free-text note filter use open-weight instruction-tuned language models. The IoD label was developed with board-certified pediatric anesthesiologists.