Generation of Lesion Probability Map(s) Pipeline
------------------------------------------------
*Authors: Charley Gros, Sara Dupont & Dominique Eden*
**Purpose:** To generate a weighted voxel-based probability map of lesion masks in the PAM50 template space, using MRI data across a range of subjects, contrasts and modalities. This pipeline has been used for the study from Eden et al. "*Spatial Distribution of Multiple Sclerosis lesions in the Cervical Cord*" ISMRM 2018 (under review).
**To launch and run scripts**, please do the following:
1. Download, move and unzip: `code.zip` & `example_data.zip` to a *CHOSEN_DIRECTORY*
2. Open terminal and change directory to *CHOSEN_DIRECTORY/code*
cd CHOSEN_DIRECTORY/code
3. Modify `config_file.py` and `data_info.csv`
- Fill out fields in `config_file.py` manually (For more information, see section *CONFIG_FILE.PY*)
- Fill out columns in `data_info.csv` manually (For more information, see section *DATA_INFO.CSV*)
4. Ensure correct folder organisation, naming and existance of data (For more information, see section *FOLDER ORGANISATION AND DATA*)
5. Return to terminal
- Source SCT environment
source sct_launcher
- STEP 0: Launch `sct0_LPM_checkData.py`
python sct0_LPM_checkData.py
*Please check `sct0_results.csv` to ensure that all subjects have been included.*
- STEP 1: Launch `sct1_LPM_register2template.py`
python sct1_LPM_register2template.py
*Please check registration of all subjects prior to running next step.*
- STEP 2: Launch `sct2_LPM_warp_mask2template.py`
python sct2_LPM_warp_mask2template.py
- STEP 3: Launch `sct3_LPM_map_lesions.py`
python sct3_LPM_map_lesions.py
#### --------- CONFIG_FILE.PY ---------
The configuration file sets pipeline parameters. Please find below a description of each parameter you will need to specify:
- `["center_dct"]`: A dictionary to categorise data. The dictionary has the following format:
`{"center_key": {"orientation_key": ["list of: contrasts"]}}`
The center_key indicates center name(s), orientation_key indicates the reference orientation of the image, i.e. ax or sag, and the [list of: contrasts] values indicate the list of contrasts to include in the mapping.
For example:
`{"center1": {"ax": ["t2s", "t2"],
"sag": []}}`
This would indicate that for `center1`, high resolution images in the axial `ax` plane for contrasts `t2s` and `t2` and no high resolution images in the sagittal `sag` plane, will be included.
N.b.: The distinction and use of term `ax` and `sag` (images) are used in the registration process, where registration parameters differ between the two.
N.b.: Both orientations are not required. If both orientations are listed however, note that the pipeline will automatically perform a weighted-merge of lesions from both images.
- `["path_data"]`: The absolute path to root folder containing data, where data is organised as described in section *FOLDER ORGANISATION AND DATA*
- `["csv_data”]`: The absolute path to `data_info.csv` with information for all subjects, as described in section *DATA_INFO.CSV*
- `["LPM_subgroups"]`: A list of categories to create LPMs for categorical subgroups. By default, a map across all subjects will be computed. For generation of additional maps per categorical subgroup (i.e. Phenotype RR), the categories here should correspond with columns entries in `data_info.csv`.
For example: By indicating `“Phenotype”`, the pipeline will generate one map per subgroup as indicated in `data_info.csv` column `“Phenotype”`.
- `["ofolder_LPM"]`: Absolute path to the chosen name of folder where LPMs will be saved.
#### --------- DATA_INFO.CSV ---------
This is a spreadsheet to list center and subject_folder information, and categorical information to generate additional maps. An example is provided in `example_data.zip`. The required columns in the csv file are:
- `Center`: the center name to group subjects by center. - `Subject_Folder`: the subject folder names to be included in mapping.
N.b. The csv file does not need to be named as `data_info.csv`, however the absolute path to the csv file must be entered in `config_file[“csv_data”]`.
#### --------- FOLDER ORGANISATION AND DATA ---------
Please ensure that all subjects folder names are listed in column `Subject_Folder` of `data_info.csv`, and that folders and data is organised into the structure:
Subject_Folder/
contrast_ax/
contrast_ax.nii.gz # MRI image
contrast_ax_seg_manual.nii.gz # spinal cord mask (binary)
contrast_ax_lesion_manual.nii.gz # lesion mask (binary)
labels.nii.gz # disc label (Please see below for instructions.)
contrast_sag/
contrast_sag.nii.gz # MRI image
contrast_sag_seg_manual.nii.gz # spinal cord mask (binary)
contrast_sag_lesion_manual.nii.gz # lesion mask (binary)
labels.nii.gz # disc label (Please see below for instructions.)
For spinal cord mask generation, `sct_propseg` may be used.
For label generation, please use SCT function `sct_label_utils`, i.e.,
sct_label_utils -create-viewer <list of: int> -i <file>
Example,
sct_label_utils -create-viewer 3,6 -i CHOSEN_DIRECTORY/example_data/cent1_subj1/t2/t2.nii.gz
(Please ensure the latest version of Spinal Cord Toolbox has been installed. For instructions on use and where to place labels, please see to: XXX)
N.b.: All files must be in NIFTI format.
WARNING: If a file is missing, the subject will be excluded for the remainder of the pipeline.
#### ========== CONTACT ==========
For any question, please contact Julien Cohen-Adad:
`jcohen@polymtl.ca`
#### ========== TERMS ============
**License**
The MIT License (MIT)
Copyright (c) 2017 École Polytechnique, Université de Montréal
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
