MELD classifier

Neural network lesion classifier for the MELD project.

The manuscript describing the classifier can be found here https://academic.oup.com/brain/advance-article/doi/10.1093/brain/awac224/6659752

Code Authors : Hannah Spitzer, Mathilde Ripart, Sophie Adler, Konrad Wagstyl

This package comes with a pretrained model that can be used to predict new subjects. It also contains code for training neural network lesion classifiers on new data.

Disclaimer

The MELD surface-based FCD detection algorithm is intended for research purposes only and has not been reviewed or approved by the Medicines and Healthcare products Regulatory Agency (MHRA), European Medicine Agency (EMA) or by any other agency. Any clinical application of the software is at the sole risk of the party engaged in such application. There is no warranty of any kind that the software will produce useful results in any way. Use of the software is at the recipient's own risk.

Installation

Note: The current installation of the MELD classifier is not working on MAC M1 and MAC M2 OS because of incompatibilities with tensorflow and these OS systems.

Prerequisites

For preprocessing, MELD classifier requires Freesurfer. It is trained on data from versions 6 & v5.3, but compatible with Freesurfer version up to V7.2. Please follow instructions on Freesurfer to install FreeSurfer.
New update ! MELD pipeline is now also working with FastSurfer (quicker version of Freesurfer). If you wish to use FastSurfer instead please follow instructions for the native install of Fastsurfer. Note that Fastsurfer requires to install Freesurfer V7.2 to works
WARNING: MELD pipeline has not been adapted for Freesurfer V7.3 and above. Please install Freesurfer V7.2 instead.

You will need to ensure that Freesurfer is activated in your terminal (you should have some printed FREESURFER paths when opening the terminal). Otherwise you will need to manually activate Freesurfer on each new terminal by running :

export FREESURFER_HOME=<freesurfer_installation_directory>/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

with <freesurfer_installation_directory> being the path to where your Freesurfer has been installed.

Conda installation

We use anaconda to manage the environment and dependencies. Please follow instructions on anaconda to install Anaconda.

Install MELD classifier and python dependencies:

# checkout and install the github repo 
git clone https://github.com/MELDProject/meld_classifier.git 

# enter the meld_classifier directory
cd meld_classifier
# create the meld classifier environment with all the dependencies 
# ! Note : If you have a new MAC1 OS system, you will need to install the special environments for new MAC1 users in the second command below.
conda env create -f environment.yml    # For Linux and old MAC os users
conda env create -f environment_MAC1.yml  # For new MAC1 users 
# activate the environment
conda activate meld_classifier
# install meld_classifier with pip (with `-e`, the development mode, to allow changes in the code to be immediately visible in the installation)
pip install -e .

Set up paths and download model

Before being able to use the classifier on your data, some paths need to be set up and the pretrained model needs to be downloaded. For this, run:

python scripts/prepare_classifier.py

This script will ask you for the location of your MELD data folder and download the pretrained model and test data to a folder inside your MELD data folder. Please provide the path to where you would like to store MRI data to run the classifier on.

Note: You can also skip the downloading of the test data. For this, append the option --skip-download-data to the python call.

FAQs

Please see our FAQ for common installation problems.

Verify installation

We provide a test script to allow you to verify that you have installed all packages, set up paths correctly, and downloaded all data. This script will run the pipeline to predict the lesion classifier on a new patient. It takes approximately 15minutes to run.

Note: Do not forget to activate Fressurfer as describe above before to run the test.

cd <path_to_meld_classifier>
conda activate meld_classifier
pytest

Note: If you run into errors at this stage and need help, you can re-run the command below to save the terminal outputs in a txt file, and send it to us. We can then work with you to solve any problems.

pytest -s | tee pytest_errors.log

You will find this pytest_errors.log file in <path_to_meld_classifier>.

Usage

With this package, you can use the provided classifier to predict subjects from existing and new sites. For new site, you will need to harmonise your data first. In addition, you can train your own classifier model. For more details, check out the guides linked below:

• Predict new subjects (existing site)
• Harmonise your data (new site)
• Train and evaluate models

Contribute

If you'd like to contribute to this code base, have a look at our contribution guide

Manuscript

Please check out our manuscript to learn more.

An overview of the notebooks that we used to create the figures can be found here.

A guide to using the MELD surface-based FCD detection algorithm on a new patient is found here.

Acknowledgments

We would like to thank the MELD consortium for providing the data to train this classifier and their expertise to build this pipeline.
We would like to thank Lennart Walger and Andrew Chen, for their help testing and improving the MELD pipeline to v1.1.0