Official code and model-weight release for the submitted manuscript:
Decomposing retinal age-clock residuals reveals disease-associated systemic heterogeneity in human aging
Biological-age clocks link aging to disease and healthspan, but image-derived clocks usually reduce this relationship to a single age gap whose biological meaning is ambiguous. We reasoned that a healthy retinal aging trajectory could provide a reference from which disease-associated deviations can be decomposed. We therefore developed PODE, a physiology-guided residual-decomposition framework based on clinical phenotypes. A VisionFM-based fundus model trained on 112,019 images from 56,019 relatively healthy participants established a calibrated retinal age anchor (mean absolute error, 2.48 years). When applied to 46,369 hospital-based participants with concurrent clinical phenotyping, residuals around this anchor showed non-monotonic associations with cardiometabolic and inflammatory burden: both positive and extreme negative residuals were adverse, revealing disease-associated pseudo-youth. PODE then partitioned these residuals into hemodynamic, metabolic, renal, hematologic and immune-associated components, and an analogous MRI implementation recovered cognition-, amyloid-, tau- and neuroinjury/glial-linked residual axes. PODE reframes age-clock error as a physiology-resolved signal for studying human aging-disease heterogeneity.
PODE organizes aging-clock modeling into three manuscript components:
- PODE-Base: normative age-anchor training and inference.
- PODE-Mapper: population-level phenotype mapping, UMAP clustering, SHAP analysis, and tabular transformer analysis.
- PODE-Splitter: physiology-guided orthogonal disentanglement of residual aging signals.
This release also includes the cross-modal BrainMRI implementation used to test the same Base/Splitter logic on 3D brain MRI.
PODE/
├── pode_base/ # Fundus PODE-Base training, evaluation, saliency, downstream analysis
├── pode_mapper/ # PODE-Mapper: XGBoost/SHAP, Tabular Transformer, UMAP/K-means
├── pode_splitter/ # Fundus PODE-Splitter training, evaluation, and prediction analysis
├── BrainMRI/ # BrainMRI base-age and splitter implementation
│ ├── brain_base/
│ ├── brain_splitter/
│ └── shared3d/
├── shared/ # Fundus data utilities and metrics
├── fig_draw/ # Paper figure and subgroup plotting scripts
├── docs/
├── requirements.txt
├── requirements-brainmri.txt
└── pyproject.toml
cd /path/to/PODE
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pip install -e .For BrainMRI workflows:
pip install -r requirements-brainmri.txtRun commands from the repository root.
python -m pode_base.train --help
python -m pode_base.evaluation.evaluate --help
python -m pode_mapper.umap_clustering.generate_umap --help
python -m pode_splitter.train --help
python -m BrainMRI.brain_base.train_age_ordinal --help
python -m BrainMRI.brain_splitter.train --helpThe four public weight packages are hosted on Hugging Face:
| Package | Public checkpoint |
|---|---|
| Fundus PODE-Base | pode_fundus_base.pth |
| Fundus PODE-Splitter | pode_fundus_splitter.pth |
| BrainMRI PODE-Base | pode_brain_mri_base.pth |
| BrainMRI PODE-Splitter | pode_brain_mri_splitter.pth |
Public checkpoint filenames are intentionally version-free. Package metadata and SHA256 checksums are available in the Hugging Face repository.
Raw clinical, fundus, ADNI, and IXI data are not included in this repository. See DATA_AVAILABILITY.md for data-access and restricted-data notes. Public examples should use synthetic or user-supplied manifests with the documented column schema.
BrainMRI code does not hardcode local training paths. Set these environment variables when running preprocessing or training against local data:
export PODE_BRAINIAC_ROOT=/path/to/BrainIAC
export PODE_IXI_DIR=/path/to/IXI
export PODE_ADNI_DIR=/path/to/ADNI
export PODE_BRAINMRI_PREPROC_ROOT=/path/to/preprocessed/brainmriThis manuscript has been submitted. Citation details will be updated after publication.
Ricardo Chu (GitHub/Hugging Face: irrrricardo)