cadence-core 1.0.1

Neural model for next clinical event prediction from EHR sequences using the Narrative Velocity framework

cadence-core

cadence-core is a pretrained neural model for next clinical event prediction from electronic health record (EHR) sequences. Given a patient's longitudinal clinical history, it predicts which of 50 clinical event categories will occur next and how many days until that event.

Documentation & Paper →

---

Key Features

• 5.86M parameter residual MLP — lightweight, fast inference, no GPU required
• Trained on MIMIC-IV v3.1 — 100k patient sequences from a large academic medical center
• Joint prediction — simultaneous 50-class event classification and time-to-event regression
• 34.18% top-1 accuracy, 36.95 days MAE — outperforms XGBoost and all evaluated baselines
• Self-knowledge distillation — improved generalization without external teacher models
• Auto-downloads checkpoint — model weights fetched from GitHub Releases on first use
• Drop-in inference — three lines of code from install to prediction

---

Installation

pip install cadence-core

Requires Python 3.10+. No GPU needed for inference.

---

Quick Start

import torch
from cadence import CadenceModel, load_checkpoint

# Load model and pretrained weights (checkpoint auto-downloads on first run)
model = CadenceModel()
load_checkpoint(model)
model.eval()

# Input: 2420-dimensional feature vector per patient visit
# [0:884]    — 884 Narrative Velocity (NV) clinical features
# [884:1652] — 768-dim PubMedBERT mean-pooled embedding of visit notes
# [1652:2420] — 768-dim PubMedBERT last-token embedding of visit notes
x = torch.randn(1, 2420)  # batch_size=1, feature_dim=2420

with torch.no_grad():
    logits, time_bins = model(x)

# logits    : (batch, 50)  — classification logits over 50 event categories
# time_bins : (batch, 19)  — regression logits over 19 discretized time bins
event_probs = torch.softmax(logits, dim=-1)
top1_event  = event_probs.argmax(dim=-1).item()
print(f"Predicted next event class : {top1_event}")
print(f"Top-1 probability          : {event_probs.max().item():.3f}")

---

Model Architecture

cadence-core implements the Narrative Velocity Composite (NV-C) framework — a residual MLP that fuses structured clinical features with contextual language embeddings.

Component	Details
Input dimension	2420 (884 NV features + 768 PubMedBERT mean + 768 PubMedBERT last)
Backbone	3-block MLP with residual skip connections and LayerNorm
Classification head	Linear → 50 event-class logits
Regression head	Linear → 19-bin discretized time-to-event logits
Parameters	5.86M
Training objective	Cross-entropy (classification) + ordinal regression loss (time), with self-KD

The 884 NV features capture structured clinical signals (labs, vitals, medications, procedures) encoded as narrative velocity trajectories. PubMedBERT embeddings are derived from clinical note text using microsoft/BiomedNLP-BiomedBERT-base-uncased-abstract-fulltext — frozen at inference.

---

Performance

100k Training Tier — Male Cohort (MIMIC-IV v3.1)

Model	Top-1 Accuracy	MAE (days)
cadence-core (NV-C)	34.18%	36.95
XGBoost	32.35%	50.9
Random Forest	24.1%	53.2
Logistic Regression	21.3%	58.7
RETAIN (baseline)	22.8%	54.1

Full-Cohort Results (MIMIC-IV v3.1)

Cohort	Top-1 Accuracy	MAE (days)
Male	34.18%	36.95
Female	33.41%	37.82

External Validation — BWH Dataset

Cohort	Top-1 Accuracy	MAE (days)
Male	31.6%	39.4
Female	30.9%	40.1

External validation was performed on ~2,000 de-identified clinical records from Brigham and Women's Hospital (BWH), a geographically and demographically distinct population from the MIMIC-IV training data.

---

Paper & Citation

Next Clinical Event Prediction in MIMIC-IV: A Comparative Evaluation of the Narrative Velocity Framework Against Established Baselines Rouhollahi A. and Nezami F.R. — preprint, 2026

If you use cadence-core in your research, please cite:

@article{rouhollahi2026cadence,
  title   = {Next Clinical Event Prediction in {MIMIC-IV}: A Comparative Evaluation
             of the Narrative Velocity Framework Against Established Baselines},
  author  = {Rouhollahi, Amir and Nezami, Farhad R.},
  year    = {2026},
  url     = {https://amirrouh.github.io/cadence/}
}

---

Reproducibility

Data access requires a signed PhysioNet credentialed account for MIMIC-IV:

https://physionet.org/content/mimiciv/3.1/

Once access is granted, follow the preprocessing instructions in src/ to generate the NV feature sequences and PubMedBERT embeddings used for training.

---

License

This project is released under the MIT License. The pretrained model checkpoint is provided for research use only. MIMIC-IV data is subject to its own PhysioNet Credentialed Health Data License.

---

Contact

Amir Rouhollahi Brigham and Women's Hospital / Harvard Medical School [e-mail] GitHub · PyPI