/lesion-mapping

Set of tools for mapping lesions in the brain and/or spinal cord

Primary LanguagePython

Multiple Sclerosis lesion quantification

Dependencies

Spinal Cord data processing

SCT is used for all preprocessing steps of the spinal cord data, including cord segmentation, registration into the template space, and lesion load quantification.

Version v.3.2.4 and above.

Brain data processing

Anima-Public is used for registrating brain data to the MNI space.

Version v.3.1 and above.

Anima-Scripts-Public is used for extracting the brain.

Version v.1.0 and above.

Download data

Dataset structure

The dataset should be arranged in a structured fashion, as the following:

- subject_name/
	- brain/
		- anat/
			- anat.nii.gz # e.g. FLAIR
			- anat_lesion_manual.nii.gz # lesion mask (binary)
		- struct/ # e.g. isotropic T1-w
			- struct.nii.gz
	- spinalcord/
	    - image_ax/
			- image_ax.nii.gz # e.g. axial T2*-w
			- image_ax_seg_manual.nii.gz # spinal cord mask (binary)
			- image_ax_lesion_manual.nii.gz # lesion mask (binary)
			- labels_disc.nii.gz # disc label (2 labels, i.e. 2 voxels)
			- labels_vert.nii.gz # vertebral label (2 labels, i.e. voxels, mid body), non-compulsory

Preprocessing for longitudinal data

Scripts are available under brain/preprocessing and spinalcord/preprocessing to register follow-up data on T0 data.

How to run

  • Download (or git clone) this repository:
git clone https://github.com/neuropoly/ms_brain_spine
  • Use SCT python
source sct_launcher

Clinical and demographic information

Please save the clinical and demographic information of the dataset into a csv file, with the following columns for each subject:

  • center: center of acquisition
  • subject: subject folder name
  • age: age of the subject (year)
  • gender: gender of the subject: either F for female or M for male
  • disease_dur: disease duration of the subject (year)
  • edss: EDSS score of the subject (float between 0 and 10)
  • phenotype: phenotype of the subject: CIS, RR, SP or PP
  • ...

Brain processing

  • Go into brain scripts folder
cd brain

Set parameters

Edit config_file.py according to your needs, then save the file.

  • dct_center: indicate for each center, the folder names of your structural image (see struct in the Dataset structure section, e.g. anat.nii.gz) and your anatomical image (anat, e.g. flair.nii.gz)
  • path_data: folder path where your data is stored (see also Dataset structure section)
  • csv_clinicalInfo: path towards the csv containing the clinical information of the dataset
  • path_results: folder path where to save the results
  • path_anima_brain_extraction: folder path to the Anima script for brain extraction
  • path_smatt_folder: folder path to the downloaded SMATT atlas
  • path_brainstem_folder: folder path to the downloaded brainstem atlas
  • path_atlases: folder path where to save the customed atlases

Check data

Check data availability and integrity:

python 0_check_data.py

This script will loop across the subjects listed in the csv file csv_clinicalInfo and check the availaibility and integrity of the files used for the processing. If some files are missing or incorrect, one or more of the following files will be output in the current directory (where datetime indicates the date and time of the end of the running of 0_check_data):

  • datetime_missing_subject.pkl: if the folder of a subject listed in the csv file is not present in the dataset.
  • datetime_missing_contrast.pkl: if the image folder of a subject listed in the dct_center dictionary is not present in the dataset.
  • datetime_missing_img.pkl: if a raw image is missing in the dataset.
  • datetime_missing_lesion.pkl: if a lesion segmentation is missing in the dataset for a anat image.
  • datetime_incorrect_lesion.pkl: if a lesion segmentation is incorrect in the dataset (i.e. not binary) for a anat image. To display the missing files or to correct / generate the missing or incorrect label files, please run:
python missing_incorrect_files.py datetime_*.pkl

for instance:

python missing_incorrect_files.py 201809201152_incorrect_lesion.pkl

Register data to the MNI152_T1_1mm space

Register data by running:

python 1_register_data.py

This script performs a muti-step registration to register the anat image to the MNI152_T1_1mm space:

  1. Brain extraction
  2. Linear registration of anat image to struct image
  3. Registration of the struct image to the MNI152_T1_1mm space
    • Rigid
    • Affine
    • Non-linear

Then, it warps the atlases into the anat space.

Quantify lesion characteristics

Quantify lesion characteristics in the brain as well as in the motor and corticospinal tracts:

python 2_quantify.py

It creates a csv and a pickle file (brain_brainstem_results.*) in the path_results folder.

Measures:

  • tbv [mm3]: total brain volume (computed on the struct image)
  • tlv [mm3]: total lesion volume in the brain
  • count_*: number of lesions in the brain or in one of the region of interest listed below (e.g. count_M1_R)
  • nlv_*: TLV divided by a volume of interest
  • alv_* [mm3]: absolute lesion volume in one of the region of interest listed below
  • extension_motor (%): volume of lesion in the corticospinal and tracts divided by the total volume of lesion in the cord

Regions of interest:

  • brain_motor, brainstem_CST: brain motor tracts, brainstem corticospinal tracts
  • brainstem_CST_R, brainstem_CST_L: corticospinal right and left tracts in the brainstem
  • brain_M1_R, brain_M1_L:
  • brain_PMd_R, brain_PMd_L:
  • brain_PMv_R, brain_PMv_L:
  • brain_preSMA_R, brain_preSMA_L:
  • brain_S1_R, brain_S1_L:
  • brain_SMA_R, brain_SMA_L:

