{"id":27086993,"url":"https://github.com/icon-lab/pflsynth","last_synced_at":"2025-10-10T15:45:00.744Z","repository":{"id":118019023,"uuid":"517358552","full_name":"icon-lab/pFLSynth","owner":"icon-lab","description":"One Model to Unite Them All: Personalized Federated Learning of Multi-Contrast MRI Synthesis (pFLSynth)","archived":false,"fork":false,"pushed_at":"2024-01-23T07:56:18.000Z","size":6070,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-01-23T09:02:17.182Z","etag":null,"topics":["deep-learning","federated-learning","image-synthesis","image-to-image-translation","mri","personalization","pytorch"],"latest_commit_sha":null,"homepage":"","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/icon-lab.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}},"created_at":"2022-07-24T15:15:13.000Z","updated_at":"2024-01-23T09:02:17.182Z","dependencies_parsed_at":null,"dependency_job_id":"768e831e-55e6-45a5-94b8-228eabb78250","html_url":"https://github.com/icon-lab/pFLSynth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icon-lab%2FpFLSynth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icon-lab%2FpFLSynth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icon-lab%2FpFLSynth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icon-lab%2FpFLSynth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icon-lab","download_url":"https://codeload.github.com/icon-lab/pFLSynth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441007,"owners_count":20939236,"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":["deep-learning","federated-learning","image-synthesis","image-to-image-translation","mri","personalization","pytorch"],"created_at":"2025-04-06T05:49:07.087Z","updated_at":"2025-10-10T15:45:00.618Z","avatar_url":"https://github.com/icon-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pFLSynth\nOfficial Pytorch Implementation of personalized Federated Learning of MRI Synthesis(pFLSynth) which is described in the [following](https://arxiv.org/abs/2207.06509) paper:\n\nOne Model to Unite Them All: Personalized Federated Learning of Multi-Contrast MRI Synthesis. Onat Dalmaz, Usama Mirza, Gökberk Elmas, Muzaffer Özbey, Salman UH Dar, Emir Ceyani, Salman Avestimehr, Tolga Çukur. ArXiV. 2022.\n\n\u003cimg src=\"main.png\" width=\"600px\"/\u003e\n\u003cimg src=\"generator.png\" width=\"600px\"/\u003e\n\u003cimg src=\"pna.png\" width=\"600px\"/\u003e\n\n## Dependencies\n```\npython\u003e=3.6.9\ntorch\u003e=1.7.1\ntorchvision\u003e=0.8.2\nvisdom\ndominate\ncuda=\u003e11.2\n```\n## Installation\n- Clone this repo:\n```bash\ngit clone https://github.com/icon-lab/pFLSynth\ncd pFLSynth\n```\n\n# Data Preprocessing\n\nThis section details the steps required to preprocess the imaging data before it can be used for analysis.\n\n## Registration\n\nIn this step, different MRI sequences are aligned to a common space. The `register_sequences.py` script performs this task.\n\n### Prerequisites\n\n- FSL (FMRIB Software Library) must be installed on your system. You can download it from [FSL's official website](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki).\n- Python 3.x must be installed on your system.\n\n### Usage\n\nTo use the registration script, you need to set up the input and output paths according to the downloaded dataset's structure. Open the `register_sequences.py` script in your favorite text editor and follow the `# TODO` comments to customize the paths and sequence names.\n\n### Demo\n\nHere is a demo of how to configure and run the `register_sequences.py` script.\n\n1. Set the dataset root path where your MRI sequences are located:\n\n    ```python\n    # TODO: Replace with the path to the dataset's root directory\n    dataset_root_path = \"/path/to/dataset/root/\"\n    ```\n\n2. Set the output path where the registered volumes will be saved:\n\n    ```python\n    # TODO: Replace with the path to the output directory for the registered volumes\n    output_root_path = \"/path/to/output/root/\"\n    ```\n\n3. Customize the sequence names based on your dataset:\n\n    ```python\n    # TODO: Customize the MRI sequence names as per your dataset\n    sequences = {\n        'T1': 'T1w',  # Example: 'T1w' or 'T1_weighted'\n        'T2': 'T2w',  # Example: 'T2w' or 'T2_weighted'\n        'T2_FLAIR': 'FLAIR',  # Example: 'FLAIR' or 'PD' or 'T2_FLAIR'\n        # Add or remove sequences as needed\n    }\n    ```\n\n4. Run the script:\n\n    ```bash\n    python preprocess/register_sequences.py\n    ```\n\nThe script will process each subject sequentially, registering the specified sequences to the T1-weighted images and saving the results in the output directory.\n\n## Converting NIfTI to PNG\n\nAfter completing the registration process, the next step in the pipeline is to convert the NIfTI files into PNG format. This conversion process takes each slice of the 3D MRI data and saves it as a 2D cross-section. The `process_nii_to_png.py` script automates this task.\n\n### Usage\n\nTo use this script, you need to specify the input directory (where the NIfTI files are stored) and the output directory (where the PNG files will be saved).\n\n1. Set the input directory in the script:\n\n    ```python\n    # TODO: Set your input directory containing NIfTI files\n    input_directory = \"/path/to/input/directory\"\n    ```\n\n2. Set the output directory for the PNG files:\n\n    ```python\n    # TODO: Set your output directory for PNG files\n    output_directory = \"/path/to/output/directory\"\n    ```\n\n3. Run the script:\n\n    ```bash\n    python preprocess/process_nii_to_png.py\n    ```\n\nThis will process each NIfTI file, converting it into a series of 2D PNG images, each representing a slice from the 3D MRI data. The script organizes these PNG images into folders corresponding to their original NIfTI file names.\n\n### Note\n\n- It is advisable to have a backup of the original NIfTI files before running this script, as it involves reading and processing significant amounts of data.\n- Ensure that the input and output directories are set correctly to avoid any unintended data loss.\n\n## Combining Multi-contrast Images into a Single Composite Image\n\nFollowing the preprocessing steps, we combine the PNG images of individual contrasts (T1, T2, FLAIR) into a single composite image where each contrast is represented in a separate color channel.\n\n### Usage\n\nTo perform the combination of contrast images, run the `combine_contrasts.py` script, which takes the T1, T2, and FLAIR images and combines them into a single RGB image with transparency. The resulting images are saved to the specified output directory.\n\n1. Set the input directory where individual contrast PNG images are located:\n\n    ```python\n    # TODO: Set the path where the PNG images are stored\n    input_directory = \"/auto/data2/umirza/OASIS_png/\"\n    ```\n\n2. Set the output directory where the combined images will be saved:\n\n    ```python\n    # TODO: Set the path where the combined images will be saved\n    output_directory = \"/auto/data2/umirza/OASIS_full/\"\n    ```\n\n3. Run the script:\n\n    ```bash\n    python preprocess/combine_contrasts.py\n    ```\n\nEach saved image will have T1, T2, and FLAIR contrasts combined, facilitating the visualization of differences between contrasts in the same slice.\n\n### Note\n\n- Ensure that each contrast directory within the input directory contains the same number of corresponding slices.\n- The script will create the output directory if it does not exist, and it will overwrite existing files with the same name without warning.\n\n\n# Training and Testing Multi-Contrast MRI Synthesis Models\n\n\n## Training and Testing of pFLSynth\nTo initiate the federated training of the pFLSynth model and test it following training, please use the provided shell scripts. These scripts encapsulate all the necessary parameters and configurations required for the training and inference procedures. \n\n### Training\nTo start training, simply execute:\n\u003cbr /\u003e\n\n```bash\nbash train_pflsynth.sh\n```\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\nEnsure that train_pflsynth.sh is properly configured with the right paths and parameters specific to your dataset and training environment. \n\n### Inference\n\n```bash\nbash test.sh\n```\n\n## Training and Testing of Competing Methods\n\nThis repository includes several scripts for training/testing 6 different federated learning (FL) baselines and 3 different centralized benchmarks besides pFLSynth. These methods can be easily executed using the provided shell scripts.\n\n### Training\n\nTo train a specific competing method, run the corresponding shell script from the command line. Each script is named according to the method it trains. \nFor example, to train the FedBN method:\n```bash\nbash train_fedbn.sh\n```\n\nBelow are the available federated learning (FL) baselines and their respective script names:\n\n- FedBN: train_fedbn.sh\n- FedMRI: train_fedmri.sh\n- FedGAN: train_fedgan.sh\n- FedMed: train_fedmed.sh\n- FedMM: train_fedmm.sh\n- FedCycle: train_fedcycle.sh\n\nBelow are the available centralized benchmarks and their respective script names:\n\n- pFLSynth_cent: train_pflsynth_centralized.sh\n- pGAN_cent: train_pgan_centralized.sh\n- pix2pix_cent: train_pix2pix_centralized.sh\n\n### Inference\n\nThis repository includes a common script (`test.sh`) for performing inference with various competing methods, including pFLSynth. The `test.sh` script is designed to be easily adaptable for different methods. To use it for a particular competing method, you will need to update certain arguments in the script:\n\n1. **Model Name (`--name`)**: Specify the name of the experiment or model. This should match the name used during training.\n2. **Model Type (`--model`)**: Indicate the model type, which corresponds to the competing method being tested.\n3. **Generator Model (`--which_model_netG`)**: Choose the appropriate generator model for the method.\n4. **Task Name (`--task_name`)** (optional): If applicable, specify the task name.\n\nFor instance, to test with the FedBN method, you would modify the script as follows:\n\n```bash\npython3 test.py \\\n--dataroot /auto/data2/odalmaz/Datasets/IXI/T1_T2__PD/ \\\n--name FedBN_variable_setup_exp \\\n--gpu_ids 0 \\\n--dataset_mode aligned \\\n--model federated_synthesis \\\n--which_model_netG resnet_generator \\\n--which_direction AtoB \\\n--norm batch \\\n--output_nc 1 \\\n--input_nc 2 \\\n--checkpoints_dir checkpoints/ \\\n--phase test \\\n--how_many 10000 \\\n--serial_batches \\\n--results_dir results/ \\\n--dataset_name ixi \\\n--save_folder_name IXI \\\n--n_clients 4 \\\n--task_name t1_t2\n```\n\n# Model Evaluation\n\nAfter conducting inference using the `test.sh` script, the synthetic images generated by the chosen method are saved under the designated directories set within the script. To quantitatively evaluated image quality, follow the steps below to locate and analyze the generated images. Note that the evaluations considered here involve reference-based quality metrics, so synthetic images will be compared against ground-truth images for the target contrast. \n\nThe output images from inference are stored in directories with the following naming convention:\n\n```bash\n/results/\u003cname\u003e/test_\u003cwhich_epoch\u003e_\u003cdataset\u003e_\u003ctask_name\u003e/images/\n```\n\n- `\u003cname\u003e`: Represents the experiment name or setup.\n- `\u003cwhich_epoch\u003e`: Indicates the specific epoch of the test, typically 'latest' or a specific epoch number.\n- `\u003cdataset\u003e`: Which dataset\n- `\u003ctask_name\u003e`: Describes the task for which inference was run (e.g., 't1_t2').\n\n## PSNR/SSIM Calculation\n\n### Overview\nThis script calculates the Peak Signal-to-Noise Ratio (PSNR) and Structural Similarity Index (SSIM) between pairs of synthetic and ground-truth target-contrast images.\n\n### Usage\nTo use the PSNR/SSIM calculation script, you need to specify the directory containing the actual and synthetic images generated by your model. The script assumes the presence of corresponding paired ground-truth images in the same directory.\n\nCommand:\n```bash\npython evaluation/psnr_ssim.py --fake_dir \u003cpath_to_results_directory\u003e [--normalize \u003c0 or 1\u003e]\n```\n## FID Calculation\n\n### Overview\nThe Frechet Inception Distance (FID) is a widely used metric to assess the quality of images generated by GANs. It compares the distribution of generated images to that of actual images.\n\nThis script calculates the Frechet Inception Distance (FID) between datasets of actual and synthetic target-contrast images.\n\n### Usage\nTo calculate FID, you need to specify the directory containing the actual and synthetic images generated by your model. The script assumes the presence of corresponding ground-truth images (they may or may not be paired) in the same directory.\n\nCommand:\n```bash\npython evaluation/fid.py --p1 \u003cpath_to_results_directory\u003e [--gpu_ids \u003cgpu_id\u003e] [--multiprocessing] [--batch-size \u003cbatch_size\u003e]\n```\n\n# Citation\nPreliminary versions of pFLSynth are presented in [MICCAI DeCaF](https://link.springer.com/chapter/10.1007/978-3-031-18523-6_8),  [NeurIPS Medical Imaging Meets](https://www.cse.cuhk.edu.hk/~qdou/public/medneurips2022/103.pdf) (Oral), and IEEE ISBI 2023.\nYou are encouraged to modify/distribute this code. However, please acknowledge this code and cite the paper appropriately.\n```\n@misc{dalmaz2022pflsynth\n  doi = {10.48550/ARXIV.2207.06509},\n  \n  url = {https://arxiv.org/abs/2207.06509},\n  \n  author = {Dalmaz, Onat and Mirza, Usama and Elmas, Gökberk and Özbey, Muzaffer and Dar, Salman UH and Ceyani, Emir and Avestimehr, Salman and Çukur, Tolga},\n  \n  keywords = {Image and Video Processing (eess.IV), Computer Vision and Pattern Recognition (cs.CV), Machine Learning (cs.LG), FOS: Electrical engineering, electronic engineering, information engineering, FOS: Electrical engineering, electronic engineering, information engineering, FOS: Computer and information sciences, FOS: Computer and information sciences},\n  \n  title = {One Model to Unite Them All: Personalized Federated Learning of Multi-Contrast MRI Synthesis},\n  \n  publisher = {arXiv},\n  \n  year = {2022},\n  \n  copyright = {arXiv.org perpetual, non-exclusive license}\n}\n\n```\nFor any questions, comments and contributions, please contact Onat Dalmaz (onat[at]ee.bilkent.edu.tr) \u003cbr /\u003e\n\n(c) ICON Lab 2022\n\n## Acknowledgments\nThis code uses libraries from [pGAN](https://github.com/icon-lab/pGAN-cGAN) repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficon-lab%2Fpflsynth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficon-lab%2Fpflsynth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficon-lab%2Fpflsynth/lists"}