Skip to content
bdsp-corePublic

Repository files navigation

NESI — Neurophysiologic Encephalopathy Severity Index

A unified, continuous, EEG-based index of encephalopathy severity for critical care.

🔬 Live interactive demo: https://bdsp-core.github.io/NESI/ — click any point on the PaCMAP embedding to view its 10-minute EEG segment (color by NESI, dominant IIC pattern, or MORGOTH feature).

This repository contains the code and trained model weights for NESI, a continuous electroencephalography (EEG)-derived measure of encephalopathy severity along the delirium–coma continuum in non-agitated states. Instead of predicting each bedside scale separately, NESI is trained jointly on four scales and places patients on one severity axis.

Where this fits. L5 — query & consume, in the BDSP OMOP repo family. Medication exposures are reproduced from omop_prod.drug_exposure rather than S3 parquet MARs. Reads the finished OMOP CDM; depends on no pipeline internals. Family members carry the topic bdsp-omop.

📌 Overview

Disorders of consciousness are assessed at the bedside with multiple, partially redundant scales that are intermittent, subjective, and often discordant. NESI unifies four of them — RASS (Richmond Agitation–Sedation Scale), GCS (Glasgow Coma Scale), CAM-S (Confusion Assessment Method–Severity), and ICANS (immune effector cell–associated neurotoxicity syndrome grading) — onto a single continuous severity scale.

The pipeline has three stages:

  1. Foundation-model features — each 10-minute EEG segment is passed through the MORGOTH clinical-EEG foundation model, yielding a 591×17 matrix of event-level feature activations.
  2. Contrastive encoder — a supervised-contrastive ResNet compresses that matrix to a 40-D embedding.
  3. Pairwise-ranking head — a Siamese MLP maps the embedding to a single scalar NESI value, trained with within-scale and cross-scale ordinal pairs (assembled into a unified dataset, SPECTRA) so severity is learned on one scale-agnostic axis.

Key results (see the manuscript): on the held-out test set NESI agrees with all four scales (Spearman ρ 0.72 RASS, 0.72 GCS, 0.84 CAM-S, 0.83 ICANS; patient-level bootstrap CIs). In an independent Northwestern cohort (990 patients, no retraining) ρ was 0.60 for RASS and 0.65 for GCS. NESI rises with modeled propofol effect-site concentration and is associated with in-hospital mortality (AUROC 0.77 at 4 h; GCS 0.81), adding discrimination to clinical covariates but not to GCS.

Project naming: this repository was previously named YAMA; it is the codebase for the NESI project described above. The per-cohort scale models (RASS/GCS/CAM-S/ICANS) are the building blocks that feed the unified NESI model.

📦 Data & published release

This repo holds code, model weights and fold-level summary metrics only. Patient- and segment-level files are listed in docs/DATA_FILES.md. The data (EEG segments, MORGOTH activations, assembled training/validation/test sets, per-cohort metadata, derived tables) are de-identified (surrogate subject IDs; shifted dates) and distributed under credentialed access on BDSP:

  • Published dataset (bdsp.io): https://bdsp.io/content/1yizvr4l41wmiljc6lou/1.0.0/
  • Credentialed S3: s3://bdsp-opendata-credentialed/yama/
  • DOIs: version 10.60508/rrbg-ba24 · core 10.60508/65as-th98
  • Provenance: yama/segment_index.csv (every segment → its continuous source EEG) and yama/source_eeg_files.csv.

Fast reproduction: reproduce/run_all.py regenerates the manuscript's numbers, tables and figures from saved intermediate results in minutes and checks every registered number against the manuscript (reproduce/claims.csv). See reproduce/README.md; python reproduce/run_all.py --list shows how each figure and table is produced. docs/REPRODUCE.md describes the full pipeline from raw EEG.

Medication data via OMOP. The medication exposures (originally pulled from S3 parquet MARs) are now in the BDSP OMOP Aurora database and are far easier to query there (BDSPPatientID == OMOP person_id; administrations are drug_type_concept_id = 38000180). A ready-to-run, verified reproduction lives in NESI/NESI-Medication-Analysis/omop/ — it reproduces Table 2's RASS propofol exposure from OMOP at 3,245 / 6,188 = 52.4% vs the published 3,250 / 6,188 = 52.5% (denominator exact; 5-patient / 0.1-pp difference).

