Probabilistic HbA1c Forecasting in Type 2 Diabetes Under Treatment-Conditioned Scenarios Using Real-World Primary Care Data

Training and evaluation at 3, 6, 9 and 12 months. Environment used: Python 3.14.

Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Data

Each row represents one quarter for a patient: idp identifies the patient and time_idx is a consecutive integer index within each patient. Missing values and duplicate patient/time pairs are not allowed. Each patient must have at least 15 observations. Static variables must remain constant.

Required columns:

• Static: sex, debut_age.
• Age: age.
• Medication: BIGUANIDA, GLITAZONA, SULFONI, iDPP4, iSGLT2, GLINIDA, arGLP1, INSULINA.
• Other categorical variables: INSULINA_RAPIDA, HEART_FAIL, STROKE, RET_DIAB, CKD, NEURO, ART_PER, CAR_ISQ, DISLIPEM, HTA, alcohol, tobacco.
• Continuous: ACR, eGFR, HDLcol, LDLcol, colTOT, TG, SBP, DBP, BMI, HbA1c.

Running the models

All four models perform hyperparameter tuning followed by training and evaluation across five folds:

python TFT_cv.py --data "<path_to_csv>" --trials XX --max-epochs XX --output benchmark/comparison
python LSTM_cv.py --data "<path_to_csv>" --trials XX --max-epochs XX --output benchmark/comparison
python GRU_cv.py --data "<path_to_csv>" --trials XX --max-epochs XX --output benchmark/comparison
python transformer_cv.py --data "<path_to_csv>" --trials XX --max-epochs XX --output benchmark/comparison

Protocol

A subset of 5,000 patients is reserved for tuning and excluded from all CV folds. The remaining patients are divided into five patient folds using seed 42 and a mapping generated locally at results/patient_folds.json. For each fold, a fresh model is trained using the other four folds; the final four observations of development patients are reserved as temporal validation targets. Testing uses one final forecast origin per patient with 7--15 historical observations. Preprocessing is fitted on training data only. Checkpoints, predictions and MAE by horizon are saved to the output directory.

TFT is trained with a multi-quantile loss and evaluated using its median prediction; the other models are trained with MAE.