FAQs

Issues & questions with installation

Issue with the MELD License

If your issue is:
```
ERROR: Could not find a MELD_LICENSE environment variable. Please ensure you have exported the MELD_LICENSE environment following the MELD Graph installation guidelines
```
This means that the MELD_LICENSE variable has not been exported/initialised in the environment (terminal) you are using. The variable should be automatically exported when using compose.yml file for the Docker, or meldgraph.sh for the native installation. You can export manually the environment variable by doing:
```
export MELD_LICENSE=<path_to_meld_license_file>
```
Please contact the team if the issue continues
If your issue is:
```
ERROR: The file meld_license.txt does not exist.
Please ensure you got the meld license file by filling the registration form provided in the MELD Graph installation guidelines and provided the right path to the file
```
This means that the meld_license.txt cannot be found in the main meld graph folder (where the code is). This can happen if you did not get the MELD license file or if the file was placed in an incorect folder. To get the proper MELD license ID, please fill in to the MELD registration form.

If your issue is:

ERROR: The license ID provided does not seem correct.
Please ensure you got the correct meld license file by filling the registration form provided in the MELD Graph installation guidelines and provided the right path to the file

or

ERROR: The license file meld_license.txt does not seem correct.
Please ensure you got the correct meld license file by filling the registration form provided in the MELD Graph installation guidelines and provided the right path to the file

This means that the MELD license file exists and is at the correct place, but the license ID does not exist or is incorrect. This can happen if you have used the Freesurfer license instead of the MELD license file, or if you have a fake MELD license file. To get the proper MELD license ID, please fill in the MELD registration form.

Issue with Native installation MAC Intel user - Issue when running meldsetup.sh

If you are a MAC user with an intel processor you will run into the issue below when running the command ./meldsetup.sh:

[...]
Installing pip dependencies: / Ran pip subprocess with arguments:
Pip subprocess output:
ERROR: CONDA_BUILD_SYSROOT or SDKROOT has to be set for cross-compiling
[...]
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:

Remove the meld_graph environment that failed conda remove -n meld_graph --all
Open the meldsetup.sh file and replace the line conda env create -f environment-mac.yml with conda env create -f environment.yml
Save the file and rebuild the environment by running:

./meldsetup.sh

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

INFO:    Creating SIF file... 
FATAL:   While performing build: while creating squashfs: create command failed: exit status 1:  
Write failed because No space left on device 

It means there is not enough space where the default singularity/apptainer cache and temporary directories are located. Usually the default cache is located in $HOME/.singularity/cache and the default temporary directory $HOME/.tmp
Solution:

You can make space in the default $HOME directory

You can change the singularity/apptainer cache and temporary directories for a folder where there is space:

export SINGULARITY_CACHEDIR=<path_folder_with_space> 
export SINGULARITY_TMPDIR=<path_folder_with_space>

Or with apptainer

export APPTAINER_CACHEDIR=<path_folder_with_space> 
export APPTAINER_TMPDIR=<path_folder_with_space>

Issues & questions with pipeline use

Variability in MELD Graph results when using T1w+FLAIR scans

We have received feedback regarding inconsistencies in MELD Graph results when using T1w+FLAIR scans compared to T1w scan alone. In some cases, the tool produces different outputs for the same patient scanned at different timepoints when FLAIR is included. Our investigation suggests that FLAIR images are more heterogeneous, even on the same scanner and acquisition. This variability can affect the reliability of the MELD Graph outputs.

Recommendation: We advise users to primarily rely on T1w scans for lesion detection. If additional sensitivity is needed, FLAIR can be added to explore other potential clusters. However, these results will need to be interpreted with extra caution, as FLAIR-based clusters may include more false positives.

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-0001 (containing only the T1w) and sub-0001withflair (containing T1w and FLAIR scans). You will need to run the MELD Graph pipeline twice.

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 :

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 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 :

INFO - subject id: Creating final training data matrix
[...]
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 are no extra columns and that the column names match what was provided as an example. 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:

Increase the memory in the Docker Desktop settings (more help in this post). We recommend to set the memory above 22GB.
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.

To do this, place the patient’s FreeSurfer folder into the meld_data folder in the output/fs_outputs folder. You will need to ensure that the freesurfer subject’s folder name matchs the subject ID used in the input data.

For example, if you have a patient ‘sub-002` and you already have FreeSurfer output folder for that patient, you can rename the folder by the subject id and place it as follow:

output
└── fs_outputs
    └── sub-0002

Typical outputs folder from the recon-all command would look like this:

sub-0002
    ├── label
    ├── mri
    ├── scripts
    ├── stats
    ├── surf
    ├── tmp
    ├── touch
    ├── trash

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 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.