{"id":31765341,"url":"https://github.com/lemuelpuglisi/brlp","last_synced_at":"2025-10-10T00:15:44.868Z","repository":{"id":238635460,"uuid":"796582316","full_name":"LemuelPuglisi/BrLP","owner":"LemuelPuglisi","description":"[MICCAI'2024, Oral] Official implementation of the Brain Latent Progression (BrLP) method from \"Enhancing Spatiotemporal Disease Progression Models via Latent Diffusion and Prior Knowledge\"","archived":false,"fork":false,"pushed_at":"2025-08-01T15:35:30.000Z","size":1530,"stargazers_count":97,"open_issues_count":1,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-01T17:39:30.813Z","etag":null,"topics":["brain-latent-progression","diffusion-models","disease-progression-model","image-generation","longitudinal","medical-image-analysis","medical-imaging","miccai","miccai2024","spatiotemporal-modeling"],"latest_commit_sha":null,"homepage":"https://lemuelpuglisi.github.io/blog/2024/brlp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LemuelPuglisi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-06T08:24:15.000Z","updated_at":"2025-08-01T15:35:34.000Z","dependencies_parsed_at":"2024-05-31T12:44:25.227Z","dependency_job_id":"d7542395-d65a-4cdb-a4c8-e6e915d35bf4","html_url":"https://github.com/LemuelPuglisi/BrLP","commit_stats":null,"previous_names":["lemuelpuglisi/brlp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LemuelPuglisi/BrLP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemuelPuglisi%2FBrLP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemuelPuglisi%2FBrLP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemuelPuglisi%2FBrLP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemuelPuglisi%2FBrLP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LemuelPuglisi","download_url":"https://codeload.github.com/LemuelPuglisi/BrLP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LemuelPuglisi%2FBrLP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002388,"owners_count":26083356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brain-latent-progression","diffusion-models","disease-progression-model","image-generation","longitudinal","medical-image-analysis","medical-imaging","miccai","miccai2024","spatiotemporal-modeling"],"created_at":"2025-10-10T00:15:40.759Z","updated_at":"2025-10-10T00:15:44.862Z","avatar_url":"https://github.com/LemuelPuglisi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![brlp](assets/readme-brlp-v2.png)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href='https://www.sciencedirect.com/science/article/pii/S1361841525002816'\u003e\n    \u003cimg src='https://img.shields.io/badge/Journal-PDF-green?style=for-the-badge\u0026logo=adobeacrobatreader\u0026logoWidth=20\u0026logoColor=white\u0026color=94DD15' alt='Paper PDF'\u003e\n  \u003c/a\u003e\n  \u003ca href='https://papers.miccai.org/miccai-2024/paper/0511_paper.pdf'\u003e\n    \u003cimg src='https://img.shields.io/badge/MICCAI-PDF-green?style=for-the-badge\u0026logo=adobeacrobatreader\u0026logoWidth=20\u0026logoColor=white\u0026color=94DD15' alt='Paper PDF'\u003e\n  \u003c/a\u003e\n  \u003ca href='https://youtu.be/6YKz2MNM4jg?si=nkG21K4lIgLrH-pK'\u003e\n    \u003cimg src='https://img.shields.io/badge/Video-YouTube-red?style=for-the-badge\u0026logo=youtube\u0026logoColor=white\u0026color=FF3737' alt='Video'\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003eEnhancing Spatiotemporal Disease Progression Models via Latent Diffusion and Prior Knowledge\u003c/h4\u003e\n\n\u003ch4 align=\"center\"\u003e\u003ca href=\"https://lemuelpuglisi.github.io/\"\u003eLemuel Puglisi\u003c/a\u003e, \u003ca href=\"https://profiles.ucl.ac.uk/3589\"\u003eDaniel C. Alexander\u003c/a\u003e, \u003ca href=\"https://daniravi.wixsite.com/researchblog\"\u003eDaniele Ravì\u003c/a\u003e\u003c/h4\u003e\n\nhttps://github.com/user-attachments/assets/28ad3693-5e3e-4f6e-9bbc-485424fbbee2\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#training\"\u003eTraining\u003c/a\u003e •\n  \u003ca href=\"#inference\"\u003eCLI Application\u003c/a\u003e •\n  \u003ca href=\"#citing\"\u003eCite\u003c/a\u003e\n\u003c/p\u003e\n\n\n**NEWS**\n* 🎉 BrLP has been awarded the runner-up position for the Media Best Paper Award at MICCAI 2025!\n* 🎉 Our [extension paper](https://arxiv.org/pdf/2502.08560) has been accepted for publication in Medical Image Analysis (*IF=11.8*)\n* 🎉 A [new paper](https://www.spiedigitallibrary.org/conference-proceedings-of-spie/13406/1340621/A-technical-assessment-of-latent-diffusion-for-Alzheimers-disease-progression/10.1117/12.3047135.short) from Vanderbilt University has replicated our results on the [BLSA](https://www.blsa.nih.gov/) dataset!\n* 🆕 The [short guide on using the BrLP CLI](https://lemuelpuglisi.github.io/blog/2024/brlp/) is out!\n* 🎉 BrLP has been nominated and shortlisted for the MICCAI Best Paper Award! (top \u003c1%)\n* 🎉 BrLP has been early-accepted and selected for **oral presentation** at [MICCAI 2024](https://conferences.miccai.org/2024/en/) (top 4%)!\n\n\n\n## Table of Contents\n- [Installation](#installation)\n- [Data preparation](./REPR-DATA.md)\n- [Training](#training)\n- [Pretrained models](#pretrained-models)\n- [Acknowledgements](#acknowledgements)\n- [Citing our work](#citing)\n\n## Installation\n\nDownload the repository, `cd` into the project folder and install the `brlp` package:\n\n```console\npip install -e .\n```\nWe recommend using a separate environment (see [Anaconda](https://www.anaconda.com/)). The code has been tested using python 3.9, however we expect it to work also with newer versions.\n\n## Data preparation\n\nCheck out our document on [*Data preparation and study reproducibility*](./REPR-DATA.md). This file will guide you in organizing your data and creating the required CSV files to run the training pipelines.\n\n\n## Training\n![](assets/pipeline.png)\n\n\nTraining BrLP has 3 main phases that will be discribed in the subsequent sections. Every training (except for the auxiliary model) can be monitored using `tensorboard` as follows:\n\n```console\ntensorboard --logdir runs\n```\n\n\n\n### Train the autoencoder\n\nFollow the commands below to train the autoencoder.\n\n```console\n# Create an output and a cache directory\nmkdir ae_output ae_cache\n\n# Run the training script\npython scripts/training/train_autoencoder.py \\\n  --dataset_csv /path/to/A.csv \\\n  --cache_dir   ./ae_cache \\\n  --output_dir  ./ae_output\n```\n\nThen extract the latents from your MRI data:\n\n```console\npython scripts/prepare/extract_latents.py \\\n  --dataset_csv /path/to/A.csv \\\n  --aekl_ckpt   ae_output/autoencoder-ep-XXX.pth\n```\n\nReplace `XXX` to select the autoencoder checkpoints of your choice.\n\n### Train the UNet\n\nFollow the commands below to train the diffusion UNet. Replace `XXX` to select the autoencoder checkpoints of your choice.\n\n\n```console\n# Create an output and a cache directory:\nmkdir unet_output unet_cache\n\n# Run the training script\npython scripts/training/train_diffusion_unet.py \\\n  --dataset_csv /path/to/A.csv \\\n  --cache_dir   unet_cache \\\n  --output_dir  unet_output \\\n  --aekl_ckpt   ae_output/autoencoder-ep-XXX.pth\n```\n\n### Train the ControlNet\n\nFollow the commands below to train the ControlNet. Replace `XXX` to select the autoencoder and UNet checkpoints of your choice.\n\n```console\n# Create an output and a cache directory:\nmkdir cnet_output cnet_cache\n\n# Run the training script\npython scripts/training/train_controlnet.py \\\n  --dataset_csv /path/to/B.csv \\\n  --cache_dir   unet_cache \\\n  --output_dir  unet_output \\\n  --aekl_ckpt   ae_output/autoencoder-ep-XXX.pth \\\n  --diff_ckpt   unet_output/unet-ep-XXX.pth\n```\n\n### Auxiliary models\n\nFollow the commands below to train the DCM auxiliary model.\n\n```console\n# Create an output directory\nmkdir aux_output\n\n# Run the training script\npython scripts/training/train_aux.py \\\n  --dataset_csv /path/to/A.csv \\\n  --output_path aux_output\n```\n\nWe emphasize that any disease progression model capable of predicting volumetric changes over time is also viable as an auxiliary model for BrLP.\n\n## Inference\n\nOur package comes with a `brlp` command to use BrLP for inference. Check:\n```console\nbrlp --help\n```\n\nThe `--input` parameter requires a CSV file where you list all available data for your subjects. For an example, check to `examples/input.example.csv`. If you haven't segmented your input scans, `brlp` can perform this task for you using [SynthSeg](https://surfer.nmr.mgh.harvard.edu/fswiki/SynthSeg), but it requires that FreeSurfer \u003e= 7.4 be installed. The `--confs` parameter specifies the paths to the models and other inference parameters, such as LAS $m$. For an example, check `examples/confs.example.yaml`. \n\nRunning the program looks like this:\n\n![inference-preview](assets/inference.gif)\n\n\n## Pretrained models\n\nDownload the pre-trained models for BrLP:\n\n| Model                  | Weights URL                                                  |\n| ---------------------- | ------------------------------------------------------------ |\n| Autoencoder            | [link](https://studentiunict-my.sharepoint.com/:u:/g/personal/pgllml99h18c351e_studium_unict_it/EUxUFIQtkQ1EvBqojYA5BAYByIyHbttca5Mx1cU4bC6q3A?e=sCXSUA) |\n| Diffusion Model UNet   | [link](https://studentiunict-my.sharepoint.com/:u:/g/personal/pgllml99h18c351e_studium_unict_it/EQT7KJTtfmRAguf8_utWeJIBUJPsRRgPZlt94s2vNbwVFw?e=IjHnx7) |\n| ControlNet             | [link](https://studentiunict-my.sharepoint.com/:u:/g/personal/pgllml99h18c351e_studium_unict_it/EYtVvH47dFJJnH8gtwSMA-MB8c3pm4_Z9g5F_IG1OKxW9Q?e=CzvGT4) |\n| Auxiliary Models (DCM) | [link](https://studentiunict-my.sharepoint.com/:u:/g/personal/pgllml99h18c351e_studium_unict_it/EXJDQqLNCwBFkt2J6zg1kpwBS_1hAZoBfGy5AfcGOBZvHQ?e=Z05kOG) |\n\n## Acknowledgements\n\nWe thank the maintainers of open-source libraries for their contributions to accelerating the research process, with a special mention of [MONAI](https://monai.io/) and its [GenerativeModels](https://github.com/Project-MONAI/GenerativeModels/tree/main) extension.\n\n## Citing\n\nMedical Image Analysis:\n\n```bib\n@article{puglisi2025brain,\n  title={Brain latent progression: Individual-based spatiotemporal disease progression on 3D brain MRIs via latent diffusion},\n  author={Puglisi, Lemuel and Alexander, Daniel C and Rav{\\`\\i}, Daniele},\n  journal={Medical Image Analysis},\n  year={2025}\n}\n```\n\nMICCAI 2024 proceedings:\n\n```bib\n@inproceedings{puglisi2024enhancing,\n  title={Enhancing spatiotemporal disease progression models via latent diffusion and prior knowledge},\n  author={Puglisi, Lemuel and Alexander, Daniel C and Rav{\\`\\i}, Daniele},\n  booktitle={International Conference on Medical Image Computing and Computer-Assisted Intervention},\n  pages={173--183},\n  year={2024},\n  organization={Springer}\n}\n```\n\n\nSPIE Medical Imaging 2025 proceedings: \n```bib\n@inproceedings{mcmaster2025technical,\n  title={A technical assessment of latent diffusion for Alzheimer's disease progression},\n  author={McMaster, Elyssa and Puglisi, Lemuel and Gao, Chenyu and Krishnan, Aravind R and Saunders, Adam M and Ravi, Daniele and Beason-Held, Lori L and Resnick, Susan M and Zuo, Lianrui and Moyer, Daniel and others},\n  booktitle={Medical Imaging 2025: Image Processing},\n  volume={13406},\n  pages={505--513},\n  year={2025},\n  organization={SPIE}\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemuelpuglisi%2Fbrlp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flemuelpuglisi%2Fbrlp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemuelpuglisi%2Fbrlp/lists"}