Docs: Update ACT page

cmd/tckgen.cpp

@@ -16,6 +16,7 @@
 
 #include "command.h"
 #include "image.h"
+#include "version.h"
 
 #include "dwi/tractography/properties.h"
 #include "dwi/tractography/roi.h"
@@ -135,7 +136,10 @@ void usage ()
       "order of integration: for any first-order method, this angle corresponds to the "
       "deviation in streamline trajectory per step; for higher-order methods, this "
       "corresponds to the change in underlying fibre orientation between the start and "
-      "end points of each step.";
+      "end points of each step."
+
+    + "More information on the requisite data for option -act can be found at: "
+      "https://mrtrix.readthedocs.io/en/" MRTRIX_BASE_VERSION "/quantitative_structural_connectivity/act.html";
 
   REFERENCES
    + "References based on streamlines algorithm used:"

docs/quantitative_structural_connectivity/act.rst

@@ -18,17 +18,141 @@ For the anatomical information to be incorporated accurately during the tractogr
 Image registration
 ^^^^^^^^^^^^^^^^^^
 
-My personal preference is to register the T1-contrast anatomical image to the diffusion image series before any further processing of the T1 image is performed. By registering the T1 image to the diffusion series rather than the other way around, reorientation of the diffusion gradient table is not necessary; and by doing this registration before subsequent T1 processing, any subsequent images derived from the T1 are inherently aligned with the diffusion image series. This registration should be rigid-body only; if the DWI distortion correction is effective, a higher-order registration is likely to only introduce errors.
+The typical advice currently is,
+having computed a registration between the diffusion image series and the T1-weighted image,
+to apply the corresponding transformation to the DWI series during pre-processing.
+By doing this registration as early as is reasonable,
+any subsequent images derived from either the DWI series or the T1-weighted image are inherently aligned with one another.
+This registration should be rigid-body only:
+if the DWI distortion correction is effective,
+a higher-order registration is likely to only introduce errors.
+
+.. note::
+
+    Earlier versions of this documentation suggested transformation of the T1-weighted image to align with the DWI series.
+    The justification for this process is that it obviates the danger of applying a spatial transformation to diffusion-weighted image data
+    without also performing the requisite rotation of the diffusion gradient directions.
+    At the time of update however,
+    this recommendation has been *reversed*,
+    for two reasons:
+
+    -   If the ``mrtransform`` command is used to apply a linear transformation to DWI data,
+        it will *automatically* apply the rotation component of that transformation
+        to any diffusion gradient table embedded within the image header.
+
+    -   Modern neuroimaging experiments are frequently multi-modal.
+        In this context,
+        it is often necessary to define a singular reference image to which all other image data are aligned.
+        This is very likely to be a T1-weighted image.
+        Transforming a T1-weighted image to align with the DWI voxel grid would therefore result
+        in derivatives of both that transformed T1-weighted image and the DWI series
+        not being spatially aligned with other modalities.
+
+    There does however remain residual scope for this process to go awry:
+
+    -   Do *not* apply a linear transform to a DWI series,
+        and then interpret those data with respect to a diffusion gradient table
+        that is stored in an *external text file in MRtrix format* rather than within the image header;
+        failure to rotate that table according to the applied spatial transformation would result in erroneous outcomes.
+
+    -   If relying on storage of the diffusion gradient table in the FSL ``bvecs`` / ``bvals`` format,
+        those diffusion sensitisation directions rotate according to the rotation of the image voxel grid,
+        such that they appropriately mimic the spatial transformation of the image data.
+        This is however *only* appropriate if the *strides of the output image match the input image*.
+        If this is violated for any reason
+        ---for instance, by specifying not only a linear transformation to be applied but also a template voxel grid on which to resample the data---
+        then the diffusion gradient table will no longer be suitable for analysis of those image data.
+
 
 DWI pre-processing
 ^^^^^^^^^^^^^^^^^^
 
