Python: Code formatting & documentation regeneration

- Some limited modification of code structure to be more faithful to C++ changes in #2818.
- Resolution of documentation changes occurring in #2678, particularly in its merge to dev following cmake adoption (#2689).

docs/reference/commands/5ttgen.rst

@@ -20,9 +20,9 @@ Usage
 Description
 -----------
 
-5ttgen acts as a 'master' script for generating a five-tissue-type (5TT) segmented tissue image suitable for use in Anatomically-Constrained Tractography (ACT). A range of different algorithms are available for completing this task. When using this script, the name of the algorithm to be used must appear as the first argument on the command-line after '5ttgen'. The subsequent compulsory arguments and options available depend on the particular algorithm being invoked.
+5ttgen acts as a "master" script for generating a five-tissue-type (5TT) segmented tissue image suitable for use in Anatomically-Constrained Tractography (ACT). A range of different algorithms are available for completing this task. When using this script, the name of the algorithm to be used must appear as the first argument on the command-line after "5ttgen". The subsequent compulsory arguments and options available depend on the particular algorithm being invoked.
 
-Each algorithm available also has its own help page, including necessary references; e.g. to see the help page of the 'fsl' algorithm, type '5ttgen fsl'.
+Each algorithm available also has its own help page, including necessary references; e.g. to see the help page of the "fsl" algorithm, type "5ttgen fsl".
 
 Options
 -------
@@ -107,13 +107,13 @@ Usage
 
     5ttgen freesurfer input output [ options ]
 
--  *input*: The input FreeSurfer parcellation image (any image containing 'aseg' in its name)
+-  *input*: The input FreeSurfer parcellation image (any image containing "aseg" in its name)
 -  *output*: The output 5TT image
 
 Options
 -------
 
-Options specific to the 'freesurfer' algorithm
+Options specific to the "freesurfer" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-lut file** Manually provide path to the lookup table on which the input parcellation image is based (e.g. FreeSurferColorLUT.txt)
@@ -204,7 +204,7 @@ Usage
 Options
 -------
 
-Options specific to the 'fsl' algorithm
+Options specific to the "fsl" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-t2 image** Provide a T2-weighted image in addition to the default T1-weighted image; this will be used as a second input to FSL FAST

docs/reference/commands/dwi2mask.rst

@@ -20,7 +20,7 @@ Usage
 Description
 -----------
 
-This script serves as an interface for many different algorithms that generate a binary mask from DWI data in different ways. Each algorithm available has its own help page, including necessary references; e.g. to see the help page of the 'fslbet' algorithm, type 'dwi2mask fslbet'.
+This script serves as an interface for many different algorithms that generate a binary mask from DWI data in different ways. Each algorithm available has its own help page, including necessary references; e.g. to see the help page of the "fslbet" algorithm, type "dwi2mask fslbet".
 
 More information on mask derivation from DWI data can be found at the following link: 
 https://mrtrix.readthedocs.io/en/3.0.4/dwi_preprocessing/masking.html
@@ -112,16 +112,16 @@ Usage
 Options
 -------
 
-Options specific to the 'afni_3dautomask' algorithm
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Options specific to the "3dautomask" algorithm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- **-clfrac** Set the 'clip level fraction', must be a number between 0.1 and 0.9. A small value means to make the initial threshold for clipping smaller, which will tend to make the mask larger.
+- **-clfrac** Set the "clip level fraction"; must be a number between 0.1 and 0.9. A small value means to make the initial threshold for clipping smaller, which will tend to make the mask larger.
 
-- **-nograd** The program uses a 'gradual' clip level by default. Add this option to use a fixed clip level.
+- **-nograd** The program uses a "gradual" clip level by default. Add this option to use a fixed clip level.
 
 - **-peels** Peel (erode) the mask n times, then unpeel (dilate).
 
-- **-nbhrs** Define the number of neighbors needed for a voxel NOT to be eroded.  It should be between 6 and 26.
+- **-nbhrs** Define the number of neighbors needed for a voxel NOT to be eroded. It should be between 6 and 26.
 
 - **-eclip** After creating the mask, remove exterior voxels below the clip threshold.
 
@@ -523,7 +523,7 @@ Usage
 Options
 -------
 
-Options specific to the 'fslbet' algorithm
+Options specific to the "fslbet" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-bet_f** Fractional intensity threshold (0->1); smaller values give larger brain outline estimates
@@ -622,7 +622,7 @@ Usage
 Options
 -------
 
