From e455381803a8e3db6e4331ebafc0457ebccf44fb Mon Sep 17 00:00:00 2001 From: Philippe Karan Date: Tue, 2 Dec 2025 15:33:54 -0500 Subject: [PATCH] Adding visu commands and cleaning b-tensor files --- .../_static/bash/reconst/btensor_metrics.sh | 34 ++++++++++++++++ .../{btensor_scripts.sh => memsmt_fodf.sh} | 14 +++---- docs/source/_static/bash/reconst/msmt_fodf.sh | 6 +++ docs/source/_static/bash/reconst/ssst_fodf.sh | 8 +++- .../reconstruction/btensor_metrics.rst | 40 +++++++++++++++++++ .../documentation/reconstruction/index.rst | 5 ++- .../{btensor_scripts.rst => memsmt_fodf.rst} | 23 ++++++----- .../reconstruction/msmt_fodf.rst | 15 ++++++- .../reconstruction/ssst_fodf.rst | 14 ++++++- 9 files changed, 136 insertions(+), 23 deletions(-) create mode 100644 docs/source/_static/bash/reconst/btensor_metrics.sh rename docs/source/_static/bash/reconst/{btensor_scripts.sh => memsmt_fodf.sh} (75%) create mode 100644 docs/source/documentation/reconstruction/btensor_metrics.rst rename docs/source/documentation/reconstruction/{btensor_scripts.rst => memsmt_fodf.rst} (70%) diff --git a/docs/source/_static/bash/reconst/btensor_metrics.sh b/docs/source/_static/bash/reconst/btensor_metrics.sh new file mode 100644 index 000000000..2c00930f2 --- /dev/null +++ b/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 ./ \ No newline at end of file diff --git a/docs/source/_static/bash/reconst/btensor_scripts.sh b/docs/source/_static/bash/reconst/memsmt_fodf.sh similarity index 75% rename from docs/source/_static/bash/reconst/btensor_scripts.sh rename to docs/source/_static/bash/reconst/memsmt_fodf.sh index 13893b626..ae8ef19ad 100755 --- a/docs/source/_static/bash/reconst/btensor_scripts.sh +++ b/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 ./ \ No newline at end of file diff --git a/docs/source/_static/bash/reconst/msmt_fodf.sh b/docs/source/_static/bash/reconst/msmt_fodf.sh index 368a02ba0..28581995e 100755 --- a/docs/source/_static/bash/reconst/msmt_fodf.sh +++ b/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 diff --git a/docs/source/_static/bash/reconst/ssst_fodf.sh b/docs/source/_static/bash/reconst/ssst_fodf.sh index ecc27ed32..9fe58510d 100755 --- a/docs/source/_static/bash/reconst/ssst_fodf.sh +++ b/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 diff --git a/docs/source/documentation/reconstruction/btensor_metrics.rst b/docs/source/documentation/reconstruction/btensor_metrics.rst new file mode 100644 index 000000000..df6d53b14 --- /dev/null +++ b/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) diff --git a/docs/source/documentation/reconstruction/index.rst b/docs/source/documentation/reconstruction/index.rst index e8ceb5c6a..05b550f6f 100644 --- a/docs/source/documentation/reconstruction/index.rst +++ b/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 \ No newline at end of file + mti_scripts + btensor_metrics \ No newline at end of file diff --git a/docs/source/documentation/reconstruction/btensor_scripts.rst b/docs/source/documentation/reconstruction/memsmt_fodf.rst similarity index 70% rename from docs/source/documentation/reconstruction/btensor_scripts.rst rename to docs/source/documentation/reconstruction/memsmt_fodf.rst index c7f4f153b..532d09b99 100644 --- a/docs/source/documentation/reconstruction/btensor_scripts.rst +++ b/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) diff --git a/docs/source/documentation/reconstruction/msmt_fodf.rst b/docs/source/documentation/reconstruction/msmt_fodf.rst index 99da85370..49d21bddd 100644 --- a/docs/source/documentation/reconstruction/msmt_fodf.rst +++ b/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 ********** diff --git a/docs/source/documentation/reconstruction/ssst_fodf.rst b/docs/source/documentation/reconstruction/ssst_fodf.rst index c13660907..ba41bd8bc 100644 --- a/docs/source/documentation/reconstruction/ssst_fodf.rst +++ b/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`. \ No newline at end of file +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. \ No newline at end of file