diff --git a/docs/source/_static/my_style.css b/docs/source/_static/my_style.css index 17faf037d..6e4788133 100644 --- a/docs/source/_static/my_style.css +++ b/docs/source/_static/my_style.css @@ -15,4 +15,14 @@ /* Make citations use full page width instead of narrow blocks */ div.citation { display: flex !important; +} + +/* Default font size is 0.9rem. A bit small. Making it bigger. */ +div.citation a, p { + font-size: 1rem !important; +} + +/* Making links from :ref: gray. With blue, it was becoming heavy */ +.internal { + color: #878787; } \ No newline at end of file diff --git a/docs/source/documentation/bundle_analysis/create_population_template.rst b/docs/source/documentation/bundle_analysis/create_population_template.rst index 4c3d7adab..ca3fcf53c 100644 --- a/docs/source/documentation/bundle_analysis/create_population_template.rst +++ b/docs/source/documentation/bundle_analysis/create_population_template.rst @@ -5,7 +5,7 @@ Creating a bundle template from a chosen population Scilpy scripts enable users to create a WM bundle population template, such as described in figure 3 in our upcoming paper. Such a pipeline includes: -1) segmenting the bundle of interest in each subject’s tractogram. The segmentation of bundles can be based on ROIs of inclusion / exclusion (`scil_tractogram_segment_with_ROI_and_score` or `scil_tractogram_filter_by_roi`) or based on the general shape of the streamlines (`scil_tractogram_segment_with_recobundles`, `scil_tractogram_segment_with_bundleseg`). See :ref:`page_tractogram_segmentation` for more information on this. +1) segmenting the bundle of interest in each subject’s tractogram. The segmentation of bundles can be based on ROIs of inclusion / exclusion (:ref:`scil_tractogram_segment_with_ROI_and_score` or :ref:`scil_tractogram_filter_by_roi`) or based on the general shape of the streamlines (:ref:`scil_tractogram_segment_with_recobundles`, :ref:`scil_tractogram_segment_with_bundleseg`). See :ref:`page_tractogram_segmentation` for more information on this. 2) registering the bundles to a reference space (e.g., MNI space) and analysing the inter-subject variability, @@ -23,7 +23,7 @@ Then, registration can be performed (see :ref:`page_tractogram_registration`). T Preparing data for this tutorial ******************************** -To download data for this tutorial, see page :ref:`page_getting_started`_. Then do: +To download data for this tutorial, see page :ref:`page_getting_started`. Then do: .. code-block:: bash @@ -34,10 +34,10 @@ To download data for this tutorial, see page :ref:`page_getting_started`_. Then --data_type int16 -f $in_dir/sub-01/sub-01__wmparc.nii.gz -The labels come from a Freesurfer segmentation (https://surfer.nmr.mgh.harvard.edu/ ), and the labels that it contains are found here: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT . +The labels come from a `Freesurfer `_ segmentation, and the labels that it contains are found `in the FsWiki's Color Look-up Table (LUT) `_ . .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/bundle_analysis/create_population_template.sh>`_. Step A. Prepare the bundle of interest in each subject diff --git a/docs/source/documentation/bundle_analysis/profilometry.rst b/docs/source/documentation/bundle_analysis/profilometry.rst index 62cb4f5fd..3fb7a615a 100644 --- a/docs/source/documentation/bundle_analysis/profilometry.rst +++ b/docs/source/documentation/bundle_analysis/profilometry.rst @@ -3,20 +3,22 @@ Profilometry (statistics on bundles) ==================================== +Defining profilometry +********************* + Using a clean bundle from a single subject, scilpy allows performing a profilometry [1]_ analysis, which is the analysis of the evolution of any dMRI metrics along its subsections. A simple example is shown in Figure 4, and for further examples of such processes, users can refer to Tractometry-flow (https://github.com/scilus/tractometry_flow), a nextflow process using many scilpy scripts, or to the study by Cousineau et. al [2]_. -The creation of the bundles required tractogram segmentation (:ref:`page_tractogram_segmentation`). +The creation of the bundles requires tractogram segmentation (:ref:`page_tractogram_segmentation`). The profilometry analysis requires segmenting the bundles into as many subsections as desired. This is not straightforward, as the division of sections can be performed arbitrarily. We generally cut the section perpendicularly to the direction of the bundle, measured from a centroid, a single streamline-like shape representing the average of all streamlines in the bundle (`scil_bundle_compute_centroid`, `scil_bundle_label_map`). Then, any metric can be associated with the subsections. Figure 4 shows the example of the sections’ volume and diameter, or mean underlying value of any given map, such as the FA map. The resulting json file’s values can be plotted with scil_plot_stats_per_point. Beyond profilometry, other analysis steps could also be performed on the whole bundle. For instance, it is possible to compute the map of the head and tail of a bundle (the starting and ending regions of the bundle, assuming all streamlines are aligned in the same direction) with scil_bundle_uniformize_endpoints and scil_bundle_compute_endpoints_map. It is also possible to extract various information with `scil_bundle_shape_measures`. -Example: reproducing figure 4 in scilpy paper ---------------------------------------------- - .. image:: /_static/images/scilpy_paper_figure4.png :alt: Figure 4 in upcoming paper. +References +********** .. [1] Yeatman JD, Dougherty RF, Myall NJ, Wandell BA, Feldman HM. Tract Profiles of White Matter Properties: Automating Fiber-Tract Quantification. PLOS ONE. 2012;7(11):e49790. doi:10.1371/journal.pone.0049790 diff --git a/docs/source/documentation/bundle_analysis/tractogram_segmentation.rst b/docs/source/documentation/bundle_analysis/tractogram_segmentation.rst index 7fed7067d..35f611e49 100644 --- a/docs/source/documentation/bundle_analysis/tractogram_segmentation.rst +++ b/docs/source/documentation/bundle_analysis/tractogram_segmentation.rst @@ -6,8 +6,3 @@ Tractogram Segmentation into bundles Scilpy scripts offer many options to segment a tractogram into bundles. The resulting bundles can be cleaned more thoroughly than whole-brain tractograms, considering that their shapes should be quite uniform, and spurious streamlines can be discarded automatically with scil_bundle_reject_outliers or visually with `scil_bundle_clean_qbx_clusters`. The bundle could also be cut or trimmed using a binary mask, allowing it to focus on a specific region, using scil_tractogram_cut_streamlines. Optionally, metrics and statistics can be measured for each individual subject using our various scripts for bundle analysis, such as presented in :ref:`profilometry`. - -Examples of usage ------------------ - -- Creating a template. See :ref:`page_population_template`. \ No newline at end of file diff --git a/docs/source/documentation/reconstruction/aodf_scripts.rst b/docs/source/documentation/reconstruction/aodf_scripts.rst index b6cca43da..8c10e917e 100644 --- a/docs/source/documentation/reconstruction/aodf_scripts.rst +++ b/docs/source/documentation/reconstruction/aodf_scripts.rst @@ -32,10 +32,10 @@ Suggestion. For a faster processing of this tutorial data, you could crop the fo } .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/aodf_scripts.sh>`_. -Creating the aodf -***************** +1. Creating the aodf +******************** Although there is an automatic way to set the parameters, it is not yet implemented in scilpy. We recommend that you experiment with the parameters to find the best configuration for your data. Here, we use the smallest sphere available in Dipy, for a fast test. You can run the command as follows: @@ -52,8 +52,8 @@ The default script runs a pure python implementation, which is slow. To speed up The script will output the asymmetric ODF image (``afodf.nii.gz``) in the current directory. At the difference of a symmetric ODF image, which is represented using a symmetric spherical harmonics basis, the asymmetric ODF image is represented using a full spherical harmonics basis. Therefore, the output image will have more SH coefficients than the input image. For instance, for a maximum SH order of 8, the input image will have 45 coefficients per voxel, while the output image will have 81 coefficients per voxel. -Computing metrics -***************** +2. Computing metrics +******************** From the estimated AODF, we can compute a bunch of metrics using the script :ref:`scil_aodf_metrics`:. diff --git a/docs/source/documentation/reconstruction/btensor_scripts.rst b/docs/source/documentation/reconstruction/btensor_scripts.rst index b998f0608..c7f4f153b 100644 --- a/docs/source/documentation/reconstruction/btensor_scripts.rst +++ b/docs/source/documentation/reconstruction/btensor_scripts.rst @@ -19,7 +19,7 @@ To run lines below, you need a various volumes, b-vector information and masks. cp $HOME/.scilpy/btensor_testdata/* $in_dir/ .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/btensor_scripts.sh>`_. 1. Computing the frf ******************** @@ -64,4 +64,7 @@ If you want to do DIVIDE with b-tensor data, you should use the following comman --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 +********** + .. [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) diff --git a/docs/source/documentation/reconstruction/msmt_fodf.rst b/docs/source/documentation/reconstruction/msmt_fodf.rst index dcf17adae..99da85370 100644 --- a/docs/source/documentation/reconstruction/msmt_fodf.rst +++ b/docs/source/documentation/reconstruction/msmt_fodf.rst @@ -22,7 +22,7 @@ To run lines below, you need a various volumes, b-vector information and masks. cp $HOME/.scilpy/commit_amico/* $in_dir/ .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/msmt_fodf.sh>`_. 1. Computing the frf ******************** @@ -40,7 +40,13 @@ When available, it is possible to add following options (not available with curr --mask_wm $in_dir/wm_mask.nii.gz --mask_gm $in_dir/gm_mask.nii.gz --mask_csf $in_dir/csf_mask.nii.gz -The script will output one FRF per tissue type: white matter (WM), gray matter (GM), cerebrospinal fluid (CSF), in three text files (wm_frf.txt, gm_frf.txt and csf_frf.txt) that will be used in the next step. Each line in those files correspond to the response function of a b-value (in decreasing order from top to bottom). The first three numbers in each line are the parallel diffusivity and the perpendicular diffusivity (written twice) of the corresponding tissue type and b-value. These should typically be around 1.2-2.0 x 10^-3 mm^2/s and 0.25-0.5 x 10^-3 mm^2/s for WM, 0.6-1.0 x 10^-3 mm^2/s and 0.5-0.8 x 10^-3 mm^2/s for GM, and 1.5-3.0 x 10^-3 mm^2/s and 1.5-3.0 x 10^-3 mm^2/s for CSF, respectively. The last number is the average value of the b0 signal of the corresponding tissue type. If the FRFs look very different from these values or if you get an error from the script, you might be able to resolve the issue by changing some parameters and making sure the inputed tissue masks are correct. Indeed, the script works better with a mask for each tissue type (WM, GM and CSF) in addition to the brain mask. Moreover, you can change the FA and MD thresholds of used to refine the tissue masks, using the ``--fa_thr_wm``, ``--fa_thr_gm``, ``--fa_thr_csf``, ``--md_thr_wm``, ``--md_thr_gm`` and ``--md_thr_csf`` options. You can also change the minimum number of voxels required to compute each FRF using the ``--min_nvox`` option (default is 100). This is particularly helpful in the case of small images. In such cases, the ``--roi_radii`` and ``--roi_center`` options can also be used to specify regions of interest (ROIs) in each tissue type. In any case, the ``-v`` (verbose) option can be used to get more information about the process. Once you have computed the FRFs, you can proceed to compute the fODFs. +The script will output one FRF per tissue type: white matter (WM), gray matter (GM), cerebrospinal fluid (CSF), in three text files (wm_frf.txt, gm_frf.txt and csf_frf.txt) that will be used in the next step. Each line in those files correspond to the response function of a b-value (in decreasing order from top to bottom). The first three numbers in each line are the parallel diffusivity and the perpendicular diffusivity (written twice) of the corresponding tissue type and b-value. These should typically be respectively around + +- :math:`1.2 \text{ to } 2.0 \times 10^{-3}\ \text{mm}^2/\text{s}`, and :math:`0.25 \text{ to } 0.5 \times 10^{-3}\ \text{mm}^2/\text{s}` for WM +- :math:`0.6 \text{ to } 1.0 \times 10^{-3}\ \text{mm}^2/\text{s}`, and :math:`0.5 \text{ to } 0.8 \times 10^{-3}\ \text{mm}^2/\text{s}` for GM +- :math:`1.5 \text{ to } 3.0 \times 10^{-3}\ \text{mm}^2/\text{s}`, and :math:`1.5 \text{ to } 3.0 \times 10^{-3}\ \text{mm}^2/\text{s}` for CSF + +The last number is the average value of the b0 signal of the corresponding tissue type. If the FRFs look very different from these values or if you get an error from the script, you might be able to resolve the issue by changing some parameters and making sure the inputed tissue masks are correct. Indeed, the script works better with a mask for each tissue type (WM, GM and CSF) in addition to the brain mask. Moreover, you can change the FA and MD thresholds of used to refine the tissue masks, using the ``--fa_thr_wm``, ``--fa_thr_gm``, ``--fa_thr_csf``, ``--md_thr_wm``, ``--md_thr_gm`` and ``--md_thr_csf`` options. You can also change the minimum number of voxels required to compute each FRF using the ``--min_nvox`` option (default is 100). This is particularly helpful in the case of small images. In such cases, the ``--roi_radii`` and ``--roi_center`` options can also be used to specify regions of interest (ROIs) in each tissue type. In any case, the ``-v`` (verbose) option can be used to get more information about the process. Once you have computed the FRFs, you can proceed to compute the fODFs. 2. Computing the fODF @@ -55,7 +61,7 @@ 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`. -.. [multitissueCSD] Jeurissen et al. NeuroImage 2014, "Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data". +References +********** - -`The complete b-tensor scripts tutorial bash script `_. \ No newline at end of file +.. [multitissueCSD] Jeurissen et al. NeuroImage 2014, "Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data". diff --git a/docs/source/documentation/reconstruction/mti_scripts.rst b/docs/source/documentation/reconstruction/mti_scripts.rst index 549bde9f5..9a2b1322d 100644 --- a/docs/source/documentation/reconstruction/mti_scripts.rst +++ b/docs/source/documentation/reconstruction/mti_scripts.rst @@ -112,7 +112,7 @@ Overall, we have data for a subject, containing: .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/mti_scripts.sh>`_. Step-by-step processing *********************** @@ -267,7 +267,7 @@ This workflow handles conversion, registration, and execution of the ``scil_mti_ References ----------- +********** [1] Varma G, Girard OM, Prevost VH, Grant AK, Duhamel G, Alsop DC. Interpretation of magnetization transfer from inhomogeneously broadened diff --git a/docs/source/documentation/reconstruction/qball_metrics.rst b/docs/source/documentation/reconstruction/qball_metrics.rst index 4595558cf..65abe799a 100644 --- a/docs/source/documentation/reconstruction/qball_metrics.rst +++ b/docs/source/documentation/reconstruction/qball_metrics.rst @@ -26,7 +26,7 @@ To run the script, you need a DWI image with its corresponding b-values and b-ve .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/qball_metrics.sh>`_. Running Q-ball diff --git a/docs/source/documentation/reconstruction/ssst_fodf.rst b/docs/source/documentation/reconstruction/ssst_fodf.rst index 0c1e68ef0..c13660907 100644 --- a/docs/source/documentation/reconstruction/ssst_fodf.rst +++ b/docs/source/documentation/reconstruction/ssst_fodf.rst @@ -23,7 +23,7 @@ The tutorial data is still in preparation, meanwhile you can use this: cp $HOME/.scilpy/processing/fa_thr.nii.gz $in_dir/wm_mask.nii.gz .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/reconst/ssst_fodf.sh>`_. 1. Computing the frf diff --git a/docs/source/documentation/tracking/fibertube_tracking.rst b/docs/source/documentation/tracking/fibertube_tracking.rst index 05d6f8ea8..c9c9ce218 100644 --- a/docs/source/documentation/tracking/fibertube_tracking.rst +++ b/docs/source/documentation/tracking/fibertube_tracking.rst @@ -362,5 +362,3 @@ This reconstruction is not very good, but it is to be expected with a --blur_radius and --step_size of 0.1. If you have a few minutes, try again with 0.01! -End of Demo ------------ diff --git a/docs/source/documentation/tractogram_manipulation/index.rst b/docs/source/documentation/tractogram_manipulation/index.rst index 160ed4757..60e0c0433 100644 --- a/docs/source/documentation/tractogram_manipulation/index.rst +++ b/docs/source/documentation/tractogram_manipulation/index.rst @@ -10,4 +10,3 @@ This section covers tractogram manipulation methods in scilpy. Most of the funct tractogram_registration tractogram_math streamlines_math - tractogram_filtering diff --git a/docs/source/documentation/tractogram_manipulation/streamlines_math.rst b/docs/source/documentation/tractogram_manipulation/streamlines_math.rst index 5af69996f..40649c7e8 100644 --- a/docs/source/documentation/tractogram_manipulation/streamlines_math.rst +++ b/docs/source/documentation/tractogram_manipulation/streamlines_math.rst @@ -1,7 +1,7 @@ .. _page_streamlines_math: -Streamlines manipulation (resampling, smoothing) -================================================ +Streamlines manipulation +======================== Here, we discuss scripts allowing modifying the streamlines themselves, for instance by resampling the number of points on each streamline (:ref:`scil_tractogram_resample_nb_points`, :ref:`scil_tractogram_compress`), or smoothing the streamlines’ trajectories (:ref:`scil_tractogram_smooth`). @@ -32,7 +32,7 @@ To look at your data in a viewer, you may use the subject's T1 volume: t1=$in_folder/sub-01/sub-01__t1.nii.gz .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/tractogram_manipulation/streamlines_math.sh>`_. Resampling the number of points in each streamline ************************************************** diff --git a/docs/source/documentation/tractogram_manipulation/tractogram_filtering.rst b/docs/source/documentation/tractogram_manipulation/tractogram_filtering.rst deleted file mode 100644 index 28469bdc9..000000000 --- a/docs/source/documentation/tractogram_manipulation/tractogram_filtering.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _page_tractogram_filtering: - -Tractogram filtering -==================== - -(to come) \ No newline at end of file diff --git a/docs/source/documentation/tractogram_manipulation/tractogram_math.rst b/docs/source/documentation/tractogram_manipulation/tractogram_math.rst index 0c3f5e063..bcf457363 100644 --- a/docs/source/documentation/tractogram_manipulation/tractogram_math.rst +++ b/docs/source/documentation/tractogram_manipulation/tractogram_math.rst @@ -7,15 +7,31 @@ Scilpy scripts allow users to modify tractograms in various ways based on their The range of possibilities is wide! ------------------------------------ +*********************************** -- Mathematical operations on two tractograms such as union, intersection and difference can be performed through the :ref:`scil_tractogram_math` script. +- Mathematical operations on **two tractograms** -- Some scripts allow operations on the tractogram as a whole object in the brain, such as flipping it on a chosen axis (:ref:`scil_tractogram_flip`) or creating a map of all voxels touched by a streamline (:ref:`scil_tractogram_compute_density_map`). + - Union, intersection and difference can be performed through the :ref:`scil_tractogram_math` script. -- Other scripts allow operations on the tractogram as set of streamlines, such as resampling the number of streamlines (:ref:`scil_tractogram_resample`, :ref:`scil_tractogram_split`), separating streamlines based on various criteria (:ref:`scil_tractogram_filter_by_roi`, :ref:`scil_tractogram_filter_by_anatomy`, :ref:`scil_tractogram_filter_by_length`, :ref:`scil_tractogram_filter_by_orientation`) or segmenting a tractogram into bundles (see :ref:`page_tractogram_segmentation`). +- Some scripts allow operations on **a single tractogram as a whole object** in the brain -- Finally, other scripts allow modifying the streamlines themselves, for instance by resampling the number of points on each streamline (:ref:`scil_tractogram_resample_nb_points`, :ref:`scil_tractogram_compress`), or smoothing the streamlines’ trajectories (:ref:`scil_tractogram_smooth`). See page :ref:`page_streamlines_math` for more information. + - We can flip it on a chosen axis with :ref:`scil_tractogram_flip` + + - We can create a map of all voxels touched by a streamline with :ref:`scil_tractogram_compute_density_map`. + +- Other scripts allow operations on **a single tractogram as set of streamlines** + + - We can resample the number of streamlines (:ref:`scil_tractogram_resample`, :ref:`scil_tractogram_split`) + + - We can filter out streamlines based on various criteria (:ref:`scil_tractogram_filter_by_roi`, :ref:`scil_tractogram_filter_by_anatomy`, :ref:`scil_tractogram_filter_by_length`, :ref:`scil_tractogram_filter_by_orientation`) + + - We can segment a tractogram into bundles (see :ref:`page_tractogram_segmentation`). + +- Finally, other scripts allow modifying **the streamlines themselves**. See page :ref:`page_streamlines_math` for more information. + + - We can resample the number of points on each streamline (:ref:`scil_tractogram_resample_nb_points`, :ref:`scil_tractogram_compress`) + + - We can smooth the streamlines’ trajectories (:ref:`scil_tractogram_smooth`). Overall, figure 2 in our upcoming paper represents well the range of possibilities. @@ -28,9 +44,6 @@ Overall, figure 2 in our upcoming paper represents well the range of possibiliti | ** For an example of streamlines cutting, see :ref:`page_streamlines_math`. -Examples of tractogram manipulation ------------------------------------ - Preparing data for this tutorial ******************************** @@ -55,7 +68,7 @@ We used MI-Brain to visualize both tractograms, which each contain one part of t .. tip:: - You may download the complete bash script to run the whole tutorial in one step `here `_. + You may download the complete bash script to run the whole tutorial in one step `⭳ here <../../_static/bash/tractogram_manipulation/tractogram_math.sh>`_. A. Logical operations @@ -84,12 +97,12 @@ If a streamline is exactly the same in both tractograms, it will be kept once. scil_tractogram_math difference $tractogram1 $tractogram2 difference1-2.trk -Below is the result of the intersection operation. The streamlines in red belonged to both tractograms and form the new file intersection.trk. - -.. image:: /_static/images/tractogram_math_intersection.png +.. figure:: /_static/images/tractogram_math_intersection.png :alt: Intersection result :width: 40% + Result of the intersection operation. The streamlines in orange belonged to both tractograms and form the new file intersection.trk. + B. Tractogram resampling ************************ @@ -110,16 +123,6 @@ Most of the time, you can use the default value for --qbx_thresholds, particular scil_tractogram_resample $tractogram1 200 tractogram_downsampled2.trk \ --downsample_per_cluster -v --qbx_thresholds 3 -See the difference between the two calls above: - -+------------------------------------------+----------------------------------------------+ -| Random selection | Selection per Quickbundle cluster | -+==========================================+==============================================+ -| .. image:: /?? | .. image:: ? | -| :width: 35% | :width: 35% | -| :align: center | :align: center | -+------------------------------------------+----------------------------------------------+ -======= You may open and compare tractogram_downsampled.trk and tractogram_downsampled2.trk. Here, data is small and in both cases, the downsampling should cover a good portion of the spatial extend of the bundle, even though the first call is random. On whole-brain data, the difference can be more impressive. **2. Upsampling:** @@ -131,11 +134,11 @@ To add more streamlines to our tractogram, the script uses randomly picked strea scil_tractogram_resample $tractogram1 4000 tractogram_upsampled.trk \ --point_wise_std 5 -v --tube_radius 4 -Below, we show a zoomed view on the results. In green: the original bundle. In blue: the new streamlines. - -.. image:: /_static/images/tractogram_math_upsampling.png +.. figure:: /_static/images/tractogram_math_upsampling.png :alt: Intersection result - :width: 40% + :width: 50% + + Zoomed view on the results. In green: the original bundle. In blue: the new streamlines. **3. Splitting a tractogram** diff --git a/docs/source/documentation/tractogram_manipulation/using_trk_or_tck.rst b/docs/source/documentation/tractogram_manipulation/using_trk_or_tck.rst index 97d68df82..529b1531b 100644 --- a/docs/source/documentation/tractogram_manipulation/using_trk_or_tck.rst +++ b/docs/source/documentation/tractogram_manipulation/using_trk_or_tck.rst @@ -1,7 +1,7 @@ Using trk or tck files ====================== -TRK files already have some metadata stored in its header. It knows the position of the tractogram in the space. When using TCK files however, this information is not given. You may view this file as a list of streamline coordinates, but no information on where point (0,0,0) actually is. All our scripts using tractograms offer the option ``--reference``. This is meant to be used when your input is a TCK file. We will read the information in another associated file (for instance a nifti volume) that is in the same space as your tractogram. It should be a file from the same subject, in the same space. +TRK files already have some metadata stored in their headers. The header knows the position of the tractogram in the space. When using TCK files however, this information is not given. You may view this file as a list of streamline coordinates, but no information on where point (0,0,0) actually is. All our scripts using tractograms offer the option ``--reference``. This is meant to be used when your input is a TCK file. We will read the information in another associated file (for instance a nifti volume) that is in the same space as your tractogram. It should be a file from the same subject, in the same space. In our tutorials using tractograms, we make sure to use inputs as TRK files to declutter our command lines, removing the ``--reference`` at each new call. Don't hesitate to add them back if your own data is in TCK format. @@ -9,4 +9,19 @@ Else, you can use this to convert your file to TRK before using it: .. code-block:: bash - scil_tractogram_convert my_file.tck my_file.trk --reference my_volume.nii.gz \ No newline at end of file + scil_tractogram_convert my_file.tck my_file.trk --reference my_volume.nii.gz + +You may also use :ref:`scil_header_print_info` on both types of files. The result will look like:: + + ************************************** + File name: tracto.tck + ************************************** + Dimensions: (138, 166, 134) + Voxel size: (1.0, 1.0, 1.0) + Datatype: Float32LE + Orientation: ('R', 'A', 'S') + Afine (vox2rasmm): + [[1. 0. 0. 0.] + [0. 1. 0. 0.] + [0. 0. 1. 0.] + [0. 0. 0. 1.]]