Skip to content

FAQs.md

Latest commit

 

History

History
322 lines (242 loc) · 15.1 KB

FAQs.md

File metadata and controls

322 lines (242 loc) · 15.1 KB

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:

  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 with conda env create -f environment.yml
  3. 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:

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

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.

Updating MELD Graph version

The instructions below are for users that already have used a version of MELD Graph (e.g. v2.2.1) on patients and would like to update to the latest version of MELD Graph (e.g. v2.2.4) while keeping the same meld_data folder.

📥 Get the updated code

Please follow the Download method below to get the new code

::::{tab-set}

:::{tab-item} Download

  1. Go to the github releases page and download the latest version V2.2.X (e.g. V2.2.4), by clicking on Source code (zip) or Source code (tar.gz).
  2. Extract the folder meld_graph-2.2.X
  3. Copy the files below from your old meld_graph-2.2.X directory to your new meld_graph-2.2.X directory:
    • the freesurfer license.txt
    • the compose.yml
    • the meld_config.ini :::

:::{tab-item} Git

  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)
git stash
git pull 
git stash pop

::: :::: 4. If not already done, register to MELD Graph to get your MELD License by filling the form.

Then depending on if you have a Native, Docker or Singularity installation of the previous MELD Graph version you will need to follow the same type of installation to update to the latest version:

::::{tab-set}

:::{tab-item} Native :sync: Native 💻 Native Installation Users: Your will need to update your environment with the new code.

  1. Activate your conda environment
conda activate meld_graph
  1. Update the code package in the environment. Make sure you are in the new meld_graph-2.2.X directory and run:
pip install -e .

:::

:::{tab-item} Docker :sync: Docker

🐳 Docker Users: You will need to pull the latest docker image

docker pull meldproject/meld_graph:latest

:::

:::{tab-item} Singularity :sync: Singularity

🚀 Singularity Users: You will need to pull the latest image

singularity pull docker://meldproject/meld_graph:latest

::: ::::

🗂️ For v2.2.1 users: Update your meld_data_folder with the new test data

If you are working with v2.2.1 and want to update to a version above, you will need to download the test data again. If you have a version v2.2.2 or above, you can skip this step.

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.

::::{tab-set}

:::{tab-item} Native :sync: Native

💻 Native Installation Users:

./meldgraph.sh prepare_classifier.py --update_test

:::

:::{tab-item} Docker :sync: Docker

🐳 Docker Users:

DOCKER_USER="$(id -u):$(id -g)" docker compose run meld_graph python scripts/new_patient_pipeline/prepare_classifier.py --update_test

:::

:::{tab-item} Singularity :sync: Singularity

🚀 Singularity Users:

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.

🧠 For v2.2.1 only: Update your predictions with the registration fix

If you are working with v2.2.1 and want to update to a version above, you will need to download the test data again. If you have a version v2.2.2 or above, you can skip this step.

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

::::{tab-set}

:::{tab-item} Native :sync: Native

💻 Native Installation Users:

./meldgraph.sh run_script_prediction.py -ids list_subjects_rerun_v2.2.X.txt --skip_prediction

:::

:::{tab-item} Docker :sync: Docker

🐳 Docker Users:

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.X.txt --skip_prediction

:::

:::{tab-item} Singularity :sync: Singularity

🚀 Singularity Users:

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.X.txt --skip_prediction"

::: ::::