-Options specific to the 'hdbet' algorithm
+Options specific to the "hdbet" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-nogpu** Do not attempt to run on the GPU
@@ -799,7 +799,7 @@ Usage
 Options
 -------
 
-Options specific to the 'mean' algorithm
+Options specific to the "mean" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-shells bvalues** Comma separated list of shells to be included in the volume averaging
@@ -904,7 +904,7 @@ Options specific to the "mtnorm" algorithm
 
 - **-init_mask image** Provide an initial brain mask, which will constrain the response function estimation (if omitted, the default dwi2mask algorithm will be used)
 
-- **-lmax values** The maximum spherical harmonic degree for the estimated FODs (see Description); defaults are "4,0,0" for multi-shell and "4,0" for single-shell data)
+- **-lmax values** The maximum spherical harmonic degree for the estimated FODs (see Description); defaults are "4,0,0" for multi-shell and "4,0" for single-shell data
 
 - **-threshold value** the threshold on the total tissue density sum image used to derive the brain mask; default is 0.5
 
@@ -1102,14 +1102,14 @@ Usage
 Options
 -------
 
-Options for turning 'dwi2mask trace' into an iterative algorithm
+Options for turning "dwi2mask trace" into an iterative algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-iterative** (EXPERIMENTAL) Iteratively refine the weights for combination of per-shell trace-weighted images prior to thresholding
 
 - **-max_iters** Set the maximum number of iterations for the algorithm (default: 10)
 
-Options specific to the 'trace' algorithm
+Options specific to the "trace" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-shells bvalues** Comma-separated list of shells used to generate trace-weighted images for masking

docs/reference/commands/dwi2response.rst

@@ -20,14 +20,15 @@ Usage
 Description
 -----------
 
-dwi2response offers different algorithms for performing various types of response function estimation. The name of the algorithm must appear as the first argument on the command-line after 'dwi2response'. The subsequent arguments and options depend on the particular algorithm being invoked.
+dwi2response offers different algorithms for performing various types of response function estimation. The name of the algorithm must appear as the first argument on the command-line after "dwi2response". The subsequent arguments and options depend on the particular algorithm being invoked.
 
-Each algorithm available has its own help page, including necessary references; e.g. to see the help page of the 'fa' algorithm, type 'dwi2response fa'.
+Each algorithm available has its own help page, including necessary references; e.g. to see the help page of the "fa" algorithm, type "dwi2response fa".
 
 More information on response function estimation for spherical deconvolution can be found at the following link: 
 https://mrtrix.readthedocs.io/en/3.0.4/constrained_spherical_deconvolution/response_function_estimation.html
 
-Note that if the -mask command-line option is not specified, the MRtrix3 command dwi2mask will automatically be called to derive an initial voxel exclusion mask. More information on mask derivation from DWI data can be found at: https://mrtrix.readthedocs.io/en/3.0.4/dwi_preprocessing/masking.html
+Note that if the -mask command-line option is not specified, the MRtrix3 command dwi2mask will automatically be called to derive an initial voxel exclusion mask. More information on mask derivation from DWI data can be found at: 
+https://mrtrix.readthedocs.io/en/3.0.4/dwi_preprocessing/masking.html
 
 Options
 -------
@@ -134,7 +135,7 @@ This is an improved version of the Dhollander et al. (2016) algorithm for unsupe
 Options
 -------
 
-Options for the 'dhollander' algorithm
+Options for the "dhollander" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-erode passes** Number of erosion passes to apply to initial (whole brain) mask. Set to 0 to not erode the brain mask. (default: 3)
@@ -248,7 +249,7 @@ Usage
 Options
 -------
 
-Options specific to the 'fa' algorithm
+Options specific to the "fa" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-erode passes** Number of brain mask erosion steps to apply prior to threshold (not used if mask is provided manually)
@@ -355,7 +356,7 @@ Usage
 Options
 -------
 
-Options specific to the 'manual' algorithm
+Options specific to the "manual" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-dirs image** Provide an input image that contains a pre-estimated fibre direction in each voxel (a tensor fit will be used otherwise)
@@ -458,7 +459,7 @@ Usage
 Options
 -------
 
