amirrouh/cadence

Cadence — Next Clinical Event Prediction

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

  

Model Description

Cadence implements the Narrative Velocity Composite (NV-C) framework — a 5.86M parameter residual MLP that fuses structured EHR features with PubMedBERT cluster-semantic embeddings under self-knowledge distillation.

Performance

Trained and evaluated on MIMIC-IV v3.1 (100k training tier, male cohort):

Bootstrap 95% CI: N=105,968 test instances, 2,000 resamples. XGBoost falls outside Cadence's CI on both metrics.

Key finding: Self-knowledge distillation yields a disproportionately large top-1 gain (+0.81 pp) when applied after PubMedBERT cluster-semantic fusion — compared to ~0 pp gain from self-KD on structured features alone — suggesting a genuine interaction between frozen semantic embeddings and knowledge distillation.

Installation & Usage

pip install cadence-core>=1.3.0

Pretrained weights not distributed. The MIMIC-trained classifier is dataset-specific (50-cluster space derived from MIMIC text). Transfer to other datasets is not meaningful, so we ship the architecture and training code rather than weights. Train your own model on your own data using cadence.train(...).

import cadence

classifier = cadence.train(
    train_jsonl="my_data/train.jsonl",
    val_jsonl="my_data/val.jsonl",
    embeddings_path="my_data/embeddings.npy",
    event_index_path="my_data/event_index.json",
    n_clusters=50,
    out_dir="./runs/my_run",
    n_epochs=30,
)

preds = cadence.predict(
    classifier,
    "my_data/test.jsonl",
    embeddings_path="my_data/embeddings.npy",
    event_index_path="my_data/event_index.json",
)
# preds: [{"patient_id": "...", "top_3_clusters": [...], "top_3_probs": [...], "days_until_next": ...}, ...]

Train on Custom Labels (Binary / Multiclass)

Starting with v1.2.0, cadence.train() accepts task="binary" or task="multiclass" so you can train Cadence on arbitrary labels instead of next-event prediction. Add a label_field key to your target objects and pass it along:

import cadence

# Binary classification on JSONL data
# (your target objects include e.g. {"cluster_id": ..., "readmitted_30d": 1})
classifier = cadence.train(
    train_jsonl="train.jsonl",
    val_jsonl="val.jsonl",
    embeddings_path="embeddings.npy",
    event_index_path="event_index.json",
    n_clusters=50,
    n_epochs=30,
    out_dir="./runs/binary_run",
    task="binary",
    label_field="readmitted_30d",
)
preds = cadence.predict(
    classifier,
    "test.jsonl",
    embeddings_path="embeddings.npy",
    event_index_path="event_index.json",
)
# preds: [{"patient_id": "...", "probabilities": 0.83}, ...]

# Multiclass (4 classes) on JSONL data
classifier = cadence.train(
    train_jsonl="train.jsonl",
    val_jsonl="val.jsonl",
    embeddings_path="embeddings.npy",
    event_index_path="event_index.json",
    n_clusters=50,
    n_epochs=30,
    out_dir="./runs/multiclass_run",
    task="multiclass",
    label_field="discharge_category",
    n_classes=4,
)
preds = cadence.predict(
    classifier,
    "test.jsonl",
    embeddings_path="embeddings.npy",
    event_index_path="event_index.json",
)
# preds: [{"patient_id": "...", "probabilities": [0.1, 0.5, 0.3, 0.1]}, ...]

Pre-built feature matrix

If you already have a feature matrix, skip JSONL entirely:

import cadence
import numpy as np

# X_train: (N, D) numpy array, y_train: (N,) integer labels
classifier = cadence.train_classifier(
    X_train, y_train,
    X_val=X_val, y_val=y_val,
    task="binary",
    n_epochs=30,
    out_dir="./runs/features_run",
)
probs = cadence.predict_from_features(classifier, X_test)
# probs: (N,) array of probabilities for binary; (N, K) for multiclass

Recommended for small datasets (n < 5000)

On small datasets Cadence can overfit quickly. Use early stopping, class weighting, and stronger L2 regularization to stabilize training (v1.2.1+):

classifier = cadence.train_classifier(
    X_train, y_train,
    X_val=X_val, y_val=y_val,
    task="binary",
    n_epochs=200,
    hidden_dims=(128, 64),         # smaller model for small n
    early_stopping_patience=10,    # halt when val plateaus
    early_stopping_metric="val_auroc",
    class_weight="balanced",       # imbalanced clinical labels
    weight_decay=1e-3,             # stronger L2 vs default 1e-4
    lr=1e-3,
)
probs = cadence.predict_from_features(classifier, X_test)

The same kwargs are available on cadence.train() for task="binary" or task="multiclass" (JSONL path). For task="next_event", these kwargs are accepted but ignored.

Training Data

Trained on MIMIC-IV v3.1 (PhysioNet credentialed access required):

• —100k patient sequences, male cohort
• —48 event categories derived from ICD-10 diagnosis and procedure codes
• —External validation: 1,120 BWH patients (JSD=0.27 domain shift)

Intended Use & Limitations

Intended use: Research on clinical event prediction, EHR sequence modelling, benchmarking.

Not intended for: Direct clinical decision-making without prospective validation.

Limitations:

• —Trained on MIMIC-IV (US academic medical center); performance under distribution shift varies
• —Structured features (labs, vitals, medications) required at inference; performance degrades when unavailable
• —48-class coarse event vocabulary; within-cluster distinctions are discarded
• —Calibration analysis pending

Citation

@article{rouhollahi2026cadence,
  title   = {Cadence: A Benchmark Evaluation of the Narrative Velocity Framework for Next Clinical Event Prediction in {MIMIC-IV}},
  author  = {Rouhollahi, Amir and Nezami, Farhad R.},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.05.06.722409},
  url     = {https://doi.org/10.64898/2026.05.06.722409}
}

Changelog

License

MIT License. MIMIC-IV data is subject to the PhysioNet Credentialed Health Data License.