AIGlucose: Viiraa Scalar MLP Models

This repository contains four PyTorch scalar prediction models trained on meal-level CGM and meal-context features. These models estimate different characteristics of the post-meal glucose response.

What Is In This Repo

Each target has its own folder with three files:

• <target>/model.pt
  • Serialized PyTorch checkpoint.
  • Includes model weights plus preprocessing metadata needed for inference.
• <target>/model_metadata.json
  • Target-specific training metadata, selected epoch, architecture, and cross-validation summary.
• <target>/training_summary.json
  • Epoch-level training loss trajectory for the final full-data refit.

Also present in this repo:

• model_multioutput.pkl
• reduce_model_multioutput.pkl

These two files were already in the repository prior to this upload and are kept for backward compatibility.

Models And What They Predict

1) peak_amplitude

• Predicts the peak glucose rise magnitude after a meal.
• Best for estimating spike size/severity.
• CV summary (from metadata):
  • pooled_r2_mean: 0.6239
  • spearman_mean: 0.7695
  • patient_macro_rmse_mean: 15.8045

2) peak_time_min

• Predicts time-to-peak (minutes) after meal start.
• Best for timing/kinetics use cases.
• CV summary:
  • pooled_r2_mean: 0.2317
  • spearman_mean: 0.4869
  • patient_macro_rmse_mean: 36.8870

3) auc_120_abs

• Predicts absolute 120-minute area under the post-meal glucose curve.
• Best for overall 2-hour glycemic exposure magnitude.
• CV summary:
  • pooled_r2_mean: 0.8445
  • spearman_mean: 0.8876
  • patient_macro_rmse_mean: 1412.5673

4) iauc_120

• Predicts incremental AUC over 120 minutes (baseline-adjusted exposure).
• Best for meal-induced excursion severity independent of baseline level.
• CV summary:
  • pooled_r2_mean: 0.6584
  • spearman_mean: 0.7945
  • patient_macro_rmse_mean: 1367.2898

Architecture Summary

• auc_120_abs: residual MLP, hidden dims [512, 512, 512]
• iauc_120: gated MLP, hidden dims [384, 192, 96]
• peak_amplitude: gated MLP, hidden dims [384, 192, 96]
• peak_time_min: plain MLP, hidden dims [256, 128]

All targets use standardized (zscore) target transforms in training metadata.

Input Requirements

These models were trained with meal-level tabular inputs combining:

• Meal information (meal type, calories/macros)
• CGM-derived wavelet/CWT features (same-anchor 5-360 configuration)
• Additional engineered meal-level context features

For correct inference, use the exact preprocessing metadata bundled in each checkpoint (model.pt) and align feature columns to the training schema.

Loading Example (PyTorch)

import torch

ckpt = torch.load("auc_120_abs/model.pt", map_location="cpu", weights_only=False)

# ckpt contains:
# - state_dict
# - model architecture settings
# - preprocessing metadata (numeric/categorical transforms)
# - target transform metadata

Use your project inference utilities to:

1. Apply numeric and categorical preprocessing from ckpt["preprocess"].
2. Build the matching model architecture from checkpoint config.
3. Load state_dict.
4. Invert target transform on predictions using checkpoint target preprocessing metadata.

Training Context

• Source family: scalar_cwt_5_360_same_anchor_mlp_cwtfeat_to_cwttarget
• Export type: full-dataset refit from best cross-validated variant per target
• Dataset scale at export time: 1452 meals across 45 patients

Important Limitations

• These are research models and are not validated for clinical decision-making.
• Generalization outside the source cohort may degrade.
• peak_time_min is notably harder than other targets (lower CV fit quality).
• Reproducibility requires matching feature engineering pipeline and preprocessing steps.

Citation / Contact

If you use these models, cite the associated Viiraa project/workflow and document the exact model commit hash from this repository.