CHeBA Neuroimaging Software!¶
UBO Detector¶
UBO Detector is a cluster-based white matter hyperintensity (WMH) extraction pipeline based on k-nearest neighbors (k-NN) algorithm, using T1-weighted and Fluid Attenuation Inversion Recovery (FLAIR) MRI sequences.
System Requirements¶
UBO Detector has been tested on both CentOS release 6.8 and macOS Sierra with the following software/toolboxes installed:
SPM12
FSL v5.0
MATLAB R2016a or above with the following toolboxes installed:
- Image Processing Toolbox (ver 9.5 tested)
- Statistics and Machine Learning Toolbox (ver 11.0 tested)
- Parallel Computing Toolbox (ver 6.9 tested)
Citation¶
If you use UBO Detector, please cite:
Jiang, J., Liu, T., Zhu, W., Koncz, R., Liu, H., Lee, T., Sachdev, P.S., Wen, W. UBO Detector – A cluster-based, fully automated pipeline for extracting white matter hyperintensities. NeuroImage, doi.org/10.1016/j.neuroimage.2018.03.050 (2018).
If you use TOPMAL, please cite:
Jiang, J., Paradise, M., Liu, T., Armstrong, N. J., Zhu, W., Kochan, N. A., Brodaty, H., Sachdev, P. S., Wen, W. The association of regional white matter lesions with cognition in a community-based cohort of older individuals, NeuroImage: Clinical 19:14-21, doi.org/10.1016/j.nicl.2018.03.035 (2018).
Quick Start Guide¶
Data Preparation¶
Data Preparation
In order to fit in UBO Detector, both T1 and FLAIR sequences are required (*.nii or *.nii.gz). The data should be named with a unique ID which can be numeric numbers or letters or combination of the two, followed by an underscore (e.g. 1111_ABCstudy_T1.nii, 1111_flairABC.nii.gz), and stored in two folders (T1 and FLAIR (all upper case)) under the study folder. For example:
WMH Extraction¶
This section describes how to extract WMH with UBO Detector graphic user interface (GUI).
Step 1: In MATLAB, addpath(‘/path/to/CNS’) and run CNS
Step 2: Open the UBO Detector through WMH -> Extract WMH.
Step 3: Find the Study Directory by clicking Find.
Step 4: Find spm12 folder.
Step 5: Specify how you would like to view the coregistration, segmentation, and final results for quality control (QC).
Display on screen - Results will be displayed in MATLAB web browser by calling the web function in MATLAB. Download to check locally - Results will be exported into a HTML webpage, and compressed for download Both - both Display on screen and Download
Step 6: “Extract with QC stops” if you want to exclude scans failed coregistration or segmentation QC, or Extract without QC stops if you want to complete the extraction without stops. “Extract without QC stops” will not allow you to exclude any subjects from the process, but will generate the same QC figures as “Extract with QC stops” (i.e. coregistration, segmentation, final QC), which is stored in the <studyFolder>/subjects/QC folder.
Step 7: If selected “Extract with QC stops” in Step 6. The pipeline will generate QC webpage after coregistration. Depending on the means of viewing the results specified in Step 5, the coregistration results will be either displayed as a webpage on screen, or available for download, or both display and download. Please input the IDs failed coregistration QC (separated by space) in the Quality Control section, and click Finish and continue.
Step 8: If selected “Extract with QC stops” in Step 6. The pipeline will generate QC webpage after segmentation. The segmentation results will be available according to what you specified in Step 5. Input the IDs failed segmentation QC (separated by space) in the Quality Control section, and click Finish and continue.
Step 9: The final results will be available according to Step 5 after finishing all the extraction steps.
Output¶
UBO Detector will provide both image and text file output. WMH volumes are calculated in SPM’s DARTEL space. Therefore, there is no need to adjust for intracranial volume (ICV). By default, any WMHs <12 mm from lateral ventricles are considered as periventricular WMH regions.
Image: An example of extracted WMH. The first row is three slices of FLAIR on each plane, and the second row is extracted WMH overlain on FLAIR.
Image Output¶
Image output of whole brain WMH is located at: /<study_folder>/subjects/<subject_ID>/mri/extractedWMH/<ID>_WMH.nii.gz
Image output of regional WMH is at:
Periventricular WMH: /<study_folder>/subjects/<subject_ID>/mri/extractedWMH/<ID>_ PVWMH.nii.gz
Deep WMH: /<study_folder>/subjects/<subject_ID>/mri/extractedWMH/<ID>_DWMH.nii.gz
Lobar WMH: /<study_folder>/subjects/<subject_ID>/mri/extractedWMH/lobarWMH/<ID>_*_WMH.nii.gz
Arterial territories WMH: /<study_folder>/subjects/<subject_ID>/mri/extractedWMH/arterialWMH/<ID>_*_WMH.nii.gz
Abbreviation of arterial territories: A.A.H., anterior artery hemisphere; A.A.C., anterior artery callosal; A.A.M.L., anterior artery medial lenticulostriate; M.A.H., middle artery hemisphere; M.A.L.L., middle artery lateral lenticulostriate; P.A.H., posterior artery hemisphere; P.A.C., posterior artery callosal; P.A.T.M.P., posterior artery thalamic and midbrain perforators.
Text File Output¶
In addition to WMH volumes, UBO Detector also counts total number of WMH incidences (NoI), i.e. number of 26-connection clusters, as well as the number of punctuate (< 10.125 mm3, i.e. 3 voxels on DARTEL space), focal (< 30.375 mm3, i.e. 9 voxels on DARTEL space), medium (< 50.625 mm3, i.e. 15 voxels on DARTEL space), and confluent (> 50.625 mm3) incidences. Both volumes and NoI of the whole brain, as well as periventricular, deep, lobar, and arterial regions, are summarized.
Individual WMH estimation can be found at:
/<study_folder>/subjects/<subject_ID>/stats/<ID>_WMH_vol.txt
/<study_folder>/subjects/<subject_ID>/stats/<ID>_WMH_NoI.txt
WMH summary of the whole study is at: /<study_folder>/subjects/WMH_spreadsheet.txt
For more information, bug reporting and suggestions please contact: cns.cheba@unsw.edu.au
Advanced settings for WMH segmentation¶
DARTEL Template¶
UBO Detector offers three options for DARTEL templates:
- Existing templates for 65 to 75 years old - The templates were generated from Older Australian Twins Study (OATS) with participants aged 65-75 years. The templates have been embedded in the release of UBO Detector.
- Existing templates for 70 to 80 years old - The templates were from Sydney Memory and Ageing Study (Sydney MAS) with older adults aged 70 to 80 years. The templates have been included in the release of UBO Detector.
- Creating templates - This option will generate sample-specific templates. This option will take longer time than the existing templates options.
k for kNN¶
The number of neighbours to search for in the n-dimension space, where n is the number of features. A ‘k=5’ works well from our experiences.
kNN training set¶
UBO Detector includes a built-in training set of manually selected WMH and non-WMH clusters from five Sydney MAS participants. A larger training set will be included in future release of UBO Detector.
Probability threshold¶
The output from the kNN step includes a probability map indicating the ratio of the number of the ‘WMH’ votes in the nearest k neighbours to k, the total number of neighbours involved in the voting. From our experiences, a probability threshold of 0.7 works well with k=5, i.e. in the five nearest neighbours, at least four voting ‘WMH’ indicates that the enquiry cluster is likely to be a WMH region.
Customize the kNN Classifier¶
In order to customize kNN classifier, the data need to go through standard WMH segmentation procedures using UBO Detector.
Step 1: From CNS GUI, select WMH -> Customise kNN classifier
Step 2: Find the study folder by clicking Find Study Dir
Step 3: Specify the number of subjects that will be included in the training set.
Step 4: Specify whether you would like the number of WMH and non-WMH to be equal.
Step 5: Type in the ID for each subject that will be included in the training set.
Step 6: Press Rude Training. From our experiences, after FSL FAST segmentation of FLAIR scans, the majority of WMH clusters are included in seg0. Therefore, by default, we preliminarily label all clusters in seg0 as WMH, and those in seg1 and seg2 as non-WMH.
Step 7: Choose to manually edit based on rude training results (i.e. with all seg0 clusters regarded as WMH), or WMH segmentation results using the built-in training set and classifier.
Step 8: Select one of the IDs from the specified training set, and click Start Visual Adjustment. FSLVIEW will be started and load the WMH map/mask selected from Step 6, which is superimposed onto FLAIR image in DARTEL space. Edit the WMH mask using the editing tools available in FSLVIEW. After finishing editing, save the edited WMH mask, and close FSLVIEW. Please be noted that the left/right orientation may be swapped after each second save in FSLVIEW. Therefore, please try to edit the whole image and save once.
Step 9: Click Auto Modify Textfile.
Step 10: Find manually edited WMH mask
Step 11: Specify the DARTEL template used for WMH segmentation carried out before customizing kNN classifier.
Step 12: Click Modify text for training, and close the autoModTxt dialog after finishing.
Step 13: Repeat Step 8-12 for each of the training IDs.
Step 14: Click All Finished.
Step 15: Click Go to Extract WMH with Customised Classifier. Remember to select “customised” for kNN training set in UBO Detector.
Longitudinal Pipeline¶
Longitudinal version of UBO Detector is only available in commandline at the moment.
Data Preparation¶
The longitudinal pipeline required a slightly different data preparation. Specifically, T1 and FLAIR data need to be renamed as ID_tp1_*.nii.gz, ID_tp2_*.nii.gz, where tp is an abbreviation of time point, tp1 means the first time point, and tp2 is the second time point, etc. These data should be saved in a similar folder structure as that described for cross-sectional UBO Detector processing:
Running Longitudinal Pipeline¶
Step 1: Add path in MATLAB. addpath (‘/path_to_CNS/WMH_extraction/WMHextraction_long’);
Step 2: Run longitudinal pipeline. WMHextraction_long_paired (studyFolder, Ntp, spm12path, dartelTemplate, k, PVWMH_magnitude, coregExcldList, segExcldList, classifier, ageRange, probThr, outputFormat);
where:
- studyFolder is the path to the study folder
- Ntp is the number of time points
- spm12path is the path to SPM12
- dartelTemplate is either ‘existing template’ or ‘creating template’
- k is the k for kNN
- PVWMH_magnitude is the distance (in mm) from lateral ventricles which defines periventricular and deep WMH
- coregExcldList is the list of IDs who failed FLAIR-to-T1 coregistration, and will be excluded in future analyses. Use ‘’ to pass an empty list
- segExcldList is the list of IDs who failed the T1 segmentation step, and will be excluded in future analyses. Use ‘’ to pass an empty list
- classifier is either ‘built-in’ or ‘customised’
- ageRange is either ‘lt55’, ‘65to75’, or ‘70to80’
- probThr is the probability threshold to threshold WMH probability map
- outputFormat is how you want to view the QC results, either ‘web’, ‘arch’, or ‘web&arch’.
Leave-one-out Cross Validation¶
Other functions after WMH segmentation¶
Manual Editing¶
After the final QC, you can select the subjects for manual editing, and re-calculate the volumes of global and regional WMH.
- /path/to/CNSP/WMH_extraction/cmd/manEdt/WMHext_manEdt_dnld.sh -s /path/to/studyFolder -i [list_of_IDs], where [list_of_IDs] is the list of IDs you want to edit, separated by coma. The script will generate a manual_editing.tar.gz file under the study folder.
- After uncompressing, the manual_editing folder contains the subjects you want to edit. For each subject, you can overlay the ID_WMH.nii.gz onto wrID_*.nii.gz, and editing the ID_WMH.nii.gz file in FSLVIEW. Replace the ID_WMH.nii.gz file with your edited WMH image.
- After finishing all the subjects, run tar czvf manual_editing.tar.gz manual_editing/* in the parent folder of the manual_editing folder.
- Run /path/to/CNSP/WMH_extraction/cmd/manEdt/WMHext_manEdt_upld.sh -s /path/to/studyFolder -m /path/to/manual_editing.tar.gz
Re-extraction¶
Users are able to re-extract WMH from middle steps, without the necessity of starting from the beginning after changing settings. This can be done by selecting the ‘Extract again’ menu on the top of UBO Detector GUI. UBO Detector offers options to re-extract WMH with:
- A different DARTEL template
- A different kNN classifier
- A different probability threshold - A different PVWMH magnitude
View kNN search¶
TOolbox for Probablistic MApping of Lesions (TOPMAL)¶
TOPMAL can map any lesion masks in DARTEL space to Johns Hopkins White Matter Tractography Atlas (JHU-WM atlas) or Harvard-Oxford (HO) Subcortical Atlas. The output of lesion loadings can be used for region-of-interest (ROI) lesion- symptom mapping (LSM) studies (see Biesbroek JM, et al. for a review).
Citation¶
If TOPMAL is used in your study, please cite:
Jiang, J., Paradise, M., Liu, T., Armstrong, N. J., Zhu, W., Kochan, N. A., Brodaty, H., Sachdev, P. S., Wen, W. The association of regional white matter lesions with cognition in a community-based cohort of older individuals, NeuroImage: Clinical 19:14-21 (2018), doi.org/10.1016/j.nicl.2018.03.035
Please also refer to this website for proper citation of the atlases.
TOPMAL GUI User Guide¶
Step 1: In MATLAB, add CNS to your path: addpath (‘/path/to/CNS’);
Step 2: Open CNS by typing CNS
Step 3: In the menu, select map2atlas -> TOPMAL. You will see the user interface of TOPMAL.
Step 4: If your lesion masks are white matter lesion (WML) masks generated using UBO Detector which follows a specific folder structure, please select Yes to the question “Lesion masks from UBO Detector?”. Otherwise, please choose No, and prepare a folder with lesion masks in DARTEL space, and name them as ID_lesMask.nii.
Step 5: Use the Find button to specify the path to the study folder where the output will be saved.
Step 6: Use the Find button to specify the path to the folder where the lesion masks are stored. These lesion masks should have been warped to DARTEL space. This step is not necessary for WML masks generated from UBO Detector (i.e. answering “Yes” to Step 4).
Step 7: Use the Find button to specify the path to SPM12 folder.
Step 8: If you are using WML lesion masks generated from the UBO_Detector, and used the “existing template” option in UBO Detector to map to the existing DARTEL templates, i.e. either existing DARTEL templates for less than 55 years old, 65-75 years old, or 70-80 years old, please select existing template for less than 55 yo, existing template for 65 to 75 yo, or existing template for 70 to 80 yo correspondingly. In such cases, we have stored the warped atlases in DARTEL space in CNS, and you do not need to rerun DARTEL. Otherwise, please select creating template, and TOPMAL will pop up a window to ask for Template1.nii, Template2.nii, … Template6.nii for the MNI-to-DARTEL transformation.
Step 9: Choose the atlas you want to map the lesion masks to. “JHU-ICBM_WM_tract_prob_1mm” represents the Johns Hopkins White Matter Tractography Atlas, and “HO_subcortical_1mm” is the Harvard-Oxford Subcortical Structural Atlas.
Step 10: Input the IDs (separated by space) you want to exclude from the TOPMAL analysis. This text box is only activated if you choose “Yes” to the question of “Lesion masks from UBO Detector”, meaning that if you excluded any subjects from UBO Detector, please list them in this text box.
Step 11: Click Run TOPMAL to run the analysis.
TOPMAL Commandline User Guide¶
Users can run commandline from MATLAB command window (or with a bit of coding from Linux shell).
Step 1: Add TOPMAL folder to path: addpath (‘/path_to_CNS/TOPMAL’);
Step 2: Run TOPMAL. If the lesion masks were WML masks from UBO Detector, please use TOPMAL_UDver.m. For example:
TOPMAL_UDver (‘/path/to/study/folder’, DARTELtemplate, ageRange, ‘/path/to/SPM12’, atlasCode, excldList);
If the lesion masks were from elsewhere, please use TOPMAL_generic.m. For example,
TOPMAL_generic (‘/path/to/DARTEL/lesion/masks/folder’, ‘/path/to/study/folder’, DARTELtemplate, ageRange, ‘/path/to/SPM12’, atlasCode);
- DARTELtemplate can be either ‘existing template’ or ‘creating template’.
- ageRange can be ‘lt55’, ‘65to75’, or ‘70to80’ for ‘existing template’, or ‘NA’ for ‘creating template’.
- atlasCode can be ‘JHU-ICBM_WM_tract_prob_1mm’ or ‘HO_subcortical_1mm’.
- excludList is the list of IDs, separated by space, that you want to exclude from TOPMAL analyses.
TOPMAL Output¶
Image output from TOPMAL¶
The images showing lesion masks mapping to atlas can be found at /path_to_study_folder/subjects/ID/mri/TOPMAL
The atlases are in 4D format, with each volume showing one structure. The image outputs from TOPMAL are in 3D with each image showing one structure.
Text output from TOPMAL¶
For each subject, the text output can be found at /path_to_study_folder/subjects/ID/stats
Each row represents one structure (see Appendix A for structure name). The five columns are Absolute loading, Fractional loading, Number of voxels where lesion mask overlaps with each 3D atlas (i.e. the 3D atlases (each represents one structure) splitted from the 4D atlas), Number of completely void voxels, and Void loading of partially void voxels. Please note the same number is shown in Column 4 and 5, respectively. This is because for one subject the number of completely void voxels and the void loading of partially void voxels are fixed.
For the whole cohort, TOPMAL outputs are summarised in:
/path_to_study_folder/subjects/TOPMAL_JHUwm_allprob.txt
OR
/path_to_study_folder/subjects/TOPMAL_HOsub_allprob.txt
Where *_absLoading is the absolute loading; *_fraLoading is the fractional loading; *_Nvox is the number of voxels where lesion mask overlaps with the structure; N_complete_void_vox is the number of completely void voxels; totalVoidLoading_partialVoidVox is the total void loading of partially void voxels. Appendix A: Structure name for JHU-WM and HO Subcortical atlases
JHU WM tracts¶
- JHU0 anterior_thalamic_radiation_L
- JHU1 anterior_thalamic_radiation_R
- JHU2 corticospinal_tract_L
- JHU3 corticospinal_tract_R
- JHU4 cingulum_(cingulate_gyrus)_L
- JHU5 cingulum_(cingulate_gyrus)_R
- JHU6 cingulum_(hippocampus)_L
- JHU7 cingulum_(hippocampus)_R
- JHU8 forceps_major
- JHU9 forceps_minor
- JHU10 inferior_fronto-occipital_fasciculus_L
- JHU11 inferior_fronto-occipital_fasciculus_R
- JHU12 inferior_longitudinal_fasciculus_L
- JHU13 inferior_longitudinal_fasciculus_R
- JHU14 superior_longitudinal_fasciculus_L
- JHU15 superior_longitudinal_fasciculus_R
- JHU16 uncinate_fasciculus_L
- JHU17 uncinate_fasciculus_R
- JHU18 superior_longitudinal_fasciculus_(temporal_part)_L
- JHU19 superior_longitudinal_fasciculus_(temporal_part)_R
HO subcortical¶
- HO0 left_cerebral_white_matter
- HO1 left_cerebral_cortex
- HO2 left_lateral_ventricle
- HO3 left_thalamus
- HO4 left_caudate
- HO5 left_putamen
- HO6 left_pallidum
- HO7 brain-stem
- HO8 left_hippocampus
- HO9 left_amygdala
- HO10 left_accumbens
- HO11 right_cerebral_white_matter
- HO12 right_cerebral_cortex
- HO13 right_lateral_ventricle
- HO14 right_thalamus
- HO15 right_caudate
- HO16 right_putamen
- HO17 right_pallidum
- HO18 right_hippocampus
- HO19 right_amygdala
- HO20 right_accumbens