Spinal cord processing

  • Go into spinal cord scripts folder
cd spinalcord

Set parameters

Edit config_file.py according to your needs, then save the file.

  • dct_center: indicate for each center, the folder names of your axial image(s) (see image_ax in the Dataset structure section)
  • path_data: folder path where your data is stored (see also Dataset structure section)
  • csv_clinicalInfo: path towards the csv containing the clinical information of the dataset
  • path_results: folder path where to save the results

Check data

Check data availability and integrity:

python 0_check_data.py

This script will loop across the subjects listed in the csv file csv_clinicalInfo and check the availaibility and integrity of the files used for the processing. If some files are missing or incorrect, one or more of the following files will be output in the current directory (where datetime indicates the date and time of the end of the running of 0_check_data):

  • datetime_missing_subject.pkl: if the folder of a subject listed in the csv file is not present in the dataset.
  • datetime_missing_contrast.pkl: if the image folder of a subject listed in the dct_center dictionary is not present in the dataset.
  • datetime_missing_img.pkl: if a raw image is missing in the dataset.
  • datetime_missing_sc.pkl: if a spinal cord segmentation is missing in the dataset.
  • datetime_missing_lesion.pkl: if a lesion segmentation is missing in the dataset.
  • datetime_missing_incorrect_labels.pkl: if a label file of the discs is missing or incorrect (i.e. more than two voxels labeled in the mask) in the dataset.
  • datetime_incorrect_sc.pkl: if a spinal cord segmentation is incorrect in the dataset (i.e. not binary and/or several connected objects).
  • datetime_incorrect_lesion.pkl: if a lesion segmentation is incorrect in the dataset (i.e. not binary). To display the missing files or to correct / generate the missing or incorrect label files, please run:
python correct_generate_labelling.py datetime_*.pkl

for instance:

python correct_generate_labelling.py 201809201152_incorrect_sc.pkl

Register data to the PAM50 template

Register data to the PAM50 template [REF] then warp the template and the white matter atlas [REF] back to the subject space:

python 1_register_data.py

Please check the QC of the registration provided in the path_results/qc folder by opening index.html file.

Quantify lesion characteristics

Quantify lesion characteristics in the entire cord as well as in the corticospinal tracts:

python 2_quantify.py

It creates a csv and a pickle file (spinalcord_results.*) in the path_results folder.

Measures:

  • csa [mm2]: mean cross-sectional area of the cord
  • tlv [mm3]: total lesion volume in the entire cord
  • count_*: number of lesions in the entire cord or in one of the region of interest listed below (e.g. count_VCST_R)
  • nlv_*: TLV divided by a volume of interest (e.g. entire cord or one of the region of interest listed below)
  • alv_* [mm3]: absolute lesion volume in one of the region of interest listed below (e.g. alv_VCST_R)
  • extension_CST (%): volume of lesion in the corticospinal tracts divided by the total volume of lesion in the cord

Regions of interest:

  • VCST_R, VCST_L: ventral corticospinal right and left tracts
  • LCST_R, LCST_L : lateral corticospinal right and left tracts
  • CST: corticospinal tracts

Generate Lesion Frequency Maps.

Generate Lesion Frequency Maps (LFM) in the entire cord as well as in the corticospinal tracts:

python 3_generate_LFM.py

It generating the LFM in the entire cord as well as in the corticospinal tracts, for each of the patients subgroup (spinalcord_LFM_<subgroup>.nii.gz and spinalcord_LFM_CST_<subgroup>.nii.gz) in the path_results/LFM folder.

Note that in its current version, the function is suboptimal, and has been recently replaced by this function:

Notable differences with the more recent version:

  1. It doesn't include the registration to the template, just assuming the warping fields already exist (because it needs a QC).
  2. it's not relying on the old version of SCT (as for my understanding this was the reason I couldn't run the script), but on bash script.
  3. It's doing nn interpolation for applying the transformation to SC segmentation (as in sct_warp_template).
  4. It has the options to set the data directories, structure and the file names (or some regex pattern) as parameters.
  5. It has the option to cut the results to the spinal cord area that covers all subjects SC segmentation.

References

  • Commowick O, Wiest-Daessle N, Prima S. Block-matching strategies for rigid registration of multimodal medical images. In: 2012 9th IEEE International Symposium on Biomedical Imaging (ISBI). 2012 Available from: http://dx.doi.org/10.1109/isbi.2012.6235644
  • De Leener B, Lévy S, Dupont SM, Fonov VS, Stikov N, Louis Collins D, et al. SCT: Spinal Cord Toolbox, an open-source software for processing spinal cord MRI data. Neuroimage 2017; 145: 24–43.
  • Gros, Charley, et al. "Automatic segmentation of the spinal cord and intramedullary multiple sclerosis lesions with convolutional neural networks." Neuroimage 184 (2019): 901-915.

Studies using this pipeline

  • Kerbrat, Anne, et al. "Multiple sclerosis lesions in motor tracts from brain to cervical cord: spatial distribution and correlation with disability." Brain 143.7 (2020): 2089-2105.

Licence

The MIT License (MIT) Copyright (c) 2018 École Polytechnique, Université de Montréal