📂 Repository structure

NESI/
├── cohort_models/      # per-scale building-block models (code + weights)
│   ├── RASS/  GCS/  CAMS/  ICANS/
├── NESI/               # the unified NESI model: training, testing, ablations,
│                       #   embedding atlas, ScaleVsNESI, medication/propofol
│                       #   (Eleveld PK), DeathPrediction (NESI vs GCS), requirements.txt
├── mortality_analysis/ # in-hospital mortality cohort assembly + NESI correlation
├── comparators/        # external baseline models kept for head-to-head comparison
│   └── AIrhythm/       #   PhysioNet/CinC 2023 coma-prognostication entry (not used in the manuscript)
├── reproduce/          # run_all.py: fast reproduction from saved intermediates + revision analyses
├── RevisionRelatedMaterials/  # revision analyses that start from raw EEG or MORGOTH activations
├── figures/
│   ├── final/          # every figure exactly as in the manuscript and supplement
│   ├── main/Codes/     # original main-figure scripts (run by reproduce/run_all.py)
│   └── supplementary_score_prediction/
├── docs/               # REPRODUCE.md (pipeline from raw EEG) + DATA_FILES.md
├── requirements.txt
├── environment.yml
└── README.md

⚠️ Prerequisite: MORGOTH

NESI uses MORGOTH as the EEG feature-extraction foundation model. Set up MORGOTH first:

🔗 https://github.com/bdsp-core/morgoth

Follow its installation instructions and ensure its environment is functional before installing NESI; the pipeline depends on MORGOTH to turn raw EEG into the 591×17 feature matrices.

⚙️ Installation

# 1. Clone
git clone https://github.com/bdsp-core/NESI.git
cd NESI

# 2. Create the environment (recommended)
conda env create -f environment.yml
conda activate torchenv

# 3. (GPU) install the matching PyTorch build
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# 4. Install remaining dependencies
pip install -r requirements.txt          # or: pip install -r NESI/requirements.txt

# 5. Verify
python -c "import torch, numpy, statsmodels, mne; print('Environment OK')"

Ensure the CUDA version matches your system. GPU is recommended for training.

🔁 Reproducing the paper

  1. Request credentialed access to the dataset (link above) and aws s3 sync the cohort(s) you need. Set NESI_DATA_ROOT to your local copy and run python link_data.py, which links the files in docs/DATA_FILES.md into the paths the scripts read.
  2. Set up MORGOTH and this environment.
  3. Run python reproduce/run_all.py (see reproduce/README.md) to regenerate the results from the saved intermediates, or follow docs/REPRODUCE.md to rerun the pipeline from raw EEG.

🧪 Comparators

Baseline models we compare NESI against live under comparators/, each with its own documentation and upstream license. Currently:

  • comparators/AIrhythm/ — the AIrhythm entry (Morteza Zabihi) to the PhysioNet/CinC 2023 coma-prognostication challenge: 382 hand-engineered EEG/ECG features per 3-minute window, pooled over multi-hour blocks, fed to an ensemble of 51 CatBoost / stacked classifiers trained across three different cross-validation partitions. It is not used in the manuscript. Note that it targets poor neurological outcome (CPC 3–5), not death — see its README for what a fair head-to-head requires.

📑 Citation

If you use NESI, please cite the dataset and the manuscript:

Roy A, Surrao K, Sun C, Jing J, … Kimchi EY, Zafar SF, Eckhardt CA, Westover MB. Neurophysiologic Encephalopathy Severity Index (NESI) — Data and Code. Brain Data Science Platform (2026). https://doi.org/10.60508/65as-th98

(Manuscript citation to be added on publication.)

📬 Contact

License

See LICENSE.txt. The accompanying data are governed by the BDSP Credentialed Health Data License and Data Use Agreement (see the bdsp.io project page).

Releases

Packages

Used by

Contributors

Languages