May 26, 2018
Version 2
MELD Protocol 4 - Lesion Masking V.2
- 1Cognitive Neuroscience and Neuropsychiatry, UCL;
- 2Brain Mapping Unit, Department of Psychiatry, University of Cambridge;
- 3Florey Institute of Neuroscience and Mental Health, Melbourne Brain Centre
Protocol Citation: Sophie Adler, Kirstie Whitaker, Mira Semmelroch, Konrad Wagstyl 2018. MELD Protocol 4 - Lesion Masking. protocols.io https://dx.doi.org/10.17504/protocols.io.n9udh6w
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: April 05, 2018
Last Modified: July 17, 2018
Protocol Integer ID: 11284
Abstract
The MELD Project is an international collaboration aiming to create open-access, robust and generalisable tools for FCD detection. To this end, we will train a neural network classifier on MRI features from FCD patients from multiple centres worldwide.
Protocol 4 provides instructions on how to create lesion masks in FreeSurfer using tkmedit.
Safety warnings
PLEASE DO NOT SHARE ANY IDENTIFIABLE DATA
Data sharing only occurs at the level of anonymised demographics information and anonymised data matrices. These are in a template space that cannot be traced back to an individual.
Before start
Lesion masks should ideally be created for all patients included in the MELD Project.
If the patient has a radiological diagnosis of FCD, the lesion mask should be done using the 3D T1 scan and 3D FLAIR (where available). If 3D FLAIR is not available, 2D FLAIR may be of help in defining the lesion. You may need assistance from a neuroradiologist at your centre for the subtle lesions.
If the patient is MRI-negative but with histological confirmation, the post-operative scan and other corroborative evidence such as EEG, PET, sEEG etc. can be used to help define where the lesion was on the preoperative scan in order to create the lesion mask.
If it is NOT possible to create a lesion mask. Please still include this patient in the study. In the csv file named MELD_[site code]_participants.csv , in the lesion mask column mark as 0.
Radiological features of FCD:
- Abnormal cortical thickness
- Blurring of the grey-white matter boundary
- Increased signal intensity of FLAIR / T2 (transmantle sign in FCD IIB)
- Abnormal folding pattern
- Hemispheric asymmetry
The Steps detail how to create a lesion mask in FreeSurfer using the viewer tkmedit , how to move the lesion mask to the FreeSurfer surfaces and save as a .mgh surface file.
If your centre has an established method to create the lesion masks or have already created lesion masks, you do not need to redo them or change your method. The lesion masks will need to be registered to the FreeSurfer surfaces. Please see Supplementary Steps for how to register .nii lesion masks to FreeSurfer surfaces.
If you have any questions or run into problems, please feel free to contact the MELD project: (meld.study@gmail.com).
Installing anaconda and environment
Installing anaconda and environment
https://conda.io/docs/user-guide/install/macos.html
To install anaconda for a mac:
1) download the 'anaconda python 2.7' version installer from here:
https://www.anaconda.com/download/ (make sure it's the mac version being downloaded)
2) Double click the .pkg file to install
3) follow the prompts on the installer screen.
To install anaconda on a linux:
1) Download the 'anaconda python 2.7' version installer from here:
https://www.anaconda.com/download/ (make sure it's the linux version being downloaded)
2) In your terminal window, run:
bash Anaconda-latest-Linux-x86_64.sh
3) follow the prompts on the installer screen
To create the anaconda environment, with all of the necessary python packages,
run the following:
cd <path>/meld/scripts
conda env create -f meld_env.yaml
Finally add the scripts directory to your PYTHONPATH by running the following
open ~/.bashrc
This will open your bash profile
add the following line
export PYTHONPATH='${PYTHONPATH}:<path>/meld/scripts'
Remember to replace <path> with the correct path according to your file system.
Creating Lesion Masks
Creating Lesion Masks
This protocol details how to create your lesion masks using tkmedit.
If you already have lesion masks (saved as .nii files) or would prefer to use a different software to create .nii lesion masks - skip to Step 14 (Supplementary Steps). Step 14 onwards details how to register your .nii lesion masks to your freesurfer surfaces.
If you have not already created lesion masks, the following steps explain how to create them using tkmedit.
Open brainmask (and 3D FLAIR) in viewer
Open brainmask (and 3D FLAIR) in viewer
Remember to read the Guidelines before starting this protocol!
Ensure that the FreeSurfer has been pointed to a directory of subjects to work on and go to that directory:
| setenv SUBJECTS_DIR <path>/meld/output cd <path>/meld/output |
brainmask.mgz = this is the 3D T1 volume with the skull stripped
FLAIR.mgz = 3D FLAIR volume coregistered to the T1
The FLAIR is loaded as the auxiliary volume
| tkmedit MELD_[site code]_[scanner code]_[patient/control]_[number] brainmask.mgz –aux FLAIR.mgz -surfs |
If no FLAIR available:
e.g. tkmedit MELD_H1_15T_FCD_0001 brainmask.mgz –surfs
If FLAIR available:
e.g. tkmedit MELD_H1_15T_FCD_0001 brainmask.mgz –aux FLAIR.mgz –surfs
About tkmedit
About tkmedit
The pial (red line), and white (yellow line) surfaces are shown. You can toggle between the brainmask.mgz (loaded as the 'main' volume) and the FLAIR.mgz (loaded as the 'auxiliary' or 2nd volume) with buttons
and
. As you switch between these two buttons, notice that at the top of the display window, the asterisks (**) surround the name of the volume you are currently looking at.
- Keyboard Shortcut: Alt-c will allow you to quickly switch back and forth between the two volumes instead of clicking between these buttons.
If you hover your mouse over a button in the Tkmedit Tools window, a pop-up will tell you what it does and its keyboard shortcut.
When the Navigation button
is chosen, you can drag the brain around in the display window. Notice how you are not able to move around the cursor (the little red cross-hair).
- To change the location of the cursor, choose any button to the right of the Navigation button and then left-click in the display window. Notice the cursor move to wherever you click. When you zoom, it will zoom into the location of the cursor. When you change brain orientation (to axial or sagittal), you will be viewing the slice where the cursor was located in that plane.
To change which brain slice you are viewing, you can use the + or - buttons next to where it says 'Slice'.
- Keyboard Shortcut: Use the Up or Down arrows on your keyboard to change slices faster (this will only work when the Display window is selected and not on the Tools window).
To switch between coronal, sagittal & horizontal views use these buttons:
Adjust the brightness and contrast so you can see the shift in intensity between gray and white. You can do this by going to View > Configure > Brightness/Contrast in the Tkmedit Tools window and then moving the sliders to adjust the levels.
Find the lesion
Find the lesion
With the brightness and contrast correctly adjusted, scroll through brain slices and different views and visually identify the lesion.
You may need to consult a neuroradiologist to help correctly identify the FCD.
As you scroll through the slices checking the surfaces, keep in mind that you are looking at a 2-dimensional rendering of a 3-dimensional image - be sure to look at more than just one view (i.e., sagittal, coronal and horizontal). To check your surfaces, toggle them off and on with
for the pial surface and
for the white surface.
Mask the lesion
Mask the lesion
You will need a mouse with 3 buttons e.g.
Use the “Select voxels tool”
Go to Tools > Configure brush info in the tkmedit tools window. Here you can change the radius of your brush (increase to select more voxels – e.g. in a large lesion). Ensure you are editing the “Main volume”. The 3D tool can be used to select voxels over multiple slices. Be cautious not to overestimate your lesions – it is better to be conservative.
Use the scroll / middle click button to select voxels in the lesion. They should appear pink when selected.
To deselect/ delete voxels from the mask use the right click button.
Remember to always select the voxels that intersect the white surface – this is required for labels to be registered to the surfaces.
Ensure you check your lesion label in all 3 views (coronal, sagittal and horizontal).
If you mistakenly select / delete voxels in the brainmask or FLAIR volume, remember to NOT save the main volume or auxiliary volume. These changes will therefore not be saved and if you close and reopen the volumetric files, they will be restored.
Ensure you check your lesion label in all 3 views (coronal, sagittal and horizontal).
Save your lesion mask by selecting File > Label > Save label as
Ensure that the path is correct e.g. <path>/meld/output/MELD_[site code]_[scanner code]_[patient/control]_[number]/label/
Save file as ?h.lesion.label
Example of lesion mask:
Move lesion label to FreeSurfer surfaces
Move lesion label to FreeSurfer surfaces
The script label2surf.sh will register the ?h.lesion.label to the cortical surface. It will smooth any small inconsistencies in the label to create one continuous lesion label and save it as a .mgh file called <lh/rh>.lesion_linked.mgh
Change directory into the scripts directory and activate the anaconda environment.
| cd <path>/meld/scripts source activate meld_env |
run the label2surf.sh script.
| bash label2surf.sh <path>/meld List_subjects.txt |
Check lesion label on surface
Check lesion label on surface
You will need to individually check that each lesion label is correct. To do this, in one terminal window load the mri scans:
| setenv SUBJECTS_DIR <path>/meld/output cd <path>/meld/output tkmedit MELD_[site code]_[scanner code]_[patient/control]_[number] T1.mgz –aux FLAIR.mgz -surfs |
In another terminal window load the cortical surface and lesion label:
| setenv SUBJECTS_DIR <path>/meld/output cd <path>/meld/output tksurfer MELD_[site code]_[scanner code]_[patient/control]_[number] ?h inflated –overlay MELD_[site code]_[scanner code]_[patient/control]_[number]/surf/?h.lesion.mgh –fminmax 0 1 |
Check lesion label:
You can click on a point on the lesion label on the inflated surface and then click
Then on the MRI scans click
and this will take you to the corresponding place on the MRI scan.
Once a participants lesion label has been checked, and it is correct, open the csv file called MELD_site code_participants.csv and fill in the Lesion Mask column.
Code as 1 if lesion mask is done.
Code as 0 if not able to be done.
Code as 666 if this is a control participant.
SUPPLEMENTARY STEPS: register .nii lesion masks to FreeSurfer surfaces
SUPPLEMENTARY STEPS: register .nii lesion masks to FreeSurfer surfaces
To register .nii lesion masks created in MRIcron (or other software) to the freesurfer surfaces use the script:
nii_lesion_mask_to_fs.sh
You will need to open the script: nano nii_lesion_mask_to_fs.sh
Change the name of the lesion mask (?h.lesion.nii) to the name of your lesion masks in .nii format. Ensure that the path to your lesion masks is correct. The script currently assumes that the ?h.lesion.nii mask is in the subjects folder e.g. <path>/meld/output/MELD_H1_15T_FCD_0001
Remember to save any changes you make.
Create List_nii.txt that contains a list of the subject IDs of the participants with .nii lesion masks.
e.g.
MELD_H1_15T_FCD_0001
MELD_H1_15T_FCD_0002
MELD_H1_15T_FCD_0003
| nano <path>/meld/output/List_nii.txt |
Save List_nii.txt
Please note: the script will only work with more than 1 participant in List_nii.txt
Make sure you have activated your meld Anaconda environment
| source activate meld_env |
Run the script:
| bash <path>/meld/scripts/nii_lesion_mask_to_fs.sh <path>/meld List_nii.txt |
Then do steps 8-11 (check lesion label on surface) to check the lesion label is correctly registered to the FreeSurfer surfaces.