Merge pull request scilus#1289 from karanphil/reconst_doc

Adding visualization commands and cleaning b-tensor files (to the docs)

Author: arnaudbore

docs/source/_static/bash/reconst/btensor_metrics.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail  # Will fail on error
+
+# ==============
+# How to run this script
+#    1) Load the input data
+#       https://scilpy.readthedocs.io/en/latest/documentation/getting_started.html
+#    2) Call this script with
+#    --->   bash btensor_metrics.sh  path/to/your/data  path/to/save/outputs
+# ==============
+in_dir=$1
+out_dir=$2
+
+in_dir=$in_dir/btensor
+
+# For now, the tutorial data only contains the masks.
+# Other necessary data can be obtained with:
+scil_data_download -v ERROR
+cp $HOME/.scilpy/btensor_testdata/* $in_dir/
+
+# ==============
+# Now let's run the tutorial
+# ==============
+cd $out_dir
+
+echo "Compute metrics"
+echo "*****************"
+scil_btensor_metrics \
+    --in_dwis $in_dir/dwi_linear.nii.gz $in_dir/dwi_planar.nii.gz $in_dir/dwi_spherical.nii.gz \
+    --in_bvals $in_dir/linear.bvals $in_dir/planar.bvals $in_dir/spherical.bvals \
+    --in_bvecs $in_dir/linear.bvecs $in_dir/planar.bvecs $in_dir/spherical.bvecs \
+    --in_bdeltas 1 -0.5 0 --fa $in_dir/fa.nii.gz --processes 8 --mask $in_dir/mask.nii.gz
+echo "Resulting files: "
+ls ./

…/_static/bash/reconst/btensor_scripts.sh …urce/_static/bash/reconst/memsmt_fodf.shdocs/source/_static/bash/reconst/btensor_scripts.sh renamed to docs/source/_static/bash/reconst/memsmt_fodf.sh docs/source/_static/bash/reconst/btensor_scripts.sh renamed to docs/source/_static/bash/reconst/memsmt_fodf.sh

@@ -6,7 +6,7 @@ set -euo pipefail  # Will fail on error
 #    1) Load the input data
 #       https://scilpy.readthedocs.io/en/latest/documentation/getting_started.html
 #    2) Call this script with
-#    --->   bash btensor_scripts.sh  path/to/your/data  path/to/save/outputs
+#    --->   bash memsmt_fodf.sh  path/to/your/data  path/to/save/outputs
 # ==============
 in_dir=$1
 out_dir=$2
@@ -41,12 +41,10 @@ scil_fodf_memsmt wm_frf.txt gm_frf.txt csf_frf.txt \
     --in_bvecs $in_dir/linear.bvecs $in_dir/planar.bvecs $in_dir/spherical.bvecs \
     --in_bdeltas 1 -0.5 0  --processes 8 --mask $in_dir/mask.nii.gz
 
-echo "Compute metrics"
-echo "*****************"
-scil_btensor_metrics \
-    --in_dwis $in_dir/dwi_linear.nii.gz $in_dir/dwi_planar.nii.gz $in_dir/dwi_spherical.nii.gz \
-    --in_bvals $in_dir/linear.bvals $in_dir/planar.bvals $in_dir/spherical.bvals \
-    --in_bvecs $in_dir/linear.bvecs $in_dir/planar.bvecs $in_dir/spherical.bvecs \
-    --in_bdeltas 1 -0.5 0 --fa $in_dir/fa.nii.gz --processes 8 --mask $in_dir/mask.nii.gz
+echo "3 - Visualizing the fODF"
+echo "************************"
+# Here, the --silent flag is used to avoid opening a visualization window.
+# It should be remove if you want to see the interactive visualization.
+scil_viz_fodf wm_fodf.nii.gz --silent --output fodf_memsmt.png
 echo "Resulting files: "
 ls ./

docs/source/_static/bash/reconst/msmt_fodf.sh

@@ -50,3 +50,9 @@ echo "Creating the fODF"
 echo "*****************"
 scil_fodf_msmt $in_dir/dwi.nii.gz $in_dir/dwi.bval $in_dir/dwi.bvec \
     wm_frf.txt gm_frf.txt csf_frf.txt --mask $in_dir/mask.nii.gz -v
+
+echo "Visualizing the fODF"
+echo "********************"
+# Here, the --silent flag is used to avoid opening a visualization window.
+# It should be remove if you want to see the interactive visualization.
+scil_viz_fodf wm_fodf.nii.gz --silent --output fodf_msmt.png

docs/source/_static/bash/reconst/ssst_fodf.sh

@@ -34,6 +34,12 @@ scil_frf_ssst $in_dir/dwi.nii.gz $in_dir/dwi.bval $in_dir/dwi.bvec frf.txt \
     --mask $in_dir/mask.nii.gz --mask_wm $in_dir/wm_mask.nii.gz -v
 
 echo "2 - Preparing the fODF"
-echo "*********************"
+echo "**********************"
 scil_fodf_ssst $in_dir/dwi.nii.gz $in_dir/dwi.bval $in_dir/dwi.bvec frf.txt fodf.nii.gz \
     --mask $in_dir/mask.nii.gz
+
+echo "3 - Visualizing the fODF"
+echo "************************"
+# Here, the --silent flag is used to avoid opening a visualization window.
+# It should be remove if you want to see the interactive visualization.
+scil_viz_fodf fodf.nii.gz --silent --output fodf_ssst.png

docs/source/documentation/reconstruction/btensor_metrics.rst

@@ -0,0 +1,40 @@
+Tensor-valued dMRI metrics reconstruction using DIVIDE
+======================================================
+
+This tutorial explains how to compute b-tensor metrics like uFA (microscopic fractional anisotropy) using the DIVIDE method [divide]_. Your data should contain more than one type of b-tensor encoding (ex: linear, planar, spherical). The following instructions are specific to b-tensor data and based on [divide]_.
+
+Preparing data for this tutorial
+********************************
+
+To run lines below, you need a various volumes, b-vector information and masks. The tutorial data is still in preparation, meanwhile you can use this: `
+
+.. code-block:: bash
+
+    in_dir=where/you/downloaded/tutorial/data
+    in_dir=$in_dir/btensor
+
+    # For now, the tutorial data only contains the masks.
+    # Other necessary data can be obtained with:
+    scil_data_download -v ERROR
+    cp $HOME/.scilpy/btensor_testdata/* $in_dir/
+
+.. tip::
+    You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/btensor_scripts.sh>`_.
+
+Computing b-tensor metrics
+**************************
+
+To run DIVIDE on your b-tensor data, you should use the following command. It will save files for the MD, uFA, OP, MK_I, MK_A and MK_T. This script should run in about 1-2 hours for a full brain.
+
+.. code-block:: bash
+
+    scil_btensor_metrics \
+        --in_dwis $in_dir/dwi_linear.nii.gz $in_dir/dwi_planar.nii.gz $in_dir/dwi_spherical.nii.gz \
+        --in_bvals $in_dir/linear.bvals $in_dir/planar.bvals $in_dir/spherical.bvals \
+        --in_bvecs $in_dir/linear.bvecs $in_dir/planar.bvecs $in_dir/spherical.bvecs \
+        --in_bdeltas 1 -0.5 0 --fa $in_dir/fa.nii.gz --processes 8 --mask $in_dir/mask.nii.gz
+
+References
+**********
+
+.. [divide] F. Szczepankiewicz et al., Tensor-valued diffusion encoding for diffusional variance decomposition (DIVIDE): Technical feasibility in clinical MRI systems. PloS one (2019)

docs/source/documentation/reconstruction/index.rst

@@ -8,7 +8,8 @@ This section covers local reconstruction methods in scilpy. They mainly use func
 
    ssst_fodf
    msmt_fodf
-   btensor_scripts
+   memsmt_fodf
    aodf_scripts
    qball_metrics
-   mti_scripts
+   mti_scripts
+   btensor_metrics

…ation/reconstruction/btensor_scripts.rst …mentation/reconstruction/memsmt_fodf.rstdocs/source/documentation/reconstruction/btensor_scripts.rst renamed to docs/source/documentation/reconstruction/memsmt_fodf.rst docs/source/documentation/reconstruction/btensor_scripts.rst renamed to docs/source/documentation/reconstruction/memsmt_fodf.rst

@@ -1,7 +1,7 @@
-Tensor-valued dMRI scripts (b-tensor)
-=====================================
+Multi-encoding multi-shell multi-tissue fODF (memsmt-fODF)
+==========================================================
 
-The scripts for multi-encoding multi-shell multi-tissue CSD (memsmt-CSD) are based on [memst]_. We recommend reading it to understand the scope of the memsmt-CSD problem.
+This tutorial explains how to compute multi-encoding multi-shell multi-tissue fiber orientation distribution functions (fODFs) using multi-encoding multi-shell multi-tissue constrained spherical deconvolution (memsmt-CSD) [memstCSD]_. You data should contain more than one type of b-tensor encoding (ex: linear, planar, spherical). The following instructions are specific to multi-encdoding and based on [memstCSD]_.
 
 Preparing data for this tutorial
 ********************************
@@ -54,17 +54,20 @@ Then, you should compute the fODFs and volume fractions. The following command w
 
 The resulting files are: csf_fodf.nii.gz gm_fodf.nii.gz  wm_fodf.nii.gz., as well as the volume fraction map: vf.nii.gz and vf_rgb.nii.gz.
 
-If you want to do DIVIDE with b-tensor data, you should use the following command. It will save files for the MD, uFA, OP, MK_I, MK_A and MK_T. This script should run in about 1-2 hours for a full brain.
+
+3. Visualizing the fODF
+***********************
+
+The resulting fODFs can be visualized using the following command:
 
 .. code-block:: bash
 
-    scil_btensor_metrics \
-        --in_dwis $in_dir/dwi_linear.nii.gz $in_dir/dwi_planar.nii.gz $in_dir/dwi_spherical.nii.gz \
-        --in_bvals $in_dir/linear.bvals $in_dir/planar.bvals $in_dir/spherical.bvals \
-        --in_bvecs $in_dir/linear.bvecs $in_dir/planar.bvecs $in_dir/spherical.bvecs \
-        --in_bdeltas 1 -0.5 0 --fa $in_dir/fa.nii.gz --processes 8 --mask $in_dir/mask.nii.gz
+     scil_viz_fodf wm_fodf.nii.gz
+
+See :ref:`scil_viz_fodf` for more information about the visualization options.
+
 
 References
 **********
 
-.. [memst] P. Karan et al., Bridging the gap between constrained spherical deconvolution and diffusional variance decomposition via tensor-valued diffusion MRI. Medical Image Analysis (2022)
+.. [memstCSD] P. Karan et al., Bridging the gap between constrained spherical deconvolution and diffusional variance decomposition via tensor-valued diffusion MRI. Medical Image Analysis (2022)

docs/source/documentation/reconstruction/msmt_fodf.rst

@@ -3,7 +3,7 @@
 Multi-shell multi-tissue fODF (msmt-fODF)
 =========================================
 
-This tutorial explains how to compute multi-shell multi-tissue fiber orientation distribution functions (fODFs) using multi-shell multi-tissue constrained spherical deconvolution (msmt-CSD) [multitissueCSD]_. If your data contains less than three b-values, you might want to consider using single-shell single-tissue CSD (ssst-CSD) instead. See the :ref:`ssst_fodf` instructions for that. The following instructions are specific to multi-shell and based on [multi-tissue_CSD]_.
+This tutorial explains how to compute multi-shell multi-tissue fiber orientation distribution functions (fODFs) using multi-shell multi-tissue constrained spherical deconvolution (msmt-CSD) [multitissueCSD]_. If your data contains less than three b-values, you might want to consider using single-shell single-tissue CSD (ssst-CSD) instead. See the :ref:`ssst_fodf` instructions for that. The following instructions are specific to multi-shell and based on [multitissueCSD]_.
 
 
 Preparing data for this tutorial
@@ -61,6 +61,19 @@ The second step is to perform multi-shell multi-tissue CSD (msmt-CSD) using :ref
 
 The script will output one fODFs file per tissue type, in nifti format (wm_fodf.nii.gz, gm_fodf.nii.gz and csf_fodf.nii.gz). The only optional arguments are the ``--sh_order`` option (default is 8) to set the maximum spherical harmonics order used to represent the fODFs and the ``--sh_basis`` option (default is 'descoteaux07') to set the spherical harmonics basis. The ``--processes`` option is used to speed up the computation by using multiple CPU cores. By default, the script will also output the volume fractions map (in default and RGB versions), with names vf.nii.gz and vf_rgb.nii.gz. To change any of the output names and paths or output only a selection of files, use the ``--not_all`` option along with the ``--wm_out_fODF``, ``--gm_out_fODF``, ``--csf_out_fODF``, ``--vf`` and ``--vf_rgb`` arguments. To visualize the fODFs, you can use :ref:`scil_viz_fodf`.
 
+
+3. Visualizing the fODF
+***********************
+
+The resulting fODFs can be visualized using the following command:
+
+.. code-block:: bash
+
+     scil_viz_fodf wm_fodf.nii.gz
+
+See :ref:`scil_viz_fodf` for more information about the visualization options.
+
+
 References
 **********
 

docs/source/documentation/reconstruction/ssst_fodf.rst

@@ -51,4 +51,16 @@ The second step is to perform single-shell single-tissue CSD (ssst-CSD) using :r
      scil_fodf_ssst $in_dir/dwi.nii.gz $in_dir/dwi.bval $in_dir/dwi.bvec frf.txt fodf.nii.gz \
         --mask $in_dir/mask.nii.gz
 
-The script will output the fODFs in a nifti file (fodf.nii.gz). The only optional arguments are the ``--sh_order`` option (default is 8) to set the maximum spherical harmonics order used to represent the fODFs and the ``--sh_basis`` option (default is 'descoteaux07') to set the spherical harmonics basis. The ``--processes`` option is used to speed up the computation by using multiple CPU cores. To visualize the fODFs, you can use :ref:`scil_viz_fodf`.
+The script will output the fODFs in a nifti file (fodf.nii.gz). The only optional arguments are the ``--sh_order`` option (default is 8) to set the maximum spherical harmonics order used to represent the fODFs and the ``--sh_basis`` option (default is 'descoteaux07') to set the spherical harmonics basis. The ``--processes`` option is used to speed up the computation by using multiple CPU cores.
+
+
+3. Visualizing the fODF
+***********************
+
+The resulting fODFs can be visualized using the following command:
+
+.. code-block:: bash
+
+     scil_viz_fodf fodf.nii.gz
+
+See :ref:`scil_viz_fodf` for more information about the visualization options.