{"id":21362169,"url":"https://github.com/cgalaz01/aladdin_cmr_la","last_synced_at":"2025-07-13T02:32:56.252Z","repository":{"id":212664639,"uuid":"728414452","full_name":"cgalaz01/aladdin_cmr_la","owner":"cgalaz01","description":"Source code for Aladdin, a complete workflow for 3D MRI left atrium motion analysis","archived":false,"fork":false,"pushed_at":"2024-09-13T12:22:33.000Z","size":78764,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-09-14T03:27:56.404Z","etag":null,"topics":["cardiac","image-registration","image-segmentation","left-atrium","medical-imaging","mri","tensorflow"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2312.09387","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cgalaz01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-06T22:24:04.000Z","updated_at":"2024-09-13T12:22:36.000Z","dependencies_parsed_at":"2024-09-05T17:20:36.475Z","dependency_job_id":"80d00d00-f809-438a-bc67-9a5d2268954e","html_url":"https://github.com/cgalaz01/aladdin_cmr_la","commit_stats":null,"previous_names":["cgalaz01/aladdin_cmr_la"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgalaz01%2Faladdin_cmr_la","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgalaz01%2Faladdin_cmr_la/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgalaz01%2Faladdin_cmr_la/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgalaz01%2Faladdin_cmr_la/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cgalaz01","download_url":"https://codeload.github.com/cgalaz01/aladdin_cmr_la/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225850164,"owners_count":17534067,"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","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":["cardiac","image-registration","image-segmentation","left-atrium","medical-imaging","mri","tensorflow"],"created_at":"2024-11-22T06:14:08.701Z","updated_at":"2024-11-22T06:14:09.836Z","avatar_url":"https://github.com/cgalaz01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aladdin: High-Resolution Maps of Left Atrial Displacements and Strains Estimated with 3D CINE MRI\n\nThis repository is the source code for Aladdin. Details on the workflow can be found here: https://arxiv.org/abs/2312.09387\n\nSource code and file descriptions can be found in the subdirectory: https://github.com/cgalaz01/aladdin_cmr_la/tree/main/src\n\nSupplementary figures of the paper can be found in the subdirectory: https://github.com/cgalaz01/aladdin_cmr_la/tree/main/supplements\n\n![workflow](supplements/la_workflow.jpg \"Workflow overview of Aladdin\")\n\nThis is a complete motion analysis workflow (displacement and strains) of the left atrium (LA) using 3D Cine MRI scans. This aim is to identify regional motion abnormalities that can be attributed to an underlying condition. \n\nThe workflow consists of:\n* Online few-shot segmentation network to identify the contour of the LA across the whole cardiac cycle\n* Online image registration network to estimate the displacement vector fields (DVFs)\n* Strain calculation from the DVFs\n* Strain and DVFs atlas construction\n* Regional abnormality detection from the atlas distribution\n\n## Setup\nTo download the code to your local repository, we suggest using Git:\n```shell\ngit clone https://github.com/cgalaz01/aladdin_cmr_la.git\n```\n\nThe code is implemented in Python and all libraries and their versions can be found in the file 'environment.yml'. To setup the environment we suggest using Anaconda.\nTo install with Anaconda:\n```shell\n# Navigate to the root directory\ncd aladdin_cmr_la\n# To create a new conda environment and install all dependencies:\nconda env create -f environment.yml\n# Now activate the environment\nconda activate aladdin\n```\n\n## Data\t\nThe data and atlas are available at: https://zenodo.org/records/13645121\n\nTo easiest way to include the data in the repository at the expected directories is by running the following command in the root:\n```shell\npython get_data.py\n```\n\nThe expected location of the data is:\n```\naladdin_cmr_la/data/train\n```\nwhere each subject's data is located in its own subfolder. The only folder naming constraint is that patients with a known pathology should have a suffix of 'PAT' so they are not included in the atlas construction. Within each patient subfolder, there should be two more folders, 'images' and 'segmentations' which contain the left atrium images and segmentations respectively.\nThe following is an example folder structure:\n```\naladdin_cmr_la/\n└── data/\n\t└── train/\n\t\t├── HLTH01/\n\t\t│\t├── images/\n\t\t│\t│\t├── 00.nii.gz\n\t\t│\t│\t├── ...\n\t\t│\t│\t└── 19.nii.gz\n\t\t│\t└── segmentations/\n\t\t│\t\t├── 00.nii.gz\n\t\t│\t\t├── ...\n\t\t│\t\t└── 19.nii.gz\n\t\t└── PAT01/\n\t\t\t├── images/\n\t\t\t│\t├── 00.nii.gz\n\t\t\t│\t├── ...\n\t\t\t│\t└── 19.nii.gz\n\t\t\t└── segmentations/\n\t\t\t\t├── 00.nii.gz\n\t\t\t\t├── ...\n\t\t\t\t└── 19.nii.gz\n```\n\nFrom the downloaded data:\n- aladdin_cmr_la/data contains the images and segmentation maps.\n- aladdin_cmr_la/data_nn contains the images and nnU-Net predicted segmentation maps.\n- aladdin_cmr_la/src/atlas_construction/_atlas_output contains the structural atlas used to register a case to.\n- aladdin_cmr_la/src/atlas_construction/_atlas_stats_output contains the healthy population's average displacement vector fields (DVFs) and prinicpal strains (Epr) used to calculate the Mahalanobis distance between an individual case and the atlas.\n\t\t\t\n## Running nnU-Net (Segmentation network)\nTo train nnU-Net follow the instructionas at: https://github.com/MIC-DKFZ/nnUNet.\n\nThe online-learning variant is simply achieved by converting each case to a separate dataset. The fold split is changed to train on cardiac phases 0, 8 and 15 and validate on the remaining cases.\n\n\n## Running Aladdin-R (Image registration network)\nTo train Aladdin-R and generate the predicted displacement vector fields, simply run the following commands:\n```shell\ncd src\npython run_training.py\n```\n\nIt is expected that the segmentations of all phases are available for training in the data folder.\n\nThe best weights per patient will be stored in the folder:\n```\naladdin_cmr_la/checkpoint/aladdin_r_\u003cdate_time\u003e/\u003cpatient\u003e/\n```\nSimilarly, the predicted displacement vector fields across the whole cardiac cycle will be saved in the folder:\n```\naladdin_cmr_la/outputs_aladdin_r_\u003cdate_time\u003e_nifti/displacement_field/\u003cpatient\u003e/full/\n```\nor just on the non-dilated contour:\n```\naladdin_cmr_la/outputs_aladdin_r_\u003cdate_time\u003e_nifti/displacement_field/\u003cpatient\u003e/contour/\n```\nThe transformed non-dilated contours are also saved:\n```\naladdin_cmr_la/outputs_aladdin_r_\u003cdate_time\u003e_nifti/segmentation/\u003cpatient\u003e/contour/\n```\n\n## Running atlas construction\nFor the atlas construction, it is expected that in the data folder, the images, segmentations and displacements for all cardiac phases are present (outputs from Aladdin-S and Aladdin-R):\n```\naladdin_cmr_la/\n└── data/\n\t└── train/\n\t\t└── \u003cpatient\u003e/\n\t\t\t├── images/\n\t\t\t├── segmentations/\n\t\t\t└── displacements/\n\t\t\t\t└── full/\n```\n\t\t\t\t\t\nTo construct a new atlas, we execute the following commands:\n```shell\ncd src/atlas_construction\npython atlas_generation.py\t\t# Constructs the structure of the atlas from the healthy participants\npython register_to_atlas.py\t\t# Calculates the strains and maps the displacement and strain values to the atlas\npython atlas_stats.py \t\t\t# Obtains the distribution of the displacement and strain values of healthy participants mapped to the atlas\npython registration_stats.py\t\t# Calculates the Mahalanobis distance of each case to the atlas' distribution of displacement and strain values\n```\n\nThe relevant results will be stored in the folder:\n```\naladdin_cmr_la/src/atlas_construction/_atlas_output/\n```\n\n## Citation\nIf you found this code useful for your project please cite as:\n```\n@misc{galazis2023highresolution,\n      title={High-Resolution Maps of Left Atrial Displacements and Strains Estimated with 3D CINE MRI and Unsupervised Neural Networks}, \n      author={Christoforos Galazis and Samuel Shepperd and Emma Brouwer and Sandro Queirós and Ebraham Alskaf and Mustafa Anjari and Amedeo Chiribiri and Jack Lee and Anil A. Bharath and Marta Varela},\n      year={2023},\n      eprint={2312.09387},\n      archivePrefix={arXiv},\n      primaryClass={cs.CV}\n}\n```\n\t\n## Acknowledgement\nThis project was supported by the UK Research and Innovation (UKRI) Centres of Doctoral Training (CDT) in Artificial Intelligence for Healthcare (AI4H) http://ai4health.io (Grant No. EP/S023283/1), the NIHR Imperial Biomedical Research Centre (BRC), and the British Heart Foundation Centre of Research Excellence at Imperial College London (RE/18/4/34215).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgalaz01%2Faladdin_cmr_la","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcgalaz01%2Faladdin_cmr_la","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgalaz01%2Faladdin_cmr_la/lists"}