updating documentation

docs/source/index.rst

@@ -40,7 +40,8 @@ If you use TOPMAL, please cite:
    :glob:
    :caption: Contents:
 
-   quickstart/quickstart
+   manual/*
+
 
 
 Indices and tables

docs/source/manual/advanced_settings.rst

@@ -0,0 +1,28 @@
+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.

docs/source/manual/customize_knn_classifier.rst

@@ -0,0 +1,37 @@
+Customize the kNN Classifier
+============================
+In order to customize kNN classifier, the data need to go through standard WMH segmentation procedures using UBO Detector.
+
+.. image:: UBO_Detector_Figure_5.png
+
+**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`. 
+
+.. image:: UBO_Detector_Figure_6.png
+
+**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.

docs/source/manual/longitudinal.rst

@@ -0,0 +1,34 @@
+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:
+
+.. image:: UBO_Detector_Figure_1.png
+
+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'.

docs/source/manual/loocv.rst

@@ -0,0 +1,2 @@
+Leave-one-out Cross Validation
+==============================

docs/source/manual/other_functions.rst

@@ -0,0 +1,27 @@
+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.
+
+a) `/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.
+
+b) 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.
+
+c) After finishing all the subjects, run `tar czvf manual_editing.tar.gz manual_editing/*` in the parent folder of the manual_editing folder.
+
+d) 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
+---------------

docs/source/manual/quickstart.rst

@@ -0,0 +1,84 @@
+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:
+
+.. image:: neuroimaging-quick-start-manual-datapreparation.png
+
+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*
+
+.. image:: neuroimaging-quick-start-manual-wmhextraction.png
+
+**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:: neuroimaging-quick-start-manual-output.png
+*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.*
+
+Folder structure of UBO Detector output
+---------------------------------------
+(Blue = folders, Orange = files)
+
+.. image:: neuroimaging-quick-start-manual-folder-structure.png
+
+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
+