Merge pull request #81 from MELDProject/dev_v2.2.2

v2.2.2

Author: kwagstyl

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.1.0
+current_version = 2.2.2
 commit = True
 tag = True
 files = setup.py meld_graph/__init__.py

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [v2.2.2] - 2025-04-29
+### Fixed
+- Fixed an issue in the backward registration process (from fsaverage_sym surface to native T1 volume) that caused a slight spatial shift (~a few millimeters) in lesion predictions on the right hemisphere.
+- Removed the requirement to specify scanner strength in demographics_file.csv for harmonisation. This resolves errors when scanner strength wasn’t 3T
+- Fixed the standalone script for merging predictions with the T1 volume, which previously failed when handling predictions with different values for salient vs. non-salient vertices.
+- Instructions for use of Docker Desktop ; Instructions to join the mailing list; Clarification on FAQ
+- Minor code cleanup for improved stability and maintainability
+
+### Notes
+- Require to download the test data again
+- Docker image `MELDproject/meld_graph:v2.2.2` is available.
+- `latest` tag now points to this version.
+
+## [v2.2.1] - 2024-11-28
+- Initial stable release of MELD Graph package.

README.md

@@ -10,6 +10,13 @@ Graph based FCD lesion segmentation for the [MELD project](https://meldproject.g
 
 This package is a pipeline to segment FCD-lesions from MRI scans. 
 
+**<span style="color: red;">SIGN UP TO THE MELD GRAPH MAILING LIST</span>**:
+We request that all MELD Graph users sign up to the mailing list. If you are using MELD Graph, please send an email to `meld.study@gmail.com` with the subject 'Request to be added to the MELD Graph mailing list' and provide use with your name and institute. This will ensure that we can update you about bug fixs and new releases. 
+
+**<span style="color: red;">EXISTING USERS: PLEASE UPDATE TO VERSION V2.2.2</span>**:
+We have released MELD Graph V2.2.2 which fixes a couple of issues found by users. For more information about the release please see [MELD Graph V2.2.2](https://github.com/MELDProject/meld_graph/releases/tag/v2.2.2). To update your code please follow the guidelines [Updating MELD Graph to V2.2.2](https://meld-graph.readthedocs.io/en/latest/FAQs.html#Updating-MELD-Graph-to-V2.2.2) from our FAQ.
+
+
 ![overview](https://raw.githubusercontent.com//MELDProject/meld_graph/main/docs/images/Fig1_pipeline.jpg)
 
 *Code Authors : Mathilde Ripart, Hannah Spitzer, Sophie Adler, Konrad Wagstyl*
@@ -31,7 +38,7 @@ This package also contains code for training and evaluating graph-based U-net le
 In addition to lesion segmentation, the model also contain auxiliary distance regression and hemisphere classification losses.
 
 For more information on how the algorithm was developed and expected performance - check our papers: 
-- Ripart et al., under revisions at JAMA Neurology -  Detection of epileptogenic focal cortical dysplasia using graph neural networks: a MELD study
+- [Ripart et al.,2025 JAMA Neurology -  Detection of epileptogenic focal cortical dysplasia using graph neural networks: a MELD study](https://jamanetwork.com/journals/jamaneurology/fullarticle/2830410)
 - [Spitzer, Ripart et al., 2022 Brain - the original MELD FCD pipeline and dataset](https://academic.oup.com/brain/advance-article/doi/10.1093/brain/awac224/6659752)
 - [Spitzer et al., 2023 MICCAI - the updated graph-based model architecture](https://arxiv.org/abs/2306.01375)
 
@@ -44,23 +51,26 @@ The MELD surface-based graph FCD detection algorithm is intended for research pu
 
 ### Installations available 
 You can install and use the MELD FCD prediction pipeline with :
-- [**docker container**](https://meld-graph.readthedocs.io/en/latest/install_docker.html) recommended for easy installation of the pipeline as all the prerequisite packages are already embedded into the container. Note: Dockers are not working on High Performance Computing (HCP) systems ; Not tested on Windows 
+- [**docker container**](https://meld-graph.readthedocs.io/en/latest/install_docker.html) recommended for easy installation of the pipeline as all the prerequisite packages are already embedded into the container. Note: Dockers are not working on High Performance Computing (HCP) systems
 - [**native installation**](https://meld-graph.readthedocs.io/en/latest/install_native.html) recommended for Mac and users that want to modify the code and/or use the code to train/test their own classifier. 
-- [**singularity container (Not tested yet)**](https://meld-graph.readthedocs.io/en/latest/install_singularity.html) enables to run a container on High Performance Computing (HCP) systems.
+- [**singularity container**](https://meld-graph.readthedocs.io/en/latest/install_singularity.html) enables to run a container on High Performance Computing (HCP) systems.
+
+**IMPORTANT NOTE**: The installations listed above are not supported on Virtual Machines. Please install MELD Graph on full Linux, Windows or MAC computers
 
 **YouTube tutorials available for the [docker installation](https://youtu.be/oduOe6NDXLA) and [native installation](https://youtu.be/jUCahJ-AebM)**
 
 
 ### Running the pipeline 
 Once installed you will be able to use the MELD FCD prediction pipeline on your data following the steps:
 1. Prepare your data : [guidelines](https://meld-graph.readthedocs.io/en/latest/prepare_data.html)
-2. (OPTIONAL) Compute the harmonisation parameters : [guidelines](https://meld-graph.readthedocs.io/en/latest/harmonisation.html)
+2. Compute the harmonisation parameters : [guidelines](https://meld-graph.readthedocs.io/en/latest/harmonisation.html) (OPTIONAL but highly recommended)
 3. Run the prediction pipeline: [guidelines](https://meld-graph.readthedocs.io/en/latest/run_prediction_pipeline.html)
 4. Interpret the results: [guidelines](https://meld-graph.readthedocs.io/en/latest/interpret_results.html)
 
 **YouTube tutorials available to run the [harmonisation step](https://youtu.be/te_TR6sA5sQ), to run the [prediction pipeline](https://youtu.be/OZg1HSzqKyc) and to [interpret the pipeline results](https://youtu.be/dSyd1zOn4F8)**
 
-Note: If you have a question or if you are running into issues at any stage (installation/use/interpretation), have a look at our [FAQs](https://meld-graph.readthedocs.io/en/latest/FAQs.html) page to see if we have not already answered them. 
+**FAQs** 
+If you have a question or if you are running into issues at any stage (installation/use/interpretation), have a look at our [FAQs](https://meld-graph.readthedocs.io/en/latest/FAQs.html) page as we may have already have a solution. 
 
 **What is the harmonisation process ?**
 
@@ -80,10 +90,14 @@ If you'd like to contribute to this code base, have a look at our [contribution
 
 ## Acknowledgments
 
-We would like to thank the [MELD consortium](https://meldproject.github.io//docs/collaborator_list.pdf) for providing the data to train this classifier and their expertise to build this pipeline.\
-We would like to thank [Lennart Walger](https://github.com/1-w) and [Andrew Chen](https://github.com/andy1764), for their help testing and improving the MELD pipeline to v1.1.0. \
-We would like to thank [Ulysses Popple](https://github.com/ulyssesdotcodes) for his help building the docs and dockers.
+We would like to thank 
+- the [MELD consortium](https://meldproject.github.io//docs/collaborator_list.pdf) for providing the data to train this classifier and their expertise to build this pipeline.\
+- [Lennart Walger](https://github.com/1-w) and [Andrew Chen](https://github.com/andy1764), for their help testing and improving the MELD pipeline to v1.1.0. \
+- [Ulysses Popple](https://github.com/ulyssesdotcodes) for his help building the docs and dockers.
+- [Cornelius Kronlage](https://github.com/ckronlage) highlighting issues in v2.2.1 and suggesting solutions in v2.2.2
 
 ## Contacts
 
 Contact the MELD team at `meld.study@gmail.com`
+
+*Please note that we are a small team and only have one day a week dedicated to the support of the MELD tools ([MELD Graph](https://github.com/MELDProject/meld_graph) and [AID-HS](https://github.com/MELDProject/AID-HS)). We will answer your emails as soon as we can!*

docs/FAQs.md

@@ -17,15 +17,14 @@ ModuleNotFoundError: No module named '_sysconfigdata_arm64_apple_darwin20_0_0'
 The issue happens because the code is trying to force-installing ARM64 specific packages on an Intel processor. 
 An alternative solution is to follow the steps below: 
 1. Remove the meld_graph environment that failed 
-conda remove -n meld_graph --all
-2. Open the `meldsetup.sh` file and replace the line `conda env create -f environment-mac.yml` by `conda env create -f environment.yml`
-3. Save the file and rebuilt the environment by running:
+`conda remove -n meld_graph --all`
+2. Open the `meldsetup.sh` file and replace the line `conda env create -f environment-mac.yml` with `conda env create -f environment.yml`
+3. Save the file and rebuild the environment by running:
 ```bash
 ./meldsetup.sh
 ```
 
-This might raises new issues about packages that could not be found or installed. Please contact the meld.study@gmail.com with information about the issue and the packages missing. 
-
+If this raises new issues about packages that could not be found or installed, please contact meld.study@gmail.com with information about the issue and the packages missing. 
 
 ### **Issue with Singularity - Not enough space when with creating the SIF**
 ```bash
@@ -50,6 +49,17 @@ Solution:
 
 ## **Issues & questions with pipeline use**
 
+### **I have an issue with FLAIR feature that does not exist**
+
+If you are running a subject with only a T1 scan and no FLAIR scan but you receive an issue like :
+```bash
+KeyError: "Unable to open object (object '.on_lh.gm_FLAIR_0.25.sm3.mgh' doesn't exist)"
+exit status 1
+```
+You are likely having this issue because you might have previously ran this same subject ID with a FLAIR scan and the FreeSurfer segmentation has been done using the FLAIR scan. Therefore, even if you remove the FLAIR scan from the input data and run again the command, the intermediate FreeSurfer outputs for that subject still contain FLAIR information, which will make the pipeline looks for FLAIR features but fail to find them.
+
+To avoid this in the future, if you want to run a same subject with and without FLAIR, you should create two separate input folders with two different subject's ID such as `sub-0001noflair` and `sub-0001flair`.
+
 ### **I have an issue during the harmonisation**
 
 If your issue looks like :
@@ -60,9 +70,18 @@ site_code, c_p, scanner = get_group_site(fs_id, demographic_file)
 TypeError: cannot unpack non-iterable NoneType object
 ```
 You are likely having an issue with the `demographics_file.csv` or the `list_subjects.txt` you provided. 
-- In the `demographics_file.csv`, check that there is no extra columns and that the columns names match what was provided as an [example](https://meld-graph.readthedocs.io/en/latest/prepare_data.html). Also ensure that the file is saved with comma separators (",") and not semicolon (";") which will prevent the code from properly reading the file. 
+- In the `demographics_file.csv`, check that there are no extra columns and that the column names match what was provided as an [example](https://meld-graph.readthedocs.io/en/latest/prepare_data.html). Also, ensure that the file is saved with comma separators (",") and not semicolon (";") which will prevent the code from properly reading the file. 
 - In the `list_subjects.txt`, ensure that there is no extra empty line at the end of the file.
 
+### **Issue during prediction - The pipeline works and then stop when running the predictions and saliencies**
+
+The error is likely due to a memory issue when the machine-learning model is called to predict.\
+If you are using Docker Desktop, it could be because the memory limit is set very low by default. 
+To fix this, you will need to:
+1) Increase the memory in the Docker Desktop settings (more help in this [post](https://stackoverflow.com/questions/43460770/docker-windows-container-memory-limit)
+2) Run the MELD Graph command again. 
+
+
 ### **Can I use precomputed FreeSurfer outputs in the pipeline ?**
 
 If prior to using this pipeline you already have processed a T1w scan (or T1w and FLAIR scans) with the `recon-all` pipeline from FreeSurfer **V6.0** or **V7.2**, you can use the output FreeSurfer folder for this patient in the pipeline. The pipeline will use those outputs and skip the FreeSurfer segmentation.  
@@ -88,15 +107,94 @@ sub-0002
     ├── trash
 ```
 
-### **Can I use the MELD Graph pipeline on scans that contains previous resection cavities?**
+### **Can I use the MELD Graph pipeline on scans that contain previous resection cavities?**
 
 The short answer is no. 
 
 The MELD Graph pipeline has not been trained on scans that contains resection cavities. Such scans will likely induce errors in the brain segmentation which will bias the prediction. 
 
-If the patient already had surgery, we recommand to use the scans that were acquired prior this surgery and use those to run in the pipeline
+If the patient already had surgery, we recommand to use the scans that were acquired prior to the surgery and use those to run in the pipeline
 
 ###  **Can I use the MELD Graph pipeline on scans with other pathologies as well as FCD e.g. tumours?**
 If the other pathology is hippocampal sclerosis (E.g. this is a FCD IIIA), yes you can use MELD Graph. However, please note it will not detect the HS as it only analyses the cortex.
 
 If it is another pathology e.g. a tumour, the pipeline has not been developed / trained on other pathologies and may not detect them. Also, the other pathology may introduce large reconstruction errors in the FreeSurfer pipeline - causing errors. We therefore do not recommend using MELD Graph on patients with other cortical pathologies. 
+
+---
+
+## **Updating MELD Graph to V2.2.2**
+
+The instructions below are for users that already have used MELD Graph v2.2.1 on patients and would like to update to MELD Graph V2.2.2 while keeping the same meld_data folder.
+
+
+### 📥 **Get the updated code**
+
+1) Open a terminal in your meld_graph folder
+2) Pull the latest code from GitHub (it will pull the latest data while keeping your changes made to the code)
+```bash
+git stash
+git pull 
+git stash pop
+```
+**💻 Native Installation Users:** Your code is now up to date. You can go directly to the next step.
+
+**🐳 Docker Users:** You will also need to pull the latest docker image
+```bash
+docker pull MELDproject/meld_graph:latest
+```
+
+**🚀 Singularity Users:** You will also need to pull the latest image
+```bash
+singularity pull docker://MELDproject/meld_graph:latest
+```
+
+### 🗂️ **Update your meld_data_folder with the new test data**
+The command below will only download the test data and it should not overwrite the patients you have already ran.
+
+**WARNING**: It will overwrite the `demographics_file.csv` and `list_subjects.txt`. Please ensure to keep a copy of those files if you have modified them.
+
+**💻 Native Installation Users:** 
+```bash
+./meldgraph.sh prepare_classifier.py --update_test
+```
+
+**🐳 Docker Users:** 
+```bash
+DOCKER_USER="$(id -u):$(id -g)" docker compose run meld_graph python scripts/new_patient_pipeline/prepare_classifier.py --update_test
+```
+
+**🚀 Singularity Users:**
+```bash
+singularity exec meld_graph.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/prepare_classifier.py --update_test"
+```
+
+### ✔️ **Run pytest again**
+Follow the guidelines **"Verify installation"** to run the test again.
+- 💻[Native Installation Users](https://meld-graph.readthedocs.io/en/latest/install_native.html#verify-installation)
+- 🐳[Docker Users](https://meld-graph.readthedocs.io/en/latest/install_docker.html#verify-installation)
+- 🚀[Singularity Users](https://meld-graph.readthedocs.io/en/latest/install_singularity.html#verify-installation)
+
+
+### 🧠 **Update your predictions with the registration fix**
+If you want to update the predictions with the new registration for patients you have already ran through MELD Graph, please follow the instructions bellow:
+
+1) Create a list of ids of patients you want to rerun: e.g. `list_subjects_rerun_v2.2.2.txt`
+
+2) Then run one of the commands below. It will use the predictions already existing for your patient. 
+
+**WARNING** This will overwrite the prediction registered to T1 and the patient report in `output/predictions_reports`
+
+**💻 Native Installation Users:** 
+```bash
+./meldgraph.sh run_script_prediction.py -ids list_subjects_rerun_v2.2.2.txt --skip_prediction
+```
+
+**🐳 Docker Users:** 
+```bash
+DOCKER_USER="$(id -u):$(id -g)" docker compose run meld_graph python scripts/new_patient_pipeline/run_script_prediction.py -ids list_subjects_rerun_v2.2.2.txt --skip_prediction
+```
+
+**🚀 Singularity Users:**
+```bash
+singularity exec meld_graph.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/run_script_prediction.py -ids list_subjects_rerun_v2.2.2.txt --skip_prediction"
+```

docs/harmonisation.md

@@ -3,15 +3,15 @@
 ## Information about the harmonisation
 Each MRI scanner / sequence  / FreeSurfer version will introduce small non-biological differences in the features that are calculated and used to predict where the FCD is. To help remove these biases, we advise harmonisation of your patient's features. This will make your patient's features "look like" the features we used to train the classifier. 
 
-Harmonisation of your patient data is not mandatory but recommended, to remove any bias induced by the scanner and sequence used. For more details on the MELD FCD predictions performances with and without harmonisation please refer to our (paper)[]
+Harmonisation of your patient data is not mandatory but recommended, to remove any bias induced by the scanner and sequence used. For more details on the MELD FCD predictions performances with and without harmonisation please refer to our [paper](https://jamanetwork.com/journals/jamaneurology/fullarticle/2830410)
 
 Here is the video tutorial detailing how to compute the harmonisation parameters - [Harmonisation tutorial](https://youtu.be/te_TR6sA5sQ).
 
 ## Compute the harmonisation paramaters 
 
 The harmonisation parameters are computed using [Distributed Combat](https://doi.org/10.1016/j.neuroimage.2021.118822).
 To get these parameters you will need a cohort of subjects acquired from the same scanner and under the same protocol (sequence, parameters, ...).
-Subjects can be controls and/or patients, but we advise to use ***at least 20 subjects*** to enable an accurate harmonisation (see (paper)[]). 
+Subjects can be controls and/or patients, but we advise to use ***at least 20 subjects*** to enable an accurate harmonisation (see (paper)[https://jamanetwork.com/journals/jamaneurology/fullarticle/2830410]). 
 Try to ensure the data are high quality (i.e no blurring, no artefacts, no cavities in the brain).
 Demographic information (e.g age and sex) will be required for this process. 
 WARNING: zero variance in the demographics information (e.g. having the same age for all subjects) will lead to Combat failures or errors. 

docs/images/example_demographic_csv.png

@@ -11,8 +11,6 @@
 install_docker
 install_native
 install_singularity
-
-FAQ
 ```
 
 
@@ -39,3 +37,12 @@ contributing
 
 ```
 
+```{toctree}
+:caption: Help
+:hidden:
+:maxdepth: 2
+
+FAQ
+
+```
+