-Because the anatomical image is used to limit the spatial extent of streamlines propagation rather than a binary mask derived from the diffusion image series, I highly recommend dilating the DWI brain mask prior to computing FODs; this is to make sure that any errors in derivation of the DWI mask do not leave gaps in the FOD data within the brain white matter, and therefore result in erroneous streamlines termination.
+Historically, a brain mask derived from the DWI data themselves would be utilised to constrain the propagation of streamlines outside of the brain.
+Such a mask could therefore also be used to limit the computational expense of processing steps such as FOD estimation.
+ACT provides the prospect of altering this precedent,
+given that delineation of the spatial extent of the brain could be more reliably determined from the T1-weighted image data
+owing to its higher spatial resolution and tissue contrast.
+It is suggested that *if* one chooses to make use of a mask to prevent the estimation of FODs where they are not needed,
+then that mask should be *more generous* than one's estimate of the spatial extent of the brain,
+for two reasons:
+
+1.  If a DWI-derived brain mask erroneously under-estimates the extent of the brain,
+    then this could cause premature termination of streamlines within the brain
+    when the extent of the brain is defined based on the tissue segmentation derived from the anatomical image.
+    This would be more deleterious to data quality
+    than would be estimation of FODs outside of that region.
+
+2.  When streamline propagation occurs,
+    fibre orientations are derived for sub-voxel locations through *interpolation*.
+    This means that a streamline vertex may reside within a voxel that is included in a mask,
+    but the interpolation that defines the next direction of traversal at that sub-voxel locations
+    may be determined making use of image data from voxels *not* included in that mask.
+    For this reason it may be beneficial
+    ---even technically if not utilising ACT---
+    for fibre orientations to be estimated based on a mask that has gone through at least two dilations
+    (necessary to ensure that for any sub-voxel location inside of the intended mask,
+    valid image data are present for all 8 voxels in the trilinear interpolation neighbourhood).
 
 Tissue segmentation
 ^^^^^^^^^^^^^^^^^^^
 
-So far I have had success with using FSL tools to also perform the anatomical image segmentation; FAST is not perfect, but in most cases it's good enough, and most alternative software I tried provided binary mask images only, which is not ideal. The ``5ttgen`` script using the ``fsl`` algorithm interfaces with FSL to generate the necessary image data from the raw T1 image, using BET, FAST and FIRST. Note that this script also crops the resulting image so that it contains no more than the extracted brain (as this reduces the file size and therefore improves memory access performance during tractography); if you want the output image to possess precisely the same dimensions as the input T1 image, you can use the ``-nocrop`` option.
+The ``5ttgen`` command provides a common interface to many algorithms
+for taking tissue segmentations from a high-resolution anatomical image
+(sometimes pre-computed, sometimes computed internally from the image data),
+and producing a tissue segmentation image in the format as expected for ACT
+(see 5TT_ below).
+
+-   The ``5ttgen fsl`` algorithm is what was presented in the ACT article.
+-   The ``5ttgen freesurfer`` algorithm is exceptionally fast
+    (discounting the computational expense required to initially run FreeSurfer);
+    but because the tissue segmentation is a *hard* segmentation
+    ---that is, each voxel consists of exactly one tissue type only---
+    the resulting image does not provide continuous *partial volume fractions*,
+    such that there is minimal useful sub-voxel interpolation information.
+    This can lead to ugly ''stair-stepping'' artifacts in the resulting tractograms,
+    where streamline terminations follow the pattern of the voxel grid
+    rather than the smooth tissue interfaces.
+-   The ``5ttgen hsvs`` algorithm is the most advanced and generally recommended algorithm.
+    It is however only applicable to *in vivo* human data
+    given that it is predicated on FreeSurfer (and also typically FSL FIRST).
+    It is also the most likely to undergo ongoing development.
+-   If particular tissue segmentation algorithms are advantageous in particular contexts,
+    and the use of such derivative data for ACT could be similarly beneficial,
+    researchers are encouraged to develop their own ``5ttgen`` algorithms,
+    in which case they can be made available to the wider research community.
+    This simply involves duplicating one of the existing files in directory ``lib/mrtrix3/_5ttgen/``
+    and modifying the underlying content as appropriate;
+    the ``5ttgen`` script will *automatically* detect the presence of the new algorithm
+    and make it available at the command-line.
+
+Note that by default,
+``5ttgen`` will *crop* the tissue segmentation image
+so that its spatial extent is no larger than is necessary to encapsulate the non-zero data.
+This is done to reduce file size
+and additionally to benefit computational performance during streamline propagation.
+If there is instead justification on the part of the researcher
+that the resulting image should have *exactly* the same voxel grid as the input image,
+then this final cropping step can be bypassed using the ``-nocrop`` option.
+
+A computed tissue segmentation image
+will typically have the same spatial resolution
+as whatever high-resolution anatomical-contrast image it was computed from,
+and is typically derived independently of any DWI data.
+This means that the tissue segumentation image and the DWI data
+(or derivatives thereof)
+will reside on *different voxel grids*
+(in terms of spatial resolution and/or orientations of image axes).
+As communicated in the original ACT article,
+this is a *positive attribute* of the implementation:
+each source of image data preserves its native spatial resolution
+and does not undergo any unecessary resampling
+during which interpolation invariably introduces some degree of image blurring.
+As streamlines are propagated,
+sub-voxel interpolation is performed *independently* for ACT image data and DWI data,
+such that their residing on a common voxel grid is not necessary.
+It is therefore generally *discouraged* to explicitly apply an intervention
+to place these data onto a common voxel grid,
+given that doing so is unnecessary and may have deleterious consequences.
 
 Using ACT
 ---------
@@ -37,7 +161,6 @@ Once the necessary pre-processing steps are completed, using ACT is simple: just
 
 In addition, since the propagation and termination of streamlines is primarily handled by the 5TT image, it is no longer necessary to provide a mask using the ``-mask`` option. In fact, for whole-brain tractography, it is recommend that you _not_ provide such an image when using ACT: depending on the accuracy of the DWI brain mask, its inclusion may only cause erroneous termination of streamlines inside the white matter due to exiting this mask. If the mask encompasses all of the white matter, then its inclusion does not provide any additional information to the tracking algorithm.
 
-
 .. _5TT:
 
 The 5TT format
@@ -59,11 +182,3 @@ The following binaries are provided for working with the 5TT format:
 * ``5tt2vis``: Produces a 3D greyscale image suitable for visualisation purposes.
 * ``5ttcheck``: Check that one or more input images conform to the 5TT format.
 * ``5ttedit``: Allows the user to edit the tissue segmentations. Useful for manually correcting tissue segmentations that are known to be erroneous (e.g. dark blobs in the white matter being labelled as grey matter); see the command's help page for more details.
-
-Alternative tissue segmentation software
-----------------------------------------
-
-Users who wish to experiment with using tissue segmentations from different software sources are encouraged to do so; if a particular approach is shown to be effective we can add an appropriate script to MRtrix. The ``5ttgen`` script has a second algorithm, ``freesurfer``, which demonstrates how the output of different software can be manipulated to provide the tissue segmentations in the appropriate format. It is however not recommended to actually use this alternative algorithm for patient studies; many midbrain structures are not segmented by FreeSurfer, so the tracking may not behave as desired.
-
-Users who wish to try manipulating the tissue segmentations from some alternative software into the 5TT format may find it most convenient to make a copy of one of the existing algorithms within the ``lib/mrtrix3/_5ttgen/`` directory, and modify accordingly. The ``5ttgen`` script will automatically detect the presence of the new algorithm, and make it available at the command-line.
-

docs/reference/commands/tckgen.rst

@@ -43,6 +43,8 @@ Below is a list of available tracking algorithms, the input image data that they
 
 Note that the behaviour of the -angle option varies slightly depending on the order of integration: for any first-order method, this angle corresponds to the deviation in streamline trajectory per step; for higher-order methods, this corresponds to the change in underlying fibre orientation between the start and end points of each step.
 
+More information on the requisite data for option -act can be found at: https://mrtrix.readthedocs.io/en/3.0.8/quantitative_structural_connectivity/act.html
+
 Options
 -------