-Options specific to the 'msmt_5tt' algorithm
+Options specific to the "msmt_5tt" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-dirs image** Provide an input image that contains a pre-estimated fibre direction in each voxel (a tensor fit will be used otherwise)
@@ -568,7 +569,7 @@ Usage
 Options
 -------
 
-Options specific to the 'tax' algorithm
+Options specific to the "tax" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-peak_ratio value** Second-to-first-peak amplitude ratio threshold
@@ -674,7 +675,7 @@ Usage
 Options
 -------
 
-Options specific to the 'tournier' algorithm
+Options specific to the "tournier" algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - **-number voxels** Number of single-fibre voxels to use when calculating response function

docs/reference/commands/dwibiascorrect.rst

@@ -204,7 +204,7 @@ dwibiascorrect fsl
 Synopsis
 --------
 
-Perform DWI bias field correction using the 'fast' command as provided in FSL
+Perform DWI bias field correction using the "fast" command as provided in FSL
 
 Usage
 -----
@@ -219,7 +219,7 @@ Usage
 Description
 -----------
 
-The FSL 'fast' command only estimates the bias field within a brain mask, and cannot extrapolate this smoothly-varying field beyond the defined mask. As such, this algorithm by necessity introduces a hard masking of the input DWI. Since this attribute may interfere with the purpose of using the command (e.g. correction of a bias field is commonly used to improve brain mask estimation), use of this particular algorithm is generally not recommended.
+The FSL "fast" command only estimates the bias field within a brain mask, and cannot extrapolate this smoothly-varying field beyond the defined mask. As such, this algorithm by necessity introduces a hard masking of the input DWI. Since this attribute may interfere with the purpose of using the command (e.g. correction of a bias field is commonly used to improve brain mask estimation), use of this particular algorithm is generally not recommended.
 
 Options
 -------

docs/reference/commands/dwibiasnormmask.rst

@@ -26,13 +26,13 @@ DWI bias field correction, intensity normalisation and masking are inter-related
 
 The operation of the algorithm is as follows. An initial mask is defined, either using the default dwi2mask algorithm or as provided by the user. Based on this mask, a sequence of response function estimation, multi-shell multi-tissue CSD, bias field correction (using the mtnormalise command), and intensity normalisation is performed. The default dwi2mask algorithm is then re-executed on the bias-field-corrected DWI series. This sequence of steps is then repeated based on the revised mask, until either a convergence criterion or some number of maximum iterations is reached.
 
-The MRtrix3 mtnormalise command is used to estimate information relating to bias field and intensity normalisation. However its usage in this context is different to its conventional usage. Firstly, while the corrected ODF images are typically used directly following invocation of this command, here the estimated bias field and scaling factors are instead used to apply the relevant corrections to the originating DWI data. Secondly, the global intensity scaling that is calculated and applied is typically based on achieving close to a unity sum of tissue signal fractions throughout the masked region. Here, it is instead the b=0 signal in CSF that forms the reference for this global intensity scaling; this is calculated based on the estimated CSF response function and the tissue-specific intensity scaling (this is calculated internally by mtnormalise as part of its optimisation process, but typically subsequently discarded in favour of a single scaling factor for all tissues)
+The MRtrix3 mtnormalise command is used to estimate information relating to bias field and intensity normalisation. However its usage in this context is different to its conventional usage. Firstly, while the corrected ODF images are typically used directly following invocation of this command here the estimated bias field and scaling factors are instead used to apply the relevant corrections to the originating DWI data. Secondly, the global intensity scaling that is calculated and applied is typically based on achieving close to a unity sum of tissue signal fractions throughout the masked region. Here, it is instead the b=0 signal in CSF that forms the reference for this global intensity scaling; this is calculated based on the estimated CSF response function and the tissue-specific intensity scaling (this is calculated internally by mtnormalise as part of its optimisation process, but typically subsequently discarded in favour of a single scaling factor for all tissues)
 
 The ODFs estimated within this optimisation procedure are by default of lower maximal spherical harmonic degree than what would be advised for analysis. This is done for computational efficiency. This behaviour can be modified through the -lmax command-line option.
 
 By default, the optimisation procedure will terminate after only two iterations. This is done because it has been observed for some data / configurations that additional iterations can lead to unstable divergence and erroneous results for bias field estimation and masking. For other configurations, it may be preferable to use a greater number of iterations, and allow the iterative algorithm to converge to a stable solution. This can be controlled via the -max_iters command-line option.
 
-Within the optimisation algorithm, derivation of the mask may potentially be performed differently to a conventional mask derivation that is based on a DWI series (where, in many instances, it is actually only the mean b=0 image that is used). Here, the image corresponding to the sum of tissue signal fractions following spherical deconvolution / bias field correction / intensity normalisation is also available, and this can potentially be used for mask derivation. Available options are as follows. "dwi2mask": Use the MRtrix3 command dwi2mask on the bias-field-corrected DWI series (ie. do not use the ODF tissue sum image for mask derivation); the algorithm to be invoked can be controlled by the user via the MRtrix config file entry "Dwi2maskAlgorithm". "fslbet": Invoke the FSL command "bet" on the ODF tissue sum image. "hdbet": Invoke the HD-BET command on the ODF tissue sum image. "mrthreshold": Invoke the MRtrix3 command "mrthreshold" on the ODF tissue sum image, where an appropriate threshold value will be determined automatically (and some heuristic cleanup of the resulting mask will be performed). "synthstrip": Invoke the FreeSurfer SynthStrip method on the ODF tissue sum image. "threshold": Apply a fixed partial volume threshold of 0.5 to the ODF tissue sum image  (and some heuristic cleanup of the resulting mask will be performed).
+Within the optimisation algorithm, derivation of the mask may potentially be performed differently to a conventional mask derivation that is based on a DWI series (where, in many instances, it is actually only the mean b=0 image that is used). Here, the image corresponding to the sum of tissue signal fractions following spherical deconvolution / bias field correction / intensity normalisation is also available,  and this can potentially be used for mask derivation. Available options are as follows. "dwi2mask": Use the MRtrix3 command dwi2mask on the bias-field-corrected DWI series (ie. do not use the ODF tissue sum image for mask derivation); the algorithm to be invoked can be controlled by the user via the MRtrix config file entry "Dwi2maskAlgorithm". "fslbet": Invoke the FSL command "bet" on the ODF tissue sum image. "hdbet": Invoke the HD-BET command on the ODF tissue sum image. "mrthreshold": Invoke the MRtrix3 command "mrthreshold" on the ODF tissue sum image, where an appropriate threshold value will be determined automatically (and some heuristic cleanup of the resulting mask will be performed). "synthstrip": Invoke the FreeSurfer SynthStrip method on the ODF tissue sum image. "threshold": Apply a fixed partial volume threshold of 0.5 to the ODF tissue sum image (and some heuristic cleanup of the resulting mask will be performed).
 
 Options
 -------
@@ -47,24 +47,24 @@ Options for importing the diffusion gradient table
 Options relevant to the internal optimisation procedure
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- **-dice value** Set the Dice coefficient threshold for similarity of masks between sequential iterations that will result in termination due to convergence; default = 0.999
+- **-dice value** Set the Dice coefficient threshold for similarity of masks between sequential iterations  that will result in termination due to convergence; default = 0.999
 
-- **-init_mask image** Provide an initial mask for the first iteration of the algorithm (if not provided, the default dwi2mask algorithm will be used)
+- **-init_mask** Provide an initial mask for the first iteration of the algorithm (if not provided, the default dwi2mask algorithm will be used)
 
 - **-max_iters count** The maximum number of iterations (see Description); default is 2; set to 0 to proceed until convergence
 
 - **-mask_algo algorithm** The algorithm to use for mask estimation, potentially based on the ODF sum image (see Description); default: threshold
 
-- **-lmax values** The maximum spherical harmonic degree for the estimated FODs (see Description); defaults are "4,0,0" for multi-shell and "4,0" for single-shell data)
+- **-lmax values** The maximum spherical harmonic degree for the estimated FODs (see Description); defaults are "4,0,0" for multi-shell  and "4,0" for single-shell data)
 
 Options that modulate the outputs of the script
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- **-output_bias image** Export the final estimated bias field to an image
+- **-output_bias** Export the final estimated bias field to an image
 
-- **-output_scale file** Write the scaling factor applied to the DWI series to a text file
+- **-output_scale** Write the scaling factor applied to the DWI series to a text file
 
-- **-output_tissuesum image** Export the tissue sum image that was used to generate the final mask
+- **-output_tissuesum** Export the tissue sum image that was used to generate the final mask
 
 - **-reference value** Set the target CSF b=0 intensity in the output DWI series (default: 1000.0)