hla-survival

Multi-modal deep learning for graft survival prediction from HLA typing and clinical data.

A research prototype combining three input modalities:

• HLA amino-acid sequences — small transformer encoder over donor/recipient sequences for each locus
• Allele codes — categorical embeddings for high-resolution HLA alleles
• Clinical features — MLP over tabular donor/recipient covariates

Predicts time-to-event for graft loss using either a Cox proportional hazards head (DeepSurv-style) or a DeepHit discrete-time head with ranking loss.

Installation

The Python package name (hla_survival) uses an underscore, so clone the repo into a matching directory:

git clone https://github.com/NessKerkeni/hla-survival.git hla_survival
pip install -r hla_survival/requirements.txt

Requires Python 3.10+, PyTorch 2.0+, NumPy 1.24+.

Quick start

End-to-end pipeline check on synthetic data — trains a model, runs 3-fold cross-validation, fits a calibration curve, computes per-locus explainability:

python -m hla_survival.demo

Module layout

File	Purpose
config.py	Dataclass-based hyperparameters
data.py	HLATransplantDataset, TransplantRecord, synthetic generator
model.py	Sequence transformer + allele embeddings + clinical MLP + fusion + survival head
losses.py	Cox partial log-likelihood, DeepHit NLL + ranking loss
metrics.py	Harrell's concordance index
calibration.py	Breslow baseline hazard, S(t|x), Kaplan-Meier, reliability curve, IBS
explain.py	Integrated Gradients (clinical) + gradient×embedding (alleles, sequences)
train.py	train, evaluate, predict_risks, cross_validate
demo.py	End-to-end example on synthetic data

Plugging in real data

Replace make_synthetic_records with a loader that produces TransplantRecord instances. Each record holds:

• donor_sequences / recipient_sequences: dict[locus] -> (allele1_seq, allele2_seq) amino-acid strings (pull from IMGT/HLA)
• donor_alleles / recipient_alleles: dict[locus] -> (allele1_id, allele2_id) integer codes from your allele→ID mapping
• clinical: 1-D NumPy array of standardised tabular features
• time, event: follow-up time in years and event indicator (1 = graft loss, 0 = censored)

Adjust cfg.allele.n_alleles to match your vocabulary size and cfg.clinical.n_features to match your tabular feature count.

Status

Research prototype — not validated for clinical use. C-index, calibration, and explainability outputs should be interpreted in consultation with clinical immunology expertise.

License

MIT — see LICENSE.