Merge pull request #2 from dutchconnectomelab/release-v3.2.0

Documentation for CATO v3.2.0
dutchconnectomelab · Nov 30, 2022 · cd3861f · cd3861f
2 parents 37309f5 + 5eb8cf7
commit cd3861f
Show file tree

Hide file tree

Showing 10 changed files with 1,656 additions and 49 deletions.
diff --git a/_index/assets/bootstrap/css/bootstrap.min.css b/_index/assets/bootstrap/css/bootstrap.min.css
diff --git a/_index/assets/bootstrap/js/bootstrap.min.js b/_index/assets/bootstrap/js/bootstrap.min.js
diff --git a/_index/assets/css/Highlight-Phone.css b/_index/assets/css/Highlight-Phone.css
@@ -1,6 +1,6 @@
 .highlight-phone {
   color: #313437;
-  background-color: #eef4f7;
+  background-color: #F7FAFC;
   padding: 50px 0 55px;
   overflow: hidden;
 }
@@ -63,7 +63,7 @@
 }
 
 .highlight-phone .intro .btn-primary {
-  background-color: #055ada;
+  background-color: rgb(37 49 183 );
   color: #fff;
 }
 

diff --git a/_index/assets/css/styles.css b/_index/assets/css/styles.css
@@ -1,3 +1,9 @@
 body {
 }
 
+a {
+  color: rgb(37, 49, 183);
+  text-decoration: none;
+  background-color: transparent;
+}
+
diff --git a/_index/assets/img/methods.svg b/_index/assets/img/methods.svg
diff --git a/_index/index.html b/_index/index.html
@@ -36,7 +36,7 @@
             <nav class="navbar navbar-light navbar-expand-md navigation-clean">
                 <div class="container"><button data-toggle="collapse" class="navbar-toggler" data-target="#navcol-1"><span class="sr-only">Toggle navigation</span><span class="navbar-toggler-icon"></span></button>
                     <div class="collapse navbar-collapse" id="navcol-1"><img src="assets/img/CATO_logo.svg" style="max-height: 3rem;">
-                        <ul class="nav navbar-nav ml-auto">
+                        <ul class="navbar-nav ml-auto">
                             <li class="nav-item"><a class="nav-link" href="docs/installation.html">Download</a></li>
                             <li class="nav-item"><a class="nav-link" href="http://www.dutchconnectomelab.nl">Dutch Connectome Lab&nbsp;<i class="fa fa-external-link" style="color: rgba(0,0,0,0.3);font-size: 0.75rem;"></i></a></li>
                             <li class="nav-item"><a class="nav-link" href="http://www.github.com/dutchconnectomelab/CATO">GitHub&nbsp;<i class="fa fa-external-link" style="color: rgba(0,0,0,0.3);font-size: 0.75rem;"></i></a></li>
@@ -48,21 +48,21 @@
                 <div class="row">
                     <div class="col-12 col-lg-6 col-xl-5 offset-xl-1 p-0">
                         <h1 class="text-body">Structural and functional<br>connectome reconstruction</h1>
-                        <p class="text-dark">CATO is a modular software package for the reconstruction of brain connectivity based on DWI or rs-fMRI data.</p><a href="docs/installation.html"><button class="btn btn-dark btn-lg text-dark action-button" type="button">Get started with CATO</button></a></div>
-                    <div
-                        class="col align-self-end"><img src="assets/img/header_matrix.svg"></div>
+                        <p class="text-dark">CATO is a modular software package for the reconstruction of brain connectivity based on DWI or rs-fMRI data.</p><a href="docs/installation.html"><button class="btn btn-dark btn-lg text-dark action-button" type="button">Get started with CATO</button></a>
+                    </div>
+                    <div class="col align-self-end"><img src="assets/img/header_matrix.svg"></div>
+                </div>
             </div>
         </div>
     </div>
-    </div>
     <div class="team-grid">
         <div class="container">
             <div class="row">
                 <div class="col-9 mx-auto">
                     <h2 class="text-center">Connectome reconstruction toolbox</h2>
-                    <p class="text-center">CATO is an integrative and modular software package for the reconstruction of structural and functional brain connectivity based on diffusion weighted imaging and resting-state functional MRI data. CATO enables researchers to run end-to-end
-                        reconstructions from MRI data to structural and functional connectome maps, customize their analysis and utilize different software packages during the data preprocessing. <br></p>
-                    <p class="text-center">CATO is introduced in:<br><em>Structural and functional connectivity reconstruction with CATO</em><br>de Lange SC, van den Heuvel MP, 2020<br></p>
+                    <p class="text-center">CATO is an integrative and modular software package for the reconstruction of structural and functional brain connectivity based on diffusion weighted imaging and resting-state functional MRI data. CATO enables researchers to run end-to-end reconstructions from MRI data to structural and functional connectome maps, customize their analysis and utilize different software packages during the data preprocessing. <br></p>
+                    <p class="text-center">CATO is introduced in:<br><a href="https://www.biorxiv.org/content/10.1101/2021.05.31.446012" target="_blank"><em>Structural and functional connectivity reconstruction with CATO</em></a><br>de Lange SC, van den Heuvel MP, 2021<br><br></p><img src="assets/img/methods.svg" width="100%">
+                    <p class="text-center">CATO is a reconstruction toolbox useful for researchers at all technical levels including both easy to use default parameters and example scripts as well as advanced options to customize the reconstruction steps.&nbsp;&nbsp;</p>
                 </div>
             </div>
             <div class="intro"></div>
@@ -72,9 +72,8 @@ <h2 class="text-center">Connectome reconstruction toolbox</h2>
         <div class="container">
             <div class="intro"></div>
             <div class="row">
-                <div class="col-9 mx-auto">
+                <div class="col-9 mx-auto mb-2">
                     <h2 class="text-center">End-to-end reconstruction pipelines</h2>
-                    <p class="text-center">CATO is a reconstruction toolbox useful for researchers at all technical levels including both easy to use default parameters and example scripts as well as advanced options to customize the reconstruction steps.&nbsp;&nbsp;</p>
                 </div>
             </div>
             <div class="row features">
@@ -99,7 +98,8 @@ <h3 class="name">Free open-source software</h3>
                 <div class="col-md-8">
                     <div class="intro">
                         <h2>Getting started</h2>
-                        <p>Read the documentation, download CATO and start making your own connectomes!&nbsp;</p><a class="btn btn-primary" role="button" href="docs/installation.html">install CATO</a></div>
+                        <p>Read the documentation, download CATO and start making your own connectomes!&nbsp;</p><a class="btn btn-primary" role="button" href="docs/installation.html">install CATO</a>
+                    </div>
                 </div>
                 <div class="col-sm-4 d-xl-flex align-items-xl-end">
                     <div style="position: relative;"><img class="img-fluid" src="assets/img/screenshot_CATO_matlab.png" style="padding-left: 6rem;"><img class="img-fluid" src="assets/img/screenshot_CATO.png" style="/*margin-bottom: 1rem;*/position: absolute;/*top: 33%;*/left: 0;/*height: 75%;*/bottom: 10%;/*width: 75%;*/padding-right: 6rem;"></div>
@@ -137,11 +137,12 @@ <h3>About</h3>
                         </ul>
                     </div>
                     <div class="col-lg-3 align-self-end item social">
-                        <p class="copyright">Dutch Connectome Lab © 2020</p>
+                        <p class="copyright">Dutch Connectome Lab © 2022</p>
                     </div>
                 </div>
             </div>
-        </footer><!-- Cloudflare Web Analytics --><script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "c39e0a81b65e4f4da24ec6e9a9fc024a"}'></script><!-- End Cloudflare Web Analytics --></div>
+        </footer><!-- Cloudflare Web Analytics --><script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "c39e0a81b65e4f4da24ec6e9a9fc024a"}'></script><!-- End Cloudflare Web Analytics -->
+    </div>
     <script src="assets/js/jquery.min.js"></script>
     <script src="assets/bootstrap/js/bootstrap.min.js"></script>
     <script src="assets/js/CA.js"></script>

diff --git a/_static/emailform.html b/_static/emailform.html
@@ -12,7 +12,7 @@
 
 <blockquote>
 <div><ul class="simple">
-<li><p><a class="reference download external" href="javascript:;" onclick="ml_account('webforms', '2915332', 't8i0h3', 'show')"><code class="xref download docutils literal notranslate"><span class="pre">CATO</span> <span class="pre">v3.1.2</span> <span class="pre">-</span> <span class="pre">Mac</span> <span class="pre">OS</span> <span class="pre">X</span></code></a></p></li>
-<li><p><a class="reference download external" download="" href="javascript:;" onclick="ml_account('webforms', '2915332', 't8i0h3', 'show')"><code class="xref download docutils literal notranslate"><span class="pre">CATO</span> <span class="pre">v3.1.2</span> <span class="pre">-</span> <span class="pre">UNIX</span></code></a></p></li>
+<li><p><a class="reference download external" href="javascript:;" onclick="ml_account('webforms', '2915332', 't8i0h3', 'show')"><code class="xref download docutils literal notranslate"><span class="pre">CATO</span> <span class="pre">v3.2.0</span> <span class="pre">-</span> <span class="pre">Mac</span> <span class="pre">OS</span> <span class="pre">X</span></code></a></p></li>
+<li><p><a class="reference download external" download="" href="javascript:;" onclick="ml_account('webforms', '2915332', 't8i0h3', 'show')"><code class="xref download docutils literal notranslate"><span class="pre">CATO</span> <span class="pre">v3.2.0</span> <span class="pre">-</span> <span class="pre">UNIX</span></code></a></p></li>
 </ul>
 </div></blockquote>
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -20,7 +20,7 @@ This example processes Subject 0001 using the ``preprocess_eddy.sh`` preprocessi
 
 The following configuration file provides the minimum parameters that need to be specified. Copy the text and save it in a file (e.g. ``/Volumes/Example/CATO.conf``).
 
-    .. code-block:: JSON
+    .. code-block:: 
 
         {
             "general":{
@@ -132,7 +132,7 @@ Functional processing example
 --------------------------------------
 This example processes EXAMPLESUBJECT using the ``preprocess_default.sh`` preprocessing script. This preprocessing script performs a.o. slice time correction, motion correction, and mapping of the T1 parcellation to the rs-fMRI image (see :ref:`functional_preprocessing`). The following configuration file provides the minimum parameters to run the functional pipeline (including applying a bandpass filter and scrubbing). Copy the text and save it in a file (e.g. ``/Volumes/Example/CATO_functional.conf``).
 
-    .. code-block:: JSON
+    .. code-block:: json
 
         {
             "general":{
@@ -193,3 +193,42 @@ To run the functional pipeline with this configuration file:
             functional_pipeline(subjectDir, ...
                 'configurationFile', configurationFile);
 
+BIDS formatted data
+-----------------------------
+Brain imaging data structured according to the BIDS format is organized consistently, making it easy to process such datasets with CATO. Datasets will differ in their acquisition and scanner parameters, so makes it always important to adjust the configuration file to the dataset used. Parameters that are often the same for BIDS datasets are listed below. In this example, FreeSurfer reconstructions are expected in the `derivatives` subfolder of the dataset and the output of CATO will go into this `derivatives` folder as well.
+
+**Structural pipeline**
+
+.. code-block:: json
+
+    {    
+        "general":{
+            "derivativesDir":"../derivatives",
+            "freesurferDir": "DERIVATIVESDIR/freesurfer/SUBJECT",
+            "outputDir": "DERIVATIVESDIR/cato_structural/SUBJECT"
+        },
+        "structural_preprocessing": {
+            "rawBvalsFile": "ses-1/dwi/SUBJECT_ses-1_dwi.bval",
+            "rawBvecsFile": "ses-1/dwi/SUBJECT_ses-1_dwi.bvec",
+            "dwiFile": "ses-1/dwi/SUBJECT_ses-1_dwi.nii.gz"
+        }
+    }
+
+**Functional pipeline**
+
+.. code-block:: json
+
+    {
+        "general":{
+            "derivativesDir":"../derivatives",
+            "freesurferDir": "DERIVATIVESDIR/freesurfer/SUBJECT",
+            "outputDir": "DERIVATIVESDIR/cato_functional/SUBJECT"
+        },
+       "functional_preprocessing": {
+           "fmriFile": "SUBJECT/ses-1/func/SUBJECT_ses-1_task-rest_bold.nii.gz"
+       }
+   }
+
+fMRI preprocessing with Melodic + Fix
+-----------------------------------------------------
+Artifacts can be removed from the fMRI data using using an independent component analysis (ICA) approach in which the fMRI signal is decomposed into ICA components and "noise" components (including motion, non-neural physiological and scanner artifacts) are removed. An example preprocessing script for this approach using `FSL Fix <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FIX>`_ and `FSL Melodic <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/MELODIC>`_ is provided on the `GitHub repository <https://github.com/dutchconnectomelab/CATO/blob/b308a583392b92765507241703562b2b7ddd0594/src/functional_preprocessing/preprocess_ICAFIX.sh>`_. This example preprocessing script is currently in development and can be discussed in the associated `pull request <https://github.com/dutchconnectomelab/CATO/pull/22>`_.
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -4,15 +4,15 @@
 Installation 
 =================
 
-Download 
+Download
 --------------------
 
 Compiled binaries of the latest toolbox version:
 
 .. raw:: html
 	:file: ../_static/emailform.html
 
-and all source code is available on `the GitHub repository <https://github.com/dutchconnectomelab/CATO/>`_.
+and all source code is available on `the GitHub repository <https://github.com/dutchconnectomelab/CATO/>`_. CATO is also available as Docker image on `Docker Hub <https://hub.docker.com/r/dutchconnectomelab/cato>`_.
 
 Example configuration files can be downloaded (or use the :ref:`online Configuration Assistant <configuration assistant>`):
 
@@ -24,7 +24,16 @@ Additional software often used with CATO are described in the :ref:`Installation
 .. toggle-header::
     :header: **Release notes**
 
-    Older versions of CATO (executibles and source-code) can be downloaded from `the CATO repository on Github <https://github.com/dutchconnectomelab/CATO/releases>`_ and older versions of this documentation website (corresponding to older CATO versions) can be downloaded from `the CATO docs repository on Github <https://github.com/dutchconnectomelab/CATO-docs/releases>`_ .
+    Older versions of CATO (binaries and source-code) can be downloaded from `the CATO repository on Github <https://github.com/dutchconnectomelab/CATO/releases>`_ and older versions of this documentation website (corresponding to older CATO versions) can be downloaded from `the CATO docs repository on GitHub <https://github.com/dutchconnectomelab/CATO-docs/releases>`_ .
+
+    - Version 3.2.0 (30 November 2022)
+   	- Introduces a test framework for continuous integration.
+		- Lets users specify the functional connectivity measure (e.g. Pearson correlations or Pearson partial correlations).
+		- Preprocessing scripts are now compatible with FreeSurfer version 7.
+		- Removes dependencies on FreeSurfer and FSL in the MATLAB functions. FreeSurfer and FSL are now only used in the preprocessing and parcellation scripts that are provided by the user.
+		- Fixes various bugs (e.g. in the readTrk function, the iRESTORE threshold assistant).
+		- Improves various features (e.g. error handling and the check on the toolboxes installed in MATLAB).
+		- Full Changelog: https://github.com/dutchconnectomelab/CATO/commits/v3.2.0
 
     - Version 3.1.2 (28 May 2021)
     	- Fixes minor issue that let MATLAB utilize all available computational threads, but which is undesirable when running multiple instances of CATO in parallel. This minor patch introduces the parameter :term:`maxNumberCompThreads` (default = 1) that lets the user set the maximum number of used computational threads.
@@ -120,9 +129,4 @@ The third required software package is FreeSurfer. Downloads and instructions ar
 
 	http://www.freesurfer.net/fswiki/DownloadAndInstall
 
-The pipeline is tested with FreeSurfer version 6.0.0. Using newest FreeSurfer release ( > v7.0.0) results in a known error when using the example preprocessing scripts. The example preprocessing scripts try to clean-up the intermediate files produced by ``bbregister``, but the name of the log-file produced by ``bbregister`` in version 7.0.0. changed. As a result when the pipeline tries to delete the log-file (using the old name), it cannot be deleted resulting in an error. In the next version of CATO, the preprocessing scripts will be updated, for now this error can be fixed by deleting the following line from the preprocessing script::
-
-	rm "$registrationMatrixFile".{mincost,param,sum,log}
-
-This **does not affect** the processing in any way, it justs results in more files in the output directory.
-
+The pipeline is tested with FreeSurfer version 7.2.0.
diff --git a/docs/structural_pipeline.rst b/docs/structural_pipeline.rst
@@ -52,17 +52,19 @@ Custom preprocessing script
 ################################################
 The user can also specify a custom preprocessing script using the :term:`preprocessingScript` configuration parameter. The custom preprocessing script will get all general and structural_preprocessing configuration parameters as input (in the form: ``--parameterName=parameterValue``). For example, when using the configuration parameters
 
-    .. code-block:: JSON
+    .. code-block:: json
 
-		"structural_preprocessing":{ 
-			"dwiFile": "DTI/DTI.nii.gz",
-			"customParameter": "test",
-			"preprocessingScript": "CONFIGDIR/my_custom_script.sh"
-		}
+	    {
+	        "structural_preprocessing":{ 
+	            "dwiFile": "DTI/DTI.nii.gz",
+	            "customParameter": "test",
+	            "preprocessingScript": "CONFIGDIR/my_custom_script.sh"
+	        }
+	    }
 
 then the structural_preprocessing script executes the script ``my_custom_script.sh`` that is located in the same directory as the configuration file with ``customParameter`` as one of the input arguments:
 
-	.. code-block:: JSON
+	.. code-block:: 
 
 		/some/directory/my_custom_scipt.sh \
 			--dwiFile="DTI/DTI.nii.gz" \
@@ -194,14 +196,17 @@ Comparing the four reconstruction methods, DTI is a robust and simple method, wh
 
 Export diffusion measures to NIFTI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The :ref:`reconstruction_diffusion` step provides the user with the additional option to export diffusion measures to a NIFTI volume file :term:`diffusionMeasuresFileNifti <exportNifti.diffusionMeasuresFileNifti>`. To export fractional anisotropy, axial diffusivity, radial diffusivity and mean diffusivity measures to a file, add the following parameters to the ``reconstruction_diffusion`` section in the configuration file::
+The :ref:`reconstruction_diffusion` step provides the user with the additional option to export diffusion measures to a NIFTI volume file :term:`diffusionMeasuresFileNifti <exportNifti.diffusionMeasuresFileNifti>`. To export fractional anisotropy, axial diffusivity, radial diffusivity and mean diffusivity measures to a file, add the following parameters to the ``reconstruction_diffusion`` section in the configuration file:
 
-	"exportNifti":{
-		"exportNifti": true,
-		"measures": ["fractional anisotropy", "axial diffusivity", "radial diffusivity", "mean diffusivity"],
-		"diffusionMeasuresFileNifti": "OUTPUTDIR/SUBJECT_MEASURE.nii.gz"
-	}
+	.. code-block:: json
 
+		{
+			"exportNifti":{
+				"exportNifti": true,
+				"measures": ["fractional anisotropy", "axial diffusivity", "radial diffusivity", "mean diffusivity"],
+				"diffusionMeasuresFileNifti": "OUTPUTDIR/SUBJECT_MEASURE.nii.gz"
+			}
+		}
 
 .. _reconstruction_fibers: