From a483d00d99ef31933751e662672b5548fccadc6f Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Wed, 28 Feb 2024 17:00:28 +1100 Subject: [PATCH] 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 | 10 +- docs/reference/commands/dwi2mask.rst | 24 +- docs/reference/commands/dwi2response.rst | 19 +- docs/reference/commands/dwibiascorrect.rst | 4 +- docs/reference/commands/dwibiasnormmask.rst | 16 +- docs/reference/commands/dwifslpreproc.rst | 13 +- docs/reference/commands/dwishellmath.rst | 2 +- docs/reference/commands/for_each.rst | 4 +- .../commands/population_template.rst | 24 +- docs/reference/commands/responsemean.rst | 21 +- python/bin/5ttgen | 21 +- python/bin/dwi2mask | 12 +- python/bin/dwi2response | 19 +- python/bin/dwibiasnormmask | 139 +++++---- python/bin/dwicat | 17 +- python/bin/dwifslpreproc | 248 ++++++++++------- python/bin/dwigradcheck | 8 +- python/bin/dwinormalise | 13 +- python/bin/dwishellmath | 14 +- python/bin/for_each | 112 ++++---- python/bin/labelsgmfix | 8 +- python/bin/mask2glass | 29 +- python/bin/mrtrix_cleanup | 30 +- python/bin/population_template | 263 ++++++++++-------- python/bin/responsemean | 24 +- python/lib/mrtrix3/dwi2mask/b02template.py | 9 +- python/lib/mrtrix3/dwi2mask/consensus.py | 6 +- python/lib/mrtrix3/dwi2mask/mtnorm.py | 7 +- python/lib/mrtrix3/dwi2mask/trace.py | 4 +- python/lib/mrtrix3/dwi2response/dhollander.py | 11 +- python/lib/mrtrix3/dwi2response/tax.py | 3 +- python/lib/mrtrix3/dwi2response/tournier.py | 3 +- python/lib/mrtrix3/dwibiascorrect/ants.py | 3 +- python/lib/mrtrix3/dwibiascorrect/mtnorm.py | 4 +- python/lib/mrtrix3/dwinormalise/mtnorm.py | 4 +- 35 files changed, 653 insertions(+), 495 deletions(-) diff --git a/docs/reference/commands/5ttgen.rst b/docs/reference/commands/5ttgen.rst index 45e15bd715..83bbf1829a 100644 --- a/docs/reference/commands/5ttgen.rst +++ b/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 diff --git a/docs/reference/commands/dwi2mask.rst b/docs/reference/commands/dwi2mask.rst index 6ef9814a03..6325cd6270 100644 --- a/docs/reference/commands/dwi2mask.rst +++ b/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 diff --git a/docs/reference/commands/dwi2response.rst b/docs/reference/commands/dwi2response.rst index dfc28d4d11..ce15f18d44 100644 --- a/docs/reference/commands/dwi2response.rst +++ b/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 diff --git a/docs/reference/commands/dwibiascorrect.rst b/docs/reference/commands/dwibiascorrect.rst index d2ec382651..0cba332966 100644 --- a/docs/reference/commands/dwibiascorrect.rst +++ b/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 ------- diff --git a/docs/reference/commands/dwibiasnormmask.rst b/docs/reference/commands/dwibiasnormmask.rst index c8ffd5b80e..7016a43c59 100644 --- a/docs/reference/commands/dwibiasnormmask.rst +++ b/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) diff --git a/docs/reference/commands/dwifslpreproc.rst b/docs/reference/commands/dwifslpreproc.rst index d0c3a02faf..81927c4f0a 100644 --- a/docs/reference/commands/dwifslpreproc.rst +++ b/docs/reference/commands/dwifslpreproc.rst @@ -26,13 +26,16 @@ This script is intended to provide convenience of use of the FSL software tools More information on use of the dwifslpreproc command can be found at the following link: https://mrtrix.readthedocs.io/en/3.0.4/dwi_preprocessing/dwifslpreproc.html -Note that the MRtrix3 command dwi2mask will automatically be called to derive a processing mask for the FSL command "eddy", which determines which voxels contribute to the estimation of geometric distortion parameters and possibly also the classification of outlier slices. If FSL command "topup" is used to estimate a susceptibility field, then dwi2mask will be executed on the resuts of running FSL command "applytopup" to the input DWIs; otherwise it will be executed directly on the input DWIs. Alternatively, the -eddy_mask option can be specified in order to manually provide such a processing 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 the MRtrix3 command dwi2mask will automatically be called to derive a processing mask for the FSL command "eddy", which determines which voxels contribute to the estimation of geometric distortion parameters and possibly also the classification of outlier slices. If FSL command "topup" is used to estimate a susceptibility field, then dwi2mask will be executed on the resuts of running FSL command "applytopup" to the input DWIs; otherwise it will be executed directly on the input DWIs. Alternatively, the -eddy_mask option can be specified in order to manually provide such a processing 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 -The "-topup_options" and "-eddy_options" command-line options allow the user to pass desired command-line options directly to the FSL commands topup and eddy. The available options for those commands may vary between versions of FSL; users can interrogate such by querying the help pages of the installed software, and/or the FSL online documentation: (topup) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide ; (eddy) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide +The "-topup_options" and "-eddy_options" command-line options allow the user to pass desired command-line options directly to the FSL commands topup and eddy. The available options for those commands may vary between versions of FSL; users can interrogate such by querying the help pages of the installed software, and/or the FSL online documentation: +(topup) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide ; +(eddy) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide The script will attempt to run the CUDA version of eddy; if this does not succeed for any reason, or is not present on the system, the CPU version will be attempted instead. By default, the CUDA eddy binary found that indicates compilation against the most recent version of CUDA will be attempted; this can be over-ridden by providing a soft-link "eddy_cuda" within your path that links to the binary you wish to be executed. -Note that this script does not perform any explicit registration between images provided to topup via the -se_epi option, and the DWI volumes provided to eddy. In some instances (motion between acquisitions) this can result in erroneous application of the inhomogeneity field during distortion correction. Use of the -align_seepi option is advocated in this scenario, which ensures that the first volume in the series provided to topup is also the first volume in the series provided to eddy, guaranteeing alignment. But a prerequisite for this approach is that the image contrast within the images provided to the -se_epi option must match the b=0 volumes present within the input DWI series: this means equivalent TE, TR and flip angle (note that differences in multi-band factors between two acquisitions may lead to differences in TR). +Note that this script does not perform any explicit registration between images provided to topup via the -se_epi option, and the DWI volumes provided to eddy. In some instances (motion between acquisitions) this can result in erroneous application of the inhomogeneity field during distortion correction. Use of the -align_seepi option is advocated in this scenario, which ensures that the first volume in the series provided to topup is also the first volume in the series provided to eddy, guaranteeing alignment. But a prerequisite for this approach is that the image contrast within the images provided to the -se_epi option must match the b=0 volumes present within the input DWI series: this means equivalent TE, TR and flip angle (note that differences in multi-band factors between two acquisitions may lead to differences in TR). Example usages -------------- @@ -59,7 +62,7 @@ Example usages $ mrcat DWI_*.mif DWI_all.mif -axis 3; mrcat b0_*.mif b0_all.mif -axis 3; dwifslpreproc DWI_all.mif DWI_out.mif -rpe_header -se_epi b0_all.mif -align_seepi - With this usage, the relevant phase encoding information is determined entirely based on the contents of the relevant image headers, and dwifslpreproc prepares all metadata for the executed FSL commands accordingly. This can therefore be used if the particular DWI acquisition strategy used does not correspond to one of the simple examples as described in the prior examples. This usage is predicated on the headers of the input files containing appropriately-named key-value fields such that MRtrix3 tools identify them as such. In some cases, conversion from DICOM using MRtrix3 commands will automatically extract and embed this information; however this is not true for all scanner vendors and/or software versions. In the latter case it may be possible to manually provide these metadata; either using the -json_import command-line option of dwifslpreproc, or the -json_import or one of the -import_pe_* command-line options of MRtrix3's mrconvert command (and saving in .mif format) prior to running dwifslpreproc. + With this usage, the relevant phase encoding information is determined entirely based on the contents of the relevant image headers, and dwifslpreproc prepares all metadata for the executed FSL commands accordingly. This can therefore be used if the particular DWI acquisition strategy used does not correspond to one of the simple examples as described in the prior examples. This usage is predicated on the headers of the input files containing appropriately-named key-value fields such that MRtrix3 tools identify them as such. In some cases, conversion from DICOM using MRtrix3 commands will automatically extract and embed this information; however this is not true for all scanner vendors and/or software versions. In the latter case it may be possible to manually provide these metadata; either using the -json_import command-line option of dwifslpreproc, or the -json_import or one of the -import_pe_* command-line options of MRtrix3's mrconvert command (and saving in .mif format) prior to running dwifslpreproc. Options ------- @@ -112,7 +115,7 @@ Options for achieving correction of susceptibility distortions - **-se_epi image** Provide an additional image series consisting of spin-echo EPI images, which is to be used exclusively by topup for estimating the inhomogeneity field (i.e. it will not form part of the output image series) -- **-align_seepi** Achieve alignment between the SE-EPI images used for inhomogeneity field estimation, and the DWIs (more information in Description section) +- **-align_seepi** Achieve alignment between the SE-EPI images used for inhomogeneity field estimation and the DWIs (more information in Description section) - **-topup_options " TopupOptions"** Manually provide additional command-line options to the topup command (provide a string within quotation marks that contains at least one space, even if only passing a single command-line option to topup) diff --git a/docs/reference/commands/dwishellmath.rst b/docs/reference/commands/dwishellmath.rst index 4c6611b63f..005820818b 100644 --- a/docs/reference/commands/dwishellmath.rst +++ b/docs/reference/commands/dwishellmath.rst @@ -22,7 +22,7 @@ Usage Description ----------- -The output of this command is a 4D image, where each volume corresponds to a b-value shell (in order of increasing b-value), and the intensities within each volume correspond to the chosen statistic having been computed from across the DWI volumes belonging to that b-value shell. +The output of this command is a 4D image, where each volume corresponds to a b-value shell (in order of increasing b-value), an the intensities within each volume correspond to the chosen statistic having been computed from across the DWI volumes belonging to that b-value shell. Example usages -------------- diff --git a/docs/reference/commands/for_each.rst b/docs/reference/commands/for_each.rst index c1375d0395..b09948c876 100644 --- a/docs/reference/commands/for_each.rst +++ b/docs/reference/commands/for_each.rst @@ -48,13 +48,13 @@ Example usages $ for_each folder/*.mif : mrinfo IN - This will run the "mrinfo" command for every .mif file present in "folder/". Note that the compulsory colon symbol is used to separate the list of items on which for_each is being instructed to operate, from the command that is intended to be run for each input. + This will run the "mrinfo" command for every .mif file present in "folder/". Note that the compulsory colon symbol is used to separate the list of items on which for_each is being instructed to operate from the command that is intended to be run for each input. - *Multi-threaded use of for_each*:: $ for_each -nthreads 4 freesurfer/subjects/* : recon-all -subjid NAME -all - In this example, for_each is instructed to run the FreeSurfer command 'recon-all' for all subjects within the 'subjects' directory, with four subjects being processed in parallel at any one time. Whenever processing of one subject is completed, processing for a new unprocessed subject will commence. This technique is useful for improving the efficiency of running single-threaded commands on multi-core systems, as long as the system possesses enough memory to support such parallel processing. Note that in the case of multi-threaded commands (which includes many MRtrix3 commands), it is generally preferable to permit multi-threaded execution of the command on a single input at a time, rather than processing multiple inputs in parallel. + In this example, for_each is instructed to run the FreeSurfer command "recon-all" for all subjects within the "subjects" directory, with four subjects being processed in parallel at any one time. Whenever processing of one subject is completed, processing for a new unprocessed subject will commence. This technique is useful for improving the efficiency of running single-threaded commands on multi-core systems, as long as the system possesses enough memory to support such parallel processing. Note that in the case of multi-threaded commands (which includes many MRtrix3 commands), it is generally preferable to permit multi-threaded execution of the command on a single input at a time, rather than processing multiple inputs in parallel. - *Excluding specific inputs from execution*:: diff --git a/docs/reference/commands/population_template.rst b/docs/reference/commands/population_template.rst index e9b64da171..9e38019957 100644 --- a/docs/reference/commands/population_template.rst +++ b/docs/reference/commands/population_template.rst @@ -38,17 +38,17 @@ Options Input, output and general options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- **-type** Specify the types of registration stages to perform. Options are "rigid" (perform rigid registration only which might be useful for intra-subject registration in longitudinal analysis), "affine" (perform affine registration) and "nonlinear" as well as cominations of registration types: "rigid_affine", "rigid_nonlinear", "affine_nonlinear", "rigid_affine_nonlinear". Default: rigid_affine_nonlinear +- **-type** Specify the types of registration stages to perform. Options are: "rigid" (perform rigid registration only, which might be useful for intra-subject registration in longitudinal analysis); "affine" (perform affine registration); "nonlinear"; as well as cominations of registration types: "rigid_affine", "rigid_nonlinear", "affine_nonlinear", "rigid_affine_nonlinear". Default: rigid_affine_nonlinear - **-voxel_size** Define the template voxel size in mm. Use either a single value for isotropic voxels or 3 comma-separated values. -- **-initial_alignment** Method of alignment to form the initial template. Options are "mass" (default), "robust_mass" (requires masks), "geometric" and "none". +- **-initial_alignment** Method of alignment to form the initial template.Options are: "mass" (default); "robust_mass" (requires masks); "geometric"; "none". - **-mask_dir** Optionally input a set of masks inside a single directory, one per input image (with the same file name prefix). Using masks will speed up registration significantly. Note that masks are used for registration, not for aggregation. To exclude areas from aggregation, NaN-mask your input images. - **-warp_dir** Output a directory containing warps from each input to the template. If the folder does not exist it will be created -- **-transformed_dir** Output a directory containing the input images transformed to the template. If the folder does not exist it will be created. For multi-contrast registration, provide comma separated list of directories. +- **-transformed_dir** Output a directory containing the input images transformed to the template. If the folder does not exist it will be created. For multi-contrast registration, this path will contain a sub-directory for the images per contrast. - **-linear_transformations_dir** Output a directory containing the linear transformations used to generate the template. If the folder does not exist it will be created @@ -56,7 +56,7 @@ Input, output and general options - **-noreorientation** Turn off FOD reorientation in mrregister. Reorientation is on by default if the number of volumes in the 4th dimension corresponds to the number of coefficients in an antipodally symmetric spherical harmonic series (i.e. 6, 15, 28, 45, 66 etc) -- **-leave_one_out** Register each input image to a template that does not contain that image. Valid choices: 0, 1, auto. (Default: auto (true if n_subjects larger than 2 and smaller than 15)) +- **-leave_one_out** Register each input image to a template that does not contain that image. Valid choices: 0, 1, auto. (Default: auto (true if n_subjects larger than 2 and smaller than 15)) - **-aggregate** Measure used to aggregate information from transformed images to the template image. Valid choices: mean, median. Default: mean @@ -71,7 +71,7 @@ Input, output and general options Options for the non-linear registration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- **-nl_scale** Specify the multi-resolution pyramid used to build the non-linear template, in the form of a list of scale factors (default: 0.3,0.4,0.5,0.6,0.7,0.8,0.9,1.0,1.0,1.0,1.0,1.0,1.0,1.0,1.0,1.0). This implicitly defines the number of template levels +- **-nl_scale** Specify the multi-resolution pyramid used to build the non-linear template, in the form of a list of scale factors (default: 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0). This implicitly defines the number of template levels - **-nl_lmax** Specify the lmax used for non-linear registration for each scale factor, in the form of a list of integers (default: 2,2,2,2,2,2,2,2,4,4,4,4,4,4,4,4). The list must be the same length as the nl_scale factor list @@ -96,24 +96,24 @@ Options for the linear registration - **-rigid_lmax** Specify the lmax used for rigid registration for each scale factor, in the form of a list of integers (default: 2,2,2,4,4,4). The list must be the same length as the linear_scale factor list -- **-rigid_niter** Specify the number of registration iterations used within each level before updating the template, in the form of a list of integers (default:50 for each scale). This must be a single number or a list of same length as the linear_scale factor list +- **-rigid_niter** Specify the number of registration iterations used within each level before updating the template, in the form of a list of integers (default: 50 for each scale). This must be a single number or a list of same length as the linear_scale factor list - **-affine_scale** Specify the multi-resolution pyramid used to build the affine template, in the form of a list of scale factors (default: 0.3,0.4,0.6,0.8,1.0,1.0). This and rigid_scale implicitly define the number of template levels - **-affine_lmax** Specify the lmax used for affine registration for each scale factor, in the form of a list of integers (default: 2,2,2,4,4,4). The list must be the same length as the linear_scale factor list -- **-affine_niter** Specify the number of registration iterations used within each level before updating the template, in the form of a list of integers (default:500 for each scale). This must be a single number or a list of same length as the linear_scale factor list +- **-affine_niter** Specify the number of registration iterations used within each level before updating the template, in the form of a list of integers (default: 500 for each scale). This must be a single number or a list of same length as the linear_scale factor list Multi-contrast options ^^^^^^^^^^^^^^^^^^^^^^ -- **-mc_weight_initial_alignment** Weight contribution of each contrast to the initial alignment. Comma separated, default: 1.0 +- **-mc_weight_initial_alignment** Weight contribution of each contrast to the initial alignment. Comma separated, default: 1.0 for each contrast (ie. equal weighting). -- **-mc_weight_rigid** Weight contribution of each contrast to the objective of rigid registration. Comma separated, default: 1.0 +- **-mc_weight_rigid** Weight contribution of each contrast to the objective of rigid registration. Comma separated, default: 1.0 for each contrast (ie. equal weighting) -- **-mc_weight_affine** Weight contribution of each contrast to the objective of affine registration. Comma separated, default: 1.0 +- **-mc_weight_affine** Weight contribution of each contrast to the objective of affine registration. Comma separated, default: 1.0 for each contrast (ie. equal weighting) -- **-mc_weight_nl** Weight contribution of each contrast to the objective of nonlinear registration. Comma separated, default: 1.0 +- **-mc_weight_nl** Weight contribution of each contrast to the objective of nonlinear registration. Comma separated, default: 1.0 for each contrast (ie. equal weighting) Additional standard options for Python scripts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -152,7 +152,7 @@ Tournier, J.-D.; Smith, R. E.; Raffelt, D.; Tabbara, R.; Dhollander, T.; Pietsch -**Author:** David Raffelt (david.raffelt@florey.edu.au) & Max Pietsch (maximilian.pietsch@kcl.ac.uk) & Thijs Dhollander (thijs.dhollander@gmail.com) +**Author:** David Raffelt (david.raffelt@florey.edu.au) and Max Pietsch (maximilian.pietsch@kcl.ac.uk) and Thijs Dhollander (thijs.dhollander@gmail.com) **Copyright:** Copyright (c) 2008-2024 the MRtrix3 contributors. diff --git a/docs/reference/commands/responsemean.rst b/docs/reference/commands/responsemean.rst index 1036ea8272..3d5663cbfb 100644 --- a/docs/reference/commands/responsemean.rst +++ b/docs/reference/commands/responsemean.rst @@ -21,16 +21,29 @@ Usage Description ----------- -Example usage: responsemean input_response1.txt input_response2.txt input_response3.txt ... output_average_response.txt - All response function files provided must contain the same number of unique b-values (lines), as well as the same number of coefficients per line. -As long as the number of unique b-values is identical across all input files, the coefficients will be averaged. This is performed on the assumption that the actual acquired b-values are identical. This is however impossible for the responsemean command to determine based on the data provided; it is therefore up to the user to ensure that this requirement is satisfied. +As long as the number of unique b-values is identical across all input files, the response functions will be averaged. This is performed on the assumption that the actual acquired b-values are identical. This is however impossible for the responsemean command to determine based on the data provided; it is therefore up to the user to ensure that this requirement is satisfied. + +Example usages +-------------- + +- *Usage where all response functions are in the same directory:*:: + + $ responsemean input_response1.txt input_response2.txt input_response3.txt output_average_response.txt + +- *Usage selecting response functions within a directory using a wildcard:*:: + + $ responsemean input_response*.txt output_average_response.txt + +- *Usage where data for each participant reside in a participant-specific directory:*:: + + $ responsemean subject-*/response.txt output_average_response.txt Options ------- -- **-legacy** Use the legacy behaviour of former command 'average_response': average response function coefficients directly, without compensating for global magnitude differences between input files +- **-legacy** Use the legacy behaviour of former command "average_response": average response function coefficients directly, without compensating for global magnitude differences between input files Additional standard options for Python scripts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/python/bin/5ttgen b/python/bin/5ttgen index ccb5522d56..8e5d962899 100755 --- a/python/bin/5ttgen +++ b/python/bin/5ttgen @@ -23,14 +23,21 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Generate a 5TT image suitable for ACT') cmdline.add_citation('Smith, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. ' - 'Anatomically-constrained tractography: Improved diffusion MRI streamlines tractography through effective use of anatomical information. ' + 'Anatomically-constrained tractography:' + ' Improved diffusion MRI streamlines tractography through effective use of anatomical information. ' 'NeuroImage, 2012, 62, 1924-1938') - cmdline.add_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.') - cmdline.add_description('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".') + cmdline.add_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.') + cmdline.add_description('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".') common_options = cmdline.add_argument_group('Options common to all 5ttgen algorithms') common_options.add_argument('-nocrop', diff --git a/python/bin/dwi2mask b/python/bin/dwi2mask index a1b11031aa..ab805cc103 100755 --- a/python/bin/dwi2mask +++ b/python/bin/dwi2mask @@ -20,11 +20,15 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import algorithm, app, _version #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au) and Warda Syeda (wtsyeda@unimelb.edu.au)') + cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and Warda Syeda (wtsyeda@unimelb.edu.au)') cmdline.set_synopsis('Generate a binary mask from DWI data') - cmdline.add_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".') + cmdline.add_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".') cmdline.add_description('More information on mask derivation from DWI data can be found at the following link: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/dwi_preprocessing/masking.html') diff --git a/python/bin/dwi2response b/python/bin/dwi2response index 8c8e8687d6..c1e1a5f53e 100755 --- a/python/bin/dwi2response +++ b/python/bin/dwi2response @@ -20,18 +20,23 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import algorithm, app, _version #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au) and Thijs Dhollander (thijs.dhollander@gmail.com)') + cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and Thijs Dhollander (thijs.dhollander@gmail.com)') cmdline.set_synopsis('Estimate response function(s) for spherical deconvolution') cmdline.add_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.') - cmdline.add_description('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".') - cmdline.add_description('More information on response function estimation for spherical deconvolution can be found at the following link: \n' + cmdline.add_description('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".') + cmdline.add_description('More information on response function estimation for spherical deconvolution' + ' can be found at the following link: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/constrained_spherical_deconvolution/response_function_estimation.html') - cmdline.add_description('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: ' + cmdline.add_description('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: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/dwi_preprocessing/masking.html') # General options diff --git a/python/bin/dwibiasnormmask b/python/bin/dwibiasnormmask index 3559c2aecf..e5c4e91dc6 100755 --- a/python/bin/dwibiasnormmask +++ b/python/bin/dwibiasnormmask @@ -27,50 +27,70 @@ DICE_COEFF_DEFAULT = 1.0 - 1e-3 def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au) and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') + cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') cmdline.set_synopsis('Perform a combination of bias field correction, intensity normalisation, and mask derivation, for DWI data') - cmdline.add_description('DWI bias field correction, intensity normalisation and masking are inter-related steps, and errors ' - 'in each may influence other steps. This script is designed to perform all of these steps in an integrated ' - 'iterative fashion, with the intention of making all steps more robust.') - cmdline.add_description('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.') - cmdline.add_description('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)') - cmdline.add_description('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.') - cmdline.add_description('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.') - cmdline.add_description('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 ' + cmdline.add_description('DWI bias field correction,' + ' intensity normalisation and masking are inter-related steps,' + ' and errors in each may influence other steps.' + ' This script is designed to perform all of these steps in an integrated iterative fashion,' + ' with the intention of making all steps more robust.') + cmdline.add_description('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.') + cmdline.add_description('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)') + cmdline.add_description('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.') + cmdline.add_description('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.') + cmdline.add_description('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).') cmdline.add_citation('Jeurissen, B; Tournier, J-D; Dhollander, T; Connelly, A & Sijbers, J. ' 'Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data. ' @@ -96,47 +116,54 @@ def usage(cmdline): #pylint: disable=unused-variable output_options = cmdline.add_argument_group('Options that modulate the outputs of the script') output_options.add_argument('-output_bias', type=app.Parser.ImageOut(), + metavar='image', help='Export the final estimated bias field to an image') output_options.add_argument('-output_scale', type=app.Parser.FileOut(), + metavar='file', help='Write the scaling factor applied to the DWI series to a text file') output_options.add_argument('-output_tissuesum', type=app.Parser.ImageOut(), + metavar='image', help='Export the tissue sum image that was used to generate the final mask') output_options.add_argument('-reference', type=app.Parser.Float(0.0), metavar='value', default=REFERENCE_INTENSITY, - help=f'Set the target CSF b=0 intensity in the output DWI series (default: {REFERENCE_INTENSITY})') + help='Set the target CSF b=0 intensity in the output DWI series' + f' (default: {REFERENCE_INTENSITY})') internal_options = cmdline.add_argument_group('Options relevant to the internal optimisation procedure') internal_options.add_argument('-dice', type=app.Parser.Float(0.0, 1.0), default=DICE_COEFF_DEFAULT, metavar='value', - help=f'Set the Dice coefficient threshold for similarity of masks between sequential iterations that will ' - f'result in termination due to convergence; default = {DICE_COEFF_DEFAULT}') + help='Set the Dice coefficient threshold for similarity of masks between sequential iterations' + ' that will result in termination due to convergence;' + f' default = {DICE_COEFF_DEFAULT}') internal_options.add_argument('-init_mask', type=app.Parser.ImageIn(), - help='Provide an initial mask for the first iteration of the algorithm ' - '(if not provided, the default dwi2mask algorithm will be used)') + metavar='image', + help='Provide an initial mask for the first iteration of the algorithm' + ' (if not provided, the default dwi2mask algorithm will be used)') internal_options.add_argument('-max_iters', type=app.Parser.Int(0), default=DWIBIASCORRECT_MAX_ITERS, metavar='count', - help=f'The maximum number of iterations (see Description); default is {DWIBIASCORRECT_MAX_ITERS}; ' - f'set to 0 to proceed until convergence') + help='The maximum number of iterations (see Description);' + f' default is {DWIBIASCORRECT_MAX_ITERS};' + ' set to 0 to proceed until convergence') internal_options.add_argument('-mask_algo', choices=MASK_ALGOS, metavar='algorithm', - help=f'The algorithm to use for mask estimation, ' - f'potentially based on the ODF sum image (see Description); ' - f'default: {MASK_ALGO_DEFAULT}') + help='The algorithm to use for mask estimation,' + ' potentially based on the ODF sum image (see Description);' + f' default: {MASK_ALGO_DEFAULT}') internal_options.add_argument('-lmax', metavar='values', type=app.Parser.SequenceInt(), - help='The maximum spherical harmonic degree for the estimated FODs (see Description); ' - f'defaults are "{",".join(map(str, LMAXES_MULTI))}" for multi-shell ' - f'and "{",".join(map(str, LMAXES_SINGLE))}" for single-shell data)') + help='The maximum spherical harmonic degree for the estimated FODs (see Description);' + f' defaults are "{",".join(map(str, LMAXES_MULTI))}" for multi-shell ' + f' and "{",".join(map(str, LMAXES_SINGLE))}" for single-shell data)') app.add_dwgrad_import_options(cmdline) diff --git a/python/bin/dwicat b/python/bin/dwicat index e7ede9a896..810fe14ead 100755 --- a/python/bin/dwicat +++ b/python/bin/dwicat @@ -24,15 +24,16 @@ import json, shutil def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Lena Dorfschmidt (ld548@cam.ac.uk) ' - 'and Jakub Vohryzek (jakub.vohryzek@queens.ox.ac.uk) ' - 'and Robert E. Smith (robert.smith@florey.edu.au)') + cmdline.set_author('Lena Dorfschmidt (ld548@cam.ac.uk)' + ' and Jakub Vohryzek (jakub.vohryzek@queens.ox.ac.uk)' + ' and Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Concatenating multiple DWI series accounting for differential intensity scaling') - cmdline.add_description('This script concatenates two or more 4D DWI series, accounting for the ' - 'fact that there may be differences in intensity scaling between those series. ' - 'This intensity scaling is corrected by determining scaling factors that will ' - 'make the overall image intensities in the b=0 volumes of each series approximately ' - 'equivalent.') + cmdline.add_description('This script concatenates two or more 4D DWI series,' + ' accounting for the fact that there may be differences in' + ' intensity scaling between those series.' + ' This intensity scaling is corrected by determining scaling factors' + ' that will make the overall image intensities in the b=0 volumes' + ' of each series approximately equivalent.') cmdline.add_argument('inputs', nargs='+', type=app.Parser.ImageIn(), diff --git a/python/bin/dwifslpreproc b/python/bin/dwifslpreproc index 313c4ed385..fd90aa5ae3 100755 --- a/python/bin/dwifslpreproc +++ b/python/bin/dwifslpreproc @@ -26,87 +26,116 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Perform diffusion image pre-processing using FSL\'s eddy tool; ' 'including inhomogeneity distortion correction using FSL\'s topup tool if possible') - cmdline.add_description('This script is intended to provide convenience of use of the FSL software tools topup and eddy for performing DWI pre-processing, ' - 'by encapsulating some of the surrounding image data and metadata processing steps. ' - 'It is intended to simply these processing steps for most commonly-used DWI acquisition strategies, ' - 'whilst also providing support for some more exotic acquisitions. ' - 'The "example usage" section demonstrates the ways in which the script can be used based on the (compulsory) -rpe_* command-line options.') + cmdline.add_description('This script is intended to provide convenience of use of the FSL software tools' + ' topup and eddy for performing DWI pre-processing,' + ' by encapsulating some of the surrounding image data and metadata processing steps.' + ' It is intended to simply these processing steps for most commonly-used DWI acquisition strategies,' + ' whilst also providing support for some more exotic acquisitions.' + ' The "example usage" section demonstrates the ways in which the script can be used' + ' based on the (compulsory) -rpe_* command-line options.') cmdline.add_description('More information on use of the dwifslpreproc command can be found at the following link: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/dwi_preprocessing/dwifslpreproc.html') - cmdline.add_description('Note that the MRtrix3 command dwi2mask will automatically be called to derive a processing mask for the FSL command "eddy", ' - 'which determines which voxels contribute to the estimation of geometric distortion parameters and possibly also the classification of outlier slices. ' - 'If FSL command "topup" is used to estimate a susceptibility field, ' - 'then dwi2mask will be executed on the resuts of running FSL command "applytopup" to the input DWIs; ' - 'otherwise it will be executed directly on the input DWIs. ' - 'Alternatively, the -eddy_mask option can be specified in order to manually provide such a processing mask. ' - 'More information on mask derivation from DWI data can be found at: ' + cmdline.add_description('Note that the MRtrix3 command dwi2mask will automatically be called' + ' to derive a processing mask for the FSL command "eddy",' + ' which determines which voxels contribute to the estimation of geometric distortion parameters' + ' and possibly also the classification of outlier slices.' + ' If FSL command "topup" is used to estimate a susceptibility field,' + ' then dwi2mask will be executed on the resuts of running FSL command "applytopup" to the input DWIs;' + ' otherwise it will be executed directly on the input DWIs.' + ' Alternatively, the -eddy_mask option can be specified in order to manually provide such a processing mask.' + ' More information on mask derivation from DWI data can be found at: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/dwi_preprocessing/masking.html') - cmdline.add_description('The "-topup_options" and "-eddy_options" command-line options allow the user to pass desired command-line options directly to the FSL commands topup and eddy. ' - 'The available options for those commands may vary between versions of FSL; ' - 'users can interrogate such by querying the help pages of the installed software, ' - 'and/or the FSL online documentation: ' - '(topup) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide ; ' + cmdline.add_description('The "-topup_options" and "-eddy_options" command-line options allow the user' + ' to pass desired command-line options directly to the FSL commands topup and eddy.' + ' The available options for those commands may vary between versions of FSL;' + ' users can interrogate such by querying the help pages of the installed software,' + ' and/or the FSL online documentation: \n' + '(topup) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide ; \n' '(eddy) https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide') - cmdline.add_description('The script will attempt to run the CUDA version of eddy; ' - 'if this does not succeed for any reason, or is not present on the system, ' - 'the CPU version will be attempted instead. ' - 'By default, the CUDA eddy binary found that indicates compilation against the most recent version of CUDA will be attempted; ' - 'this can be over-ridden by providing a soft-link "eddy_cuda" within your path that links to the binary you wish to be executed.') - cmdline.add_description('Note that this script does not perform any explicit registration between images provided to topup via the -se_epi option, ' - 'and the DWI volumes provided to eddy. ' - 'In some instances (motion between acquisitions) this can result in erroneous application of the inhomogeneity field during distortion correction. ' - 'Use of the -align_seepi option is advocated in this scenario, ' - 'which ensures that the first volume in the series provided to topup is also the first volume in the series provided to eddy, ' - 'guaranteeing alignment. ' - 'But a prerequisite for this approach is that the image contrast within the images provided to the -se_epi option ' - 'must match the b=0 volumes present within the input DWI series: ' - 'this means equivalent TE, TR and flip angle ' - '(note that differences in multi-band factors between two acquisitions may lead to differences in TR).') - cmdline.add_example_usage('A basic DWI acquisition, where all image volumes are acquired in a single protocol with fixed phase encoding', + cmdline.add_description('The script will attempt to run the CUDA version of eddy;' + ' if this does not succeed for any reason,' + ' or is not present on the system,' + ' the CPU version will be attempted instead.' + ' By default, the CUDA eddy binary found that indicates compilation' + ' against the most recent version of CUDA will be attempted;' + ' this can be over-ridden by providing a soft-link "eddy_cuda" within your path' + ' that links to the binary you wish to be executed.') + cmdline.add_description('Note that this script does not perform any explicit registration' + ' between images provided to topup via the -se_epi option,' + ' and the DWI volumes provided to eddy.' + ' In some instances (motion between acquisitions)' + ' this can result in erroneous application of the inhomogeneity field during distortion correction.' + ' Use of the -align_seepi option is advocated in this scenario,' + ' which ensures that the first volume in the series provided to topup' + ' is also the first volume in the series provided to eddy,' + ' guaranteeing alignment.' + ' But a prerequisite for this approach is that the image contrast' + ' within the images provided to the -se_epi option' + ' must match the b=0 volumes present within the input DWI series:' + ' this means equivalent TE, TR and flip angle' + ' (note that differences in multi-band factors between two acquisitions' + ' may lead to differences in TR).') + cmdline.add_example_usage('A basic DWI acquisition,' + ' where all image volumes are acquired in a single protocol with fixed phase encoding', 'dwifslpreproc DWI_in.mif DWI_out.mif -rpe_none -pe_dir ap -readout_time 0.55', - 'Due to use of a single fixed phase encoding, no EPI distortion correction can be applied in this case.') + 'Due to use of a single fixed phase encoding,' + ' no EPI distortion correction can be applied in this case.') cmdline.add_example_usage('DWIs all acquired with a single fixed phase encoding; ' - 'but additionally a pair of b=0 images with reversed phase encoding to estimate the inhomogeneity field', - 'mrcat b0_ap.mif b0_pa.mif b0_pair.mif -axis 3; ' - 'dwifslpreproc DWI_in.mif DWI_out.mif -rpe_pair -se_epi b0_pair.mif -pe_dir ap -readout_time 0.72 -align_seepi', - 'Here the two individual b=0 volumes are concatenated into a single 4D image series, ' - 'and this is provided to the script via the -se_epi option. ' - 'Note that with the -rpe_pair option used here, ' - 'which indicates that the SE-EPI image series contains one or more pairs of b=0 images with reversed phase encoding, ' - 'the FIRST HALF of the volumes in the SE-EPI series must possess the same phase encoding as the input DWI series, ' - 'while the second half are assumed to contain the opposite phase encoding direction but identical total readout time. ' - 'Use of the -align_seepi option is advocated as long as its use is valid ' - '(more information in the Description section).') - cmdline.add_example_usage('All DWI directions & b-values are acquired twice, ' - 'with the phase encoding direction of the second acquisition protocol being reversed with respect to the first', - 'mrcat DWI_lr.mif DWI_rl.mif DWI_all.mif -axis 3; ' - 'dwifslpreproc DWI_all.mif DWI_out.mif -rpe_all -pe_dir lr -readout_time 0.66', - 'Here the two acquisition protocols are concatenated into a single DWI series containing all acquired volumes. ' - 'The direction indicated via the -pe_dir option should be the direction of ' - 'phase encoding used in acquisition of the FIRST HALF of volumes in the input DWI series; ' - 'ie. the first of the two files that was provided to the mrcat command. ' - 'In this usage scenario, ' - 'the output DWI series will contain the same number of image volumes as ONE of the acquired DWI series ' - '(ie. half of the number in the concatenated series); ' - 'this is because the script will identify pairs of volumes that possess the same diffusion sensitisation but reversed phase encoding, ' - 'and perform explicit recombination of those volume pairs in such a way that image contrast in ' - 'regions of inhomogeneity is determined from the stretched rather than the compressed image.') + 'but additionally a pair of b=0 images with reversed phase encoding' + ' to estimate the inhomogeneity field', + 'mrcat b0_ap.mif b0_pa.mif b0_pair.mif -axis 3;' + ' dwifslpreproc DWI_in.mif DWI_out.mif -rpe_pair -se_epi b0_pair.mif -pe_dir ap -readout_time 0.72 -align_seepi', + 'Here the two individual b=0 volumes are concatenated into a single 4D image series,' + ' and this is provided to the script via the -se_epi option.' + ' Note that with the -rpe_pair option used here,' + ' which indicates that the SE-EPI image series contains' + ' one or more pairs of b=0 images with reversed phase encoding,' + ' the FIRST HALF of the volumes in the SE-EPI series must possess' + ' the same phase encoding as the input DWI series,' + ' while the second half are assumed to contain the opposite' + ' phase encoding direction but identical total readout time.' + ' Use of the -align_seepi option is advocated as long as its use is valid' + ' (more information in the Description section).') + cmdline.add_example_usage('All DWI directions & b-values are acquired twice,' + ' with the phase encoding direction of the second acquisition protocol' + ' being reversed with respect to the first', + 'mrcat DWI_lr.mif DWI_rl.mif DWI_all.mif -axis 3;' + ' dwifslpreproc DWI_all.mif DWI_out.mif -rpe_all -pe_dir lr -readout_time 0.66', + 'Here the two acquisition protocols are concatenated' + ' into a single DWI series containing all acquired volumes.' + ' The direction indicated via the -pe_dir option should be the direction of' + ' phase encoding used in acquisition of the FIRST HALF of volumes in the input DWI series;' + ' ie. the first of the two files that was provided to the mrcat command.' + ' In this usage scenario,' + ' the output DWI series will contain the same number of image volumes' + ' as ONE of the acquired DWI series' + ' (ie. half of the number in the concatenated series);' + ' this is because the script will identify pairs of volumes that possess' + ' the same diffusion sensitisation but reversed phase encoding,' + ' and perform explicit recombination of those volume pairs in such a way' + ' that image contrast in regions of inhomogeneity is determined' + ' from the stretched rather than the compressed image.') cmdline.add_example_usage('Any acquisition scheme that does not fall into one of the example usages above', - 'mrcat DWI_*.mif DWI_all.mif -axis 3; ' - 'mrcat b0_*.mif b0_all.mif -axis 3; ' - 'dwifslpreproc DWI_all.mif DWI_out.mif -rpe_header -se_epi b0_all.mif -align_seepi', - 'With this usage, ' - 'the relevant phase encoding information is determined entirely based on the contents of the relevant image headers, ' - 'and dwifslpreproc prepares all metadata for the executed FSL commands accordingly. ' - 'This can therefore be used if the particular DWI acquisition strategy used does not correspond to one of the simple examples as described in the prior examples. ' - 'This usage is predicated on the headers of the input files containing appropriately-named key-value fields such that MRtrix3 tools identify them as such. ' - 'In some cases, conversion from DICOM using MRtrix3 commands will automatically extract and embed this information; ' - 'however this is not true for all scanner vendors and/or software versions. ' - 'In the latter case it may be possible to manually provide these metadata; ' - 'either using the -json_import command-line option of dwifslpreproc, ' - 'or the -json_import or one of the -import_pe_* command-line options of MRtrix3\'s mrconvert command ' - '(and saving in .mif format) ' - 'prior to running dwifslpreproc.') + 'mrcat DWI_*.mif DWI_all.mif -axis 3;' + ' mrcat b0_*.mif b0_all.mif -axis 3;' + ' dwifslpreproc DWI_all.mif DWI_out.mif -rpe_header -se_epi b0_all.mif -align_seepi', + 'With this usage,' + ' the relevant phase encoding information is determined' + ' entirely based on the contents of the relevant image headers,' + ' and dwifslpreproc prepares all metadata for the executed FSL commands accordingly. ' + ' This can therefore be used if the particular DWI acquisition strategy used' + ' does not correspond to one of the simple examples as described in the prior examples.' + ' This usage is predicated on the headers of the input files' + ' containing appropriately-named key-value fields' + ' such that MRtrix3 tools identify them as such.' + ' In some cases,' + ' conversion from DICOM using MRtrix3 commands will automatically extract and embed this information;' + ' however this is not true for all scanner vendors and/or software versions.' + ' In the latter case it may be possible to manually provide these metadata;' + ' either using the -json_import command-line option of dwifslpreproc,' + ' or the -json_import or one of the -import_pe_* command-line options of MRtrix3\'s mrconvert command' + ' (and saving in .mif format)' + ' prior to running dwifslpreproc.') cmdline.add_citation('Andersson, J. L. & Sotiropoulos, S. N. ' 'An integrated approach to correction for off-resonance effects and subject movement in diffusion MR imaging. ' 'NeuroImage, 2015, 125, 1063-1078', @@ -118,7 +147,8 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.add_citation('Skare, S. & Bammer, R. ' 'Jacobian weighting of distortion corrected EPI data. ' 'Proceedings of the International Society for Magnetic Resonance in Medicine, 2010, 5063', - condition='If performing recombination of diffusion-weighted volume pairs with opposing phase encoding directions', + condition='If performing recombination of diffusion-weighted volume pairs' + ' with opposing phase encoding directions', is_external=True) cmdline.add_citation('Andersson, J. L.; Skare, S. & Ashburner, J. ' 'How to correct susceptibility distortions in spin-echo echo-planar images: ' @@ -151,15 +181,15 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.add_argument('-json_import', type=app.Parser.FileIn(), metavar='file', - help='Import image header information from an associated JSON file ' - '(may be necessary to determine phase encoding information)') + help='Import image header information from an associated JSON file' + ' (may be necessary to determine phase encoding information)') pe_options = cmdline.add_argument_group('Options for manually specifying the phase encoding of the input DWIs') pe_options.add_argument('-pe_dir', metavar='PE', - help='Manually specify the phase encoding direction of the input series; ' - 'can be a signed axis number (e.g. -0, 1, +2), ' - 'an axis designator (e.g. RL, PA, IS), ' - 'or NIfTI axis codes (e.g. i-, j, k)') + help='Manually specify the phase encoding direction of the input series;' + ' can be a signed axis number (e.g. -0, 1, +2),' + ' an axis designator (e.g. RL, PA, IS),' + ' or NIfTI axis codes (e.g. i-, j, k)') pe_options.add_argument('-readout_time', type=app.Parser.Float(0.0), metavar='time', @@ -168,18 +198,18 @@ def usage(cmdline): #pylint: disable=unused-variable distcorr_options.add_argument('-se_epi', type=app.Parser.ImageIn(), metavar='image', - help='Provide an additional image series consisting of spin-echo EPI images, ' - 'which is to be used exclusively by topup for estimating the inhomogeneity field ' - '(i.e. it will not form part of the output image series)') + help='Provide an additional image series consisting of spin-echo EPI images,' + ' which is to be used exclusively by topup for estimating the inhomogeneity field' + ' (i.e. it will not form part of the output image series)') distcorr_options.add_argument('-align_seepi', action='store_true', - help='Achieve alignment between the SE-EPI images used for inhomogeneity field estimation and the DWIs ' - '(more information in Description section)') + help='Achieve alignment between the SE-EPI images used for inhomogeneity field estimation and the DWIs' + ' (more information in Description section)') distcorr_options.add_argument('-topup_options', metavar='" TopupOptions"', - help='Manually provide additional command-line options to the topup command ' - '(provide a string within quotation marks that contains at least one space, ' - 'even if only passing a single command-line option to topup)') + help='Manually provide additional command-line options to the topup command' + ' (provide a string within quotation marks that contains at least one space,' + ' even if only passing a single command-line option to topup)') distcorr_options.add_argument('-topup_files', metavar='prefix', help='Provide files generated by prior execution of the FSL "topup" command to be utilised by eddy') @@ -190,50 +220,52 @@ def usage(cmdline): #pylint: disable=unused-variable eddy_options.add_argument('-eddy_mask', type=app.Parser.ImageIn(), metavar='image', - help='Provide a processing mask to use for eddy, ' - 'instead of having dwifslpreproc generate one internally using dwi2mask') + help='Provide a processing mask to use for eddy,' + ' instead of having dwifslpreproc generate one internally using dwi2mask') eddy_options.add_argument('-eddy_slspec', type=app.Parser.FileIn(), metavar='file', help='Provide a file containing slice groupings for eddy\'s slice-to-volume registration') eddy_options.add_argument('-eddy_options', metavar='" EddyOptions"', - help='Manually provide additional command-line options to the eddy command ' - '(provide a string within quotation marks that contains at least one space, ' - 'even if only passing a single command-line option to eddy)') + help='Manually provide additional command-line options to the eddy command' + ' (provide a string within quotation marks that contains at least one space,' + ' even if only passing a single command-line option to eddy)') eddyqc_options = cmdline.add_argument_group('Options for utilising EddyQC') eddyqc_options.add_argument('-eddyqc_text', type=app.Parser.DirectoryOut(), metavar='directory', - help='Copy the various text-based statistical outputs generated by eddy, ' - 'and the output of eddy_qc (if installed), ' - 'into an output directory') + help='Copy the various text-based statistical outputs generated by eddy,' + ' and the output of eddy_qc (if installed),' + ' into an output directory') eddyqc_options.add_argument('-eddyqc_all', type=app.Parser.DirectoryOut(), metavar='directory', - help='Copy ALL outputs generated by eddy (including images), ' - 'and the output of eddy_qc (if installed), ' - 'into an output directory') + help='Copy ALL outputs generated by eddy (including images),' + ' and the output of eddy_qc (if installed),' + ' into an output directory') cmdline.flag_mutually_exclusive_options( [ 'eddyqc_text', 'eddyqc_all' ], False ) app.add_dwgrad_export_options(cmdline) app.add_dwgrad_import_options(cmdline) - rpe_options = cmdline.add_argument_group('Options for specifying the acquisition phase-encoding design; ' - 'note that one of the -rpe_* options MUST be provided') + rpe_options = cmdline.add_argument_group('Options for specifying the acquisition phase-encoding design;' + ' note that one of the -rpe_* options MUST be provided') rpe_options.add_argument('-rpe_none', action='store_true', - help='Specify that no reversed phase-encoding image data is being provided; ' - 'eddy will perform eddy current and motion correction only') + help='Specify that no reversed phase-encoding image data is being provided;' + ' eddy will perform eddy current and motion correction only') rpe_options.add_argument('-rpe_pair', action='store_true', - help='Specify that a set of images (typically b=0 volumes) will be provided for use in inhomogeneity field estimation only ' - '(using the -se_epi option)') + help='Specify that a set of images' + ' (typically b=0 volumes)' + ' will be provided for use in inhomogeneity field estimation only' + ' (using the -se_epi option)') rpe_options.add_argument('-rpe_all', action='store_true', help='Specify that ALL DWIs have been acquired with opposing phase-encoding') rpe_options.add_argument('-rpe_header', action='store_true', - help='Specify that the phase-encoding information can be found in the image header(s), ' - 'and that this is the information that the script should use') + help='Specify that the phase-encoding information can be found in the image header(s),' + ' and that this is the information that the script should use') cmdline.flag_mutually_exclusive_options( [ 'rpe_none', 'rpe_pair', 'rpe_all', 'rpe_header' ], True ) cmdline.flag_mutually_exclusive_options( [ 'rpe_none', 'se_epi' ], False ) # May still technically provide -se_epi even with -rpe_all cmdline.flag_mutually_exclusive_options( [ 'rpe_pair', 'topup_files'] ) # Would involve two separate sources of inhomogeneity field information diff --git a/python/bin/dwigradcheck b/python/bin/dwigradcheck index 5b39ea2288..611530c62a 100755 --- a/python/bin/dwigradcheck +++ b/python/bin/dwigradcheck @@ -24,9 +24,11 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Check the orientation of the diffusion gradient table') cmdline.add_description('Note that the corrected gradient table can be output using the -export_grad_{mrtrix,fsl} option.') - cmdline.add_description('Note that if the -mask command-line option is not specified, the MRtrix3 command dwi2mask will automatically be called to ' - 'derive a binary mask image to be used for streamline seeding and to constrain streamline propagation. ' - 'More information on mask derivation from DWI data can be found at the following link: \n' + cmdline.add_description('Note that if the -mask command-line option is not specified,' + ' the MRtrix3 command dwi2mask will automatically be called' + ' to derive a binary mask image to be used for streamline seeding' + ' and to constrain streamline propagation.' + ' More information on mask derivation from DWI data can be found at the following link: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/dwi_preprocessing/masking.html') cmdline.add_citation('Jeurissen, B.; Leemans, A.; Sijbers, J. ' 'Automated correction of improperly rotated diffusion gradient orientations in diffusion weighted MRI. ' diff --git a/python/bin/dwinormalise b/python/bin/dwinormalise index 6f5ee6d49c..db6ea2720f 100755 --- a/python/bin/dwinormalise +++ b/python/bin/dwinormalise @@ -20,11 +20,14 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import algorithm #pylint: disable=no-name-in-module, import-outside-toplevel cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Perform various forms of intensity normalisation of DWIs') - cmdline.add_description('This script provides access to different techniques for globally scaling the intensity of diffusion-weighted images. ' - 'The different algorithms have different purposes, ' - 'and different requirements with respect to the data with which they must be provided & will produce as output. ' - 'Further information on the individual algorithms available can be accessed via their individual help pages; ' - 'eg. "dwinormalise group -help".') + cmdline.add_description('This script provides access to different techniques' + ' for globally scaling the intensity of diffusion-weighted images.' + ' The different algorithms have different purposes,' + ' and different requirements with respect to the data' + ' with which they must be provided & will produce as output.' + ' Further information on the individual algorithms available' + ' can be accessed via their individual help pages;' + ' eg. "dwinormalise group -help".') # Import the command-line settings for all algorithms found in the relevant directory algorithm.usage(cmdline) diff --git a/python/bin/dwishellmath b/python/bin/dwishellmath index 9d1a192e65..5b06cecc37 100755 --- a/python/bin/dwishellmath +++ b/python/bin/dwishellmath @@ -23,18 +23,18 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel cmdline.set_author('Daan Christiaens (daan.christiaens@kcl.ac.uk)') cmdline.set_synopsis('Apply an mrmath operation to each b-value shell in a DWI series') - cmdline.add_description('The output of this command is a 4D image, ' - 'where each volume corresponds to a b-value shell ' - '(in order of increasing b-value), ' - 'an the intensities within each volume correspond to the chosen statistic having been ' - 'computed from across the DWI volumes belonging to that b-value shell.') + cmdline.add_description('The output of this command is a 4D image,' + ' where each volume corresponds to a b-value shell' + ' (in order of increasing b-value),' + ' and the intensities within each volume correspond to the chosen statistic' + ' having been computed from across the DWI volumes belonging to that b-value shell.') cmdline.add_argument('input', type=app.Parser.ImageIn(), help='The input diffusion MRI series') cmdline.add_argument('operation', choices=SUPPORTED_OPS, - help='The operation to be applied to each shell; ' - 'this must be one of the following: ' + help='The operation to be applied to each shell;' + ' this must be one of the following: ' + ', '.join(SUPPORTED_OPS)) cmdline.add_argument('output', type=app.Parser.ImageOut(), diff --git a/python/bin/for_each b/python/bin/for_each index 1743bfd760..0931606b8b 100755 --- a/python/bin/for_each +++ b/python/bin/for_each @@ -31,19 +31,24 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import _version #pylint: disable=no-name-in-module, import-outside-toplevel cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au) and David Raffelt (david.raffelt@florey.edu.au)') cmdline.set_synopsis('Perform some arbitrary processing step for each of a set of inputs') - cmdline.add_description('This script greatly simplifies various forms of batch processing by enabling the execution of a command ' - '(or set of commands) ' - 'independently for each of a set of inputs.') + cmdline.add_description('This script greatly simplifies various forms of batch processing' + ' by enabling the execution of a command' + ' (or set of commands)' + ' independently for each of a set of inputs.') cmdline.add_description('More information on use of the for_each command can be found at the following link: \n' f'https://mrtrix.readthedocs.io/en/{_version.__tag__}/tips_and_tricks/batch_processing_with_foreach.html') - cmdline.add_description('The way that this batch processing capability is achieved is by providing basic text substitutions, ' - 'which simplify the formation of valid command strings based on the unique components of the input strings on which the script is instructed to execute. ' - 'This does however mean that the items to be passed as inputs to the for_each command ' - '(e.g. file / directory names) ' - 'MUST NOT contain any instances of these substitution strings, ' - 'as otherwise those paths will be corrupted during the course of the substitution.') + cmdline.add_description('The way that this batch processing capability is achieved' + ' is by providing basic text substitutions,' + ' which simplify the formation of valid command strings' + ' based on the unique components of the input strings' + ' on which the script is instructed to execute. ' + 'This does however mean that the items to be passed as inputs to the for_each command' + ' (e.g. file / directory names)' + ' MUST NOT contain any instances of these substitution strings,' + ' as otherwise those paths will be corrupted during the course of the substitution.') cmdline.add_description('The available substitutions are listed below ' - '(note that the -test command-line option can be used to ensure correct command string formation prior to actually executing the commands):') + '(note that the -test command-line option can be used' + ' to ensure correct command string formation prior to actually executing the commands):') cmdline.add_description(' - IN: ' 'The full matching pattern, including leading folders. ' 'For example, if the target list contains a file "folder/image.mif", ' @@ -61,52 +66,61 @@ def usage(cmdline): #pylint: disable=unused-variable 'The unique part of the input after removing any common prefix and common suffix. ' 'For example, if the target list contains files: "folder/001dwi.mif", "folder/002dwi.mif", "folder/003dwi.mif", ' 'any occurrence of "UNI" will be substituted with "001", "002", "003".') - cmdline.add_description('Note that due to a limitation of the Python "argparse" module, ' - 'any command-line OPTIONS that the user intends to provide specifically to the for_each script ' - 'must appear BEFORE providing the list of inputs on which for_each is intended to operate. ' - 'While command-line options provided as such will be interpreted specifically by the for_each script, ' - 'any command-line options that are provided AFTER the COLON separator will form part of the executed COMMAND, ' - 'and will therefore be interpreted as command-line options having been provided to that underlying command.') + cmdline.add_description('Note that due to a limitation of the Python "argparse" module,' + ' any command-line OPTIONS that the user intends to provide specifically to the for_each script' + ' must appear BEFORE providing the list of inputs on which for_each is intended to operate.' + ' While command-line options provided as such will be interpreted specifically by the for_each script,' + ' any command-line options that are provided AFTER the COLON separator will form part of the executed COMMAND,' + ' and will therefore be interpreted as command-line options having been provided to that underlying command.') cmdline.add_example_usage('Demonstration of basic usage syntax', 'for_each folder/*.mif : mrinfo IN', - 'This will run the "mrinfo" command for every .mif file present in "folder/". ' - 'Note that the compulsory colon symbol is used to separate the list of items on which for_each is being instructed to operate, ' - 'from the command that is intended to be run for each input.') + 'This will run the "mrinfo" command for every .mif file present in "folder/".' + ' Note that the compulsory colon symbol is used' + ' to separate the list of items on which for_each is being instructed to operate' + ' from the command that is intended to be run for each input.') cmdline.add_example_usage('Multi-threaded use of for_each', 'for_each -nthreads 4 freesurfer/subjects/* : recon-all -subjid NAME -all', 'In this example, ' - 'for_each is instructed to run the FreeSurfer command "recon-all" for all subjects within the "subjects" directory, ' - 'with four subjects being processed in parallel at any one time. ' - 'Whenever processing of one subject is completed, ' - 'processing for a new unprocessed subject will commence. ' - 'This technique is useful for improving the efficiency of running single-threaded commands on multi-core systems, ' - 'as long as the system possesses enough memory to support such parallel processing. ' - 'Note that in the case of multi-threaded commands ' - '(which includes many MRtrix3 commands), ' - 'it is generally preferable to permit multi-threaded execution of the command on a single input at a time, ' - 'rather than processing multiple inputs in parallel.') + 'for_each is instructed to run the FreeSurfer command "recon-all"' + ' for all subjects within the "subjects" directory,' + ' with four subjects being processed in parallel at any one time.' + ' Whenever processing of one subject is completed,' + ' processing for a new unprocessed subject will commence.' + ' This technique is useful for improving the efficiency' + ' of running single-threaded commands on multi-core systems,' + ' as long as the system possesses enough memory to support such parallel processing.' + ' Note that in the case of multi-threaded commands' + ' (which includes many MRtrix3 commands),' + ' it is generally preferable to permit multi-threaded execution' + ' of the command on a single input at a time,' + ' rather than processing multiple inputs in parallel.') cmdline.add_example_usage('Excluding specific inputs from execution', 'for_each *.nii -exclude 001.nii : mrconvert IN PRE.mif', - 'Particularly when a wildcard is used to define the list of inputs for for_each, ' - 'it is possible in some instances that this list will include one or more strings for which execution should in fact not be performed; ' - 'for instance, if a command has already been executed for one or more files, ' - 'and then for_each is being used to execute the same command for all other files. ' - 'In this case, ' - 'the -exclude option can be used to effectively remove an item from the list of inputs that would otherwise be included due to the use of a wildcard ' - '(and can be used more than once to exclude more than one string). ' - 'In this particular example, ' - 'mrconvert is instructed to perform conversions from NIfTI to MRtrix image formats, ' - 'for all except the first image in the directory. ' - 'Note that any usages of this option must appear AFTER the list of inputs. ' - 'Note also that the argument following the -exclude option can alternatively be a regular expression, ' - 'in which case any inputs for which a match to the expression is found will be excluded from processing.') + 'Particularly when a wildcard is used to define the list of inputs for for_each,' + ' it is possible in some instances that this list will include one or more strings' + ' for which execution should in fact not be performed;' + ' for instance, if a command has already been executed for one or more files,' + ' and then for_each is being used to execute the same command for all other files.' + ' In this case,' + ' the -exclude option can be used to effectively remove an item' + ' from the list of inputs that would otherwise be included due to the use of a wildcard' + ' (and can be used more than once to exclude more than one string).' + ' In this particular example,' + ' mrconvert is instructed to perform conversions from NIfTI to MRtrix image formats,' + ' for all except the first image in the directory.' + ' Note that any usages of this option must appear AFTER the list of inputs.' + ' Note also that the argument following the -exclude option' + ' can alternatively be a regular expression,' + ' in which case any inputs for which a match to the expression is found' + ' will be excluded from processing.') cmdline.add_example_usage('Testing the command string substitution', 'for_each -test * : mrconvert IN PRE.mif', - 'By specifying the -test option, ' - 'the script will print to the terminal the results of text substitutions for all of the specified inputs, ' - 'but will not actually execute those commands. ' - 'It can therefore be used to verify that the script is receiving the intended set of inputs, ' - 'and that the text substitutions on those inputs lead to the intended command strings.') + 'By specifying the -test option,' + ' the script will print to the terminal the results of text substitutions' + ' for all of the specified inputs,' + ' but will not actually execute those commands.' + ' It can therefore be used to verify that the script is receiving the intended set of inputs,' + ' and that the text substitutions on those inputs lead to the intended command strings.') cmdline.add_argument('inputs', nargs='+', help='Each of the inputs for which processing should be run') @@ -127,8 +141,8 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.add_argument('-test', action='store_true', default=False, - help='Test the operation of the for_each script, ' - 'by printing the command strings following string substitution but not actually executing them') + help='Test the operation of the for_each script,' + ' by printing the command strings following string substitution but not actually executing them') # Usage of for_each needs to be handled slightly differently here: # We want argparse to parse only the contents of the command-line before the colon symbol, diff --git a/python/bin/labelsgmfix b/python/bin/labelsgmfix index e1b941a440..ad8d7de722 100755 --- a/python/bin/labelsgmfix +++ b/python/bin/labelsgmfix @@ -32,8 +32,8 @@ import math, os def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') - cmdline.set_synopsis('In a FreeSurfer parcellation image, ' - 'replace the sub-cortical grey matter structure delineations using FSL FIRST') + cmdline.set_synopsis('In a FreeSurfer parcellation image,' + ' replace the sub-cortical grey matter structure delineations using FSL FIRST') cmdline.add_citation('Patenaude, B.; Smith, S. M.; Kennedy, D. N. & Jenkinson, M. ' 'A Bayesian model of shape and appearance for subcortical brain segmentation. ' 'NeuroImage, 2011, 56, 907-922', @@ -64,8 +64,8 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.add_argument('-sgm_amyg_hipp', action='store_true', default=False, - help='Consider the amygdalae and hippocampi as sub-cortical grey matter structures, ' - 'and also replace their estimates with those from FIRST') + help='Consider the amygdalae and hippocampi as sub-cortical grey matter structures,' + ' and also replace their estimates with those from FIRST') diff --git a/python/bin/mask2glass b/python/bin/mask2glass index 3a3e028450..d2c8fab50b 100755 --- a/python/bin/mask2glass +++ b/python/bin/mask2glass @@ -17,16 +17,18 @@ def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Remika Mito (remika.mito@florey.edu.au) ' - 'and Robert E. Smith (robert.smith@florey.edu.au)') + cmdline.set_author('Remika Mito (remika.mito@florey.edu.au)' + ' and Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Create a glass brain from mask input') - cmdline.add_description('The output of this command is a glass brain image, ' - 'which can be viewed using the volume render option in mrview, ' - 'and used for visualisation purposes to view results in 3D.') - cmdline.add_description('While the name of this script indicates that a binary mask image is required as input, ' - 'it can also operate on a floating-point image. ' - 'One way in which this can be exploited is to compute the mean of all subject masks within template space, ' - 'in which case this script will produce a smoother result than if a binary template mask were to be used as input.') + cmdline.add_description('The output of this command is a glass brain image,' + ' which can be viewed using the volume render option in mrview,' + ' and used for visualisation purposes to view results in 3D.') + cmdline.add_description('While the name of this script indicates that a binary mask image is required as input,' + ' it can also operate on a floating-point image.' + ' One way in which this can be exploited' + ' is to compute the mean of all subject masks within template space,' + ' in which case this script will produce a smoother result' + ' than if a binary template mask were to be used as input.') cmdline.add_argument('input', type=app.Parser.ImageIn(), help='The input mask image') @@ -36,15 +38,18 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.add_argument('-dilate', type=app.Parser.Int(0), default=2, - help='Provide number of passes for dilation step; default = 2') + help='Provide number of passes for dilation step;' + ' default = 2') cmdline.add_argument('-scale', type=app.Parser.Float(0.0), default=2.0, - help='Provide resolution upscaling value; default = 2.0') + help='Provide resolution upscaling value;' + ' default = 2.0') cmdline.add_argument('-smooth', type=app.Parser.Float(0.0), default=1.0, - help='Provide standard deviation of smoothing (in mm); default = 1.0') + help='Provide standard deviation of smoothing (in mm);' + ' default = 1.0') def execute(): #pylint: disable=unused-variable diff --git a/python/bin/mrtrix_cleanup b/python/bin/mrtrix_cleanup index a2a7702226..f1275414c1 100755 --- a/python/bin/mrtrix_cleanup +++ b/python/bin/mrtrix_cleanup @@ -27,24 +27,28 @@ def usage(cmdline): #pylint: disable=unused-variable cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)') cmdline.set_synopsis('Clean up residual temporary files & scratch directories from MRtrix3 commands') - cmdline.add_description('This script will search the file system at the specified location ' - '(and in sub-directories thereof) ' - 'for any temporary files or directories that have been left behind by failed or terminated MRtrix3 commands, ' - 'and attempt to delete them.') - cmdline.add_description('Note that the script\'s search for temporary items will not extend beyond the user-specified filesystem location. ' - 'This means that any built-in or user-specified default location for MRtrix3 piped data and scripts will not be automatically searched. ' - 'Cleanup of such locations should instead be performed explicitly: ' - 'e.g. "mrtrix_cleanup /tmp/" to remove residual piped images from /tmp/.') - cmdline.add_description('This script should not be run while other MRtrix3 commands are being executed: ' - 'it may delete temporary items during operation that may lead to unexpected behaviour.') + cmdline.add_description('This script will search the file system at the specified location' + ' (and in sub-directories thereof)' + ' for any temporary files or directories that have been left behind' + ' by failed or terminated MRtrix3 commands,' + ' and attempt to delete them.') + cmdline.add_description('Note that the script\'s search for temporary items' + ' will not extend beyond the user-specified filesystem location.' + ' This means that any built-in or user-specified default location' + ' for MRtrix3 piped data and scripts will not be automatically searched.' + ' Cleanup of such locations should instead be performed explicitly:' + ' e.g. "mrtrix_cleanup /tmp/" to remove residual piped images from /tmp/.') + cmdline.add_description('This script should not be run while other MRtrix3 commands are being executed:' + ' it may delete temporary items during operation' + ' that may lead to unexpected behaviour.') cmdline.add_argument('path', type=app.Parser.DirectoryIn(), help='Directory from which to commence filesystem search') cmdline.add_argument('-test', action='store_true', - help='Run script in test mode: ' - 'will list identified files / directories, ' - 'but not attempt to delete them') + help='Run script in test mode:' + ' will list identified files / directories,' + ' but not attempt to delete them') cmdline.add_argument('-failed', type=app.Parser.FileOut(), metavar='file', diff --git a/python/bin/population_template b/python/bin/population_template index 70d3e9e39f..d6219ea94a 100755 --- a/python/bin/population_template +++ b/python/bin/population_template @@ -34,7 +34,13 @@ DEFAULT_NL_UPDATE_SMOOTH = 2.0 DEFAULT_NL_DISP_SMOOTH = 1.0 DEFAULT_NL_GRAD_STEP = 0.5 -REGISTRATION_MODES = ['rigid', 'affine', 'nonlinear', 'rigid_affine', 'rigid_nonlinear', 'affine_nonlinear', 'rigid_affine_nonlinear'] +REGISTRATION_MODES = ['rigid', + 'affine', + 'nonlinear', + 'rigid_affine', + 'rigid_nonlinear', + 'affine_nonlinear', + 'rigid_affine_nonlinear'] AGGREGATION_MODES = ['mean', 'median'] @@ -48,14 +54,14 @@ IMAGEEXT = ['mif', 'nii', 'mih', 'mgh', 'mgz', 'img', 'hdr'] def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('David Raffelt (david.raffelt@florey.edu.au) ' - '& Max Pietsch (maximilian.pietsch@kcl.ac.uk) ' - '& Thijs Dhollander (thijs.dhollander@gmail.com)') + cmdline.set_author('David Raffelt (david.raffelt@florey.edu.au)' + ' and Max Pietsch (maximilian.pietsch@kcl.ac.uk)' + ' and Thijs Dhollander (thijs.dhollander@gmail.com)') cmdline.set_synopsis('Generates an unbiased group-average template from a series of images') - cmdline.add_description('First a template is optimised with linear registration ' - '(rigid and/or affine, both by default), ' - 'then non-linear registration is used to optimise the template further.') + cmdline.add_description('First a template is optimised with linear registration' + ' (rigid and/or affine, both by default),' + ' then non-linear registration is used to optimise the template further.') cmdline.add_argument('input_dir', nargs='+', type=app.Parser.Various(), @@ -65,28 +71,36 @@ def usage(cmdline): #pylint: disable=unused-variable help='Output template image') cmdline.add_example_usage('Multi-contrast registration', 'population_template input_WM_ODFs/ output_WM_template.mif input_GM_ODFs/ output_GM_template.mif', - 'When performing multi-contrast registration, ' - 'the input directory and corresponding output template ' - 'image for a given contrast are to be provided as a pair, ' - 'with the pairs corresponding to different contrasts provided sequentially.') + 'When performing multi-contrast registration,' + ' the input directory and corresponding output template image' + ' for a given contrast are to be provided as a pair,' + ' with the pairs corresponding to different contrasts provided sequentially.') options = cmdline.add_argument_group('Multi-contrast options') options.add_argument('-mc_weight_initial_alignment', type=app.Parser.SequenceFloat(), - help='Weight contribution of each contrast to the initial alignment. ' - 'Comma separated, default: 1.0 for each contrast (ie. equal weighting).') + metavar='values', + help='Weight contribution of each contrast to the initial alignment.' + ' Comma separated,' + ' default: 1.0 for each contrast (ie. equal weighting).') options.add_argument('-mc_weight_rigid', type=app.Parser.SequenceFloat(), - help='Weight contribution of each contrast to the objective of rigid registration. ' - 'Comma separated, default: 1.0 for each contrast (ie. equal weighting)') + metavar='values', + help='Weight contribution of each contrast to the objective of rigid registration.' + ' Comma separated,' + ' default: 1.0 for each contrast (ie. equal weighting)') options.add_argument('-mc_weight_affine', type=app.Parser.SequenceFloat(), - help='Weight contribution of each contrast to the objective of affine registration. ' - 'Comma separated, default: 1.0 for each contrast (ie. equal weighting)') + metavar='values', + help='Weight contribution of each contrast to the objective of affine registration.' + ' Comma separated,' + ' default: 1.0 for each contrast (ie. equal weighting)') options.add_argument('-mc_weight_nl', type=app.Parser.SequenceFloat(), - help='Weight contribution of each contrast to the objective of nonlinear registration. ' - 'Comma separated, default: 1.0 for each contrast (ie. equal weighting)') + metavar='values', + help='Weight contribution of each contrast to the objective of nonlinear registration.' + ' Comma separated,' + ' default: 1.0 for each contrast (ie. equal weighting)') linoptions = cmdline.add_argument_group('Options for the linear registration') linoptions.add_argument('-linear_no_pause', @@ -97,170 +111,179 @@ def usage(cmdline): #pylint: disable=unused-variable help='Deactivate correction of template appearance (scale and shear) over iterations') linoptions.add_argument('-linear_estimator', choices=LINEAR_ESTIMATORS, - help='Specify estimator for intensity difference metric. ' - 'Valid choices are: ' - 'l1 (least absolute: |x|), ' - 'l2 (ordinary least squares), ' - 'lp (least powers: |x|^1.2), ' - 'none (no robust estimator). ' - 'Default: none.') + help='Specify estimator for intensity difference metric.' + ' Valid choices are:' + ' l1 (least absolute: |x|),' + ' l2 (ordinary least squares),' + ' lp (least powers: |x|^1.2),' + ' none (no robust estimator).' + ' Default: none.') linoptions.add_argument('-rigid_scale', type=app.Parser.SequenceFloat(), - help='Specify the multi-resolution pyramid used to build the rigid template, ' - 'in the form of a list of scale factors ' - f'(default: {",".join([str(x) for x in DEFAULT_RIGID_SCALES])}). ' - 'This and affine_scale implicitly define the number of template levels') + help='Specify the multi-resolution pyramid used to build the rigid template,' + ' in the form of a list of scale factors' + f' (default: {",".join([str(x) for x in DEFAULT_RIGID_SCALES])}).' + ' This and affine_scale implicitly define the number of template levels') linoptions.add_argument('-rigid_lmax', type=app.Parser.SequenceInt(), - help='Specify the lmax used for rigid registration for each scale factor, ' - 'in the form of a list of integers ' - f'(default: {",".join([str(x) for x in DEFAULT_RIGID_LMAX])}). ' - 'The list must be the same length as the linear_scale factor list') + help='Specify the lmax used for rigid registration for each scale factor,' + ' in the form of a list of integers' + f' (default: {",".join([str(x) for x in DEFAULT_RIGID_LMAX])}).' + ' The list must be the same length as the linear_scale factor list') linoptions.add_argument('-rigid_niter', type=app.Parser.SequenceInt(), - help='Specify the number of registration iterations used within each level before updating the template, ' - 'in the form of a list of integers ' - '(default: 50 for each scale). ' - 'This must be a single number or a list of same length as the linear_scale factor list') + help='Specify the number of registration iterations used' + ' within each level before updating the template,' + ' in the form of a list of integers' + ' (default: 50 for each scale).' + ' This must be a single number' + ' or a list of same length as the linear_scale factor list') linoptions.add_argument('-affine_scale', type=app.Parser.SequenceFloat(), - help='Specify the multi-resolution pyramid used to build the affine template, ' - 'in the form of a list of scale factors ' - f'(default: {",".join([str(x) for x in DEFAULT_AFFINE_SCALES])}). ' - 'This and rigid_scale implicitly define the number of template levels') + help='Specify the multi-resolution pyramid used to build the affine template,' + ' in the form of a list of scale factors' + f' (default: {",".join([str(x) for x in DEFAULT_AFFINE_SCALES])}).' + ' This and rigid_scale implicitly define the number of template levels') linoptions.add_argument('-affine_lmax', type=app.Parser.SequenceInt(), - help='Specify the lmax used for affine registration for each scale factor, ' - 'in the form of a list of integers ' - f'(default: {",".join([str(x) for x in DEFAULT_AFFINE_LMAX])}). ' - 'The list must be the same length as the linear_scale factor list') + help='Specify the lmax used for affine registration for each scale factor,' + ' in the form of a list of integers' + f' (default: {",".join([str(x) for x in DEFAULT_AFFINE_LMAX])}).' + ' The list must be the same length as the linear_scale factor list') linoptions.add_argument('-affine_niter', type=app.Parser.SequenceInt(), - help='Specify the number of registration iterations used within each level before updating the template, ' - 'in the form of a list of integers ' - '(default: 500 for each scale). ' - 'This must be a single number or a list of same length as the linear_scale factor list') + help='Specify the number of registration iterations' + ' used within each level before updating the template,' + ' in the form of a list of integers' + ' (default: 500 for each scale).' + ' This must be a single number' + ' or a list of same length as the linear_scale factor list') nloptions = cmdline.add_argument_group('Options for the non-linear registration') nloptions.add_argument('-nl_scale', type=app.Parser.SequenceFloat(), - help='Specify the multi-resolution pyramid used to build the non-linear template, ' - 'in the form of a list of scale factors ' - f'(default: {" ".join([str(x) for x in DEFAULT_NL_SCALES])}). ' - 'This implicitly defines the number of template levels') + help='Specify the multi-resolution pyramid used to build the non-linear template,' + ' in the form of a list of scale factors' + f' (default: {",".join([str(x) for x in DEFAULT_NL_SCALES])}).' + ' This implicitly defines the number of template levels') nloptions.add_argument('-nl_lmax', type=app.Parser.SequenceInt(), - help='Specify the lmax used for non-linear registration for each scale factor, ' - 'in the form of a list of integers ' - f'(default: {",".join([str(x) for x in DEFAULT_NL_LMAX])}). ' - 'The list must be the same length as the nl_scale factor list') + help='Specify the lmax used for non-linear registration for each scale factor,' + ' in the form of a list of integers' + f' (default: {",".join([str(x) for x in DEFAULT_NL_LMAX])}).' + ' The list must be the same length as the nl_scale factor list') nloptions.add_argument('-nl_niter', type=app.Parser.SequenceInt(), - help='Specify the number of registration iterations used within each level before updating the template, ' - 'in the form of a list of integers ' - f'(default: {",".join([str(x) for x in DEFAULT_NL_NITER])}). ' - 'The list must be the same length as the nl_scale factor list') + help='Specify the number of registration iterations' + ' used within each level before updating the template,' + ' in the form of a list of integers' + f' (default: {",".join([str(x) for x in DEFAULT_NL_NITER])}).' + ' The list must be the same length as the nl_scale factor list') nloptions.add_argument('-nl_update_smooth', type=app.Parser.Float(0.0), default=DEFAULT_NL_UPDATE_SMOOTH, - help='Regularise the gradient update field with Gaussian smoothing ' - '(standard deviation in voxel units, ' - f'Default {DEFAULT_NL_UPDATE_SMOOTH} x voxel_size)') + help='Regularise the gradient update field with Gaussian smoothing' + ' (standard deviation in voxel units,' + f' Default {DEFAULT_NL_UPDATE_SMOOTH} x voxel_size)') nloptions.add_argument('-nl_disp_smooth', type=app.Parser.Float(0.0), default=DEFAULT_NL_DISP_SMOOTH, - help='Regularise the displacement field with Gaussian smoothing ' - '(standard deviation in voxel units, ' - f'Default {DEFAULT_NL_DISP_SMOOTH} x voxel_size)') + help='Regularise the displacement field with Gaussian smoothing' + ' (standard deviation in voxel units,' + f' Default {DEFAULT_NL_DISP_SMOOTH} x voxel_size)') nloptions.add_argument('-nl_grad_step', type=app.Parser.Float(0.0), default=DEFAULT_NL_GRAD_STEP, - help='The gradient step size for non-linear registration ' - f'(Default: {DEFAULT_NL_GRAD_STEP})') + help='The gradient step size for non-linear registration' + f' (Default: {DEFAULT_NL_GRAD_STEP})') options = cmdline.add_argument_group('Input, output and general options') registration_modes_string = ', '.join(f'"{x}"' for x in REGISTRATION_MODES if '_' in x) options.add_argument('-type', choices=REGISTRATION_MODES, - help='Specify the types of registration stages to perform. ' - 'Options are: ' - '"rigid" (perform rigid registration only, ' - 'which might be useful for intra-subject registration in longitudinal analysis), ' - '"affine" (perform affine registration), ' - '"nonlinear", ' - f'as well as cominations of registration types: {registration_modes_string}. ' - 'Default: rigid_affine_nonlinear', + help='Specify the types of registration stages to perform.' + ' Options are:' + ' "rigid" (perform rigid registration only,' + ' which might be useful for intra-subject registration in longitudinal analysis);' + ' "affine" (perform affine registration);' + ' "nonlinear";' + f' as well as cominations of registration types: {registration_modes_string}.' + ' Default: rigid_affine_nonlinear', default='rigid_affine_nonlinear') options.add_argument('-voxel_size', type=app.Parser.SequenceFloat(), - help='Define the template voxel size in mm. ' - 'Use either a single value for isotropic voxels or 3 comma-separated values.') + help='Define the template voxel size in mm.' + ' Use either a single value for isotropic voxels or 3 comma-separated values.') options.add_argument('-initial_alignment', choices=INITIAL_ALIGNMENT, default='mass', - help='Method of alignment to form the initial template. ' - 'Options are: ' - '"mass" (default), ' - '"robust_mass" (requires masks), ' - '"geometric", ' - '"none".') + help='Method of alignment to form the initial template.' + ' Options are:' + ' "mass" (default);' + ' "robust_mass" (requires masks);' + ' "geometric";' + ' "none".') options.add_argument('-mask_dir', type=app.Parser.DirectoryIn(), - help='Optionally input a set of masks inside a single directory, ' - 'one per input image ' - '(with the same file name prefix). ' - 'Using masks will speed up registration significantly. ' - 'Note that masks are used for registration, ' - 'not for aggregation. ' - 'To exclude areas from aggregation, ' - 'NaN-mask your input images.') + help='Optionally input a set of masks inside a single directory,' + ' one per input image' + ' (with the same file name prefix).' + ' Using masks will speed up registration significantly.' + ' Note that masks are used for registration,' + ' not for aggregation.' + ' To exclude areas from aggregation,' + ' NaN-mask your input images.') options.add_argument('-warp_dir', type=app.Parser.DirectoryOut(), - help='Output a directory containing warps from each input to the template. ' - 'If the folder does not exist it will be created') + help='Output a directory containing warps from each input to the template.' + ' If the folder does not exist it will be created') # TODO Would prefer for this to be exclusively a directory; # but to do so will need to provide some form of disambiguation of multi-contrast files options.add_argument('-transformed_dir', type=app.Parser.DirectoryOut(), - help='Output a directory containing the input images transformed to the template. ' - 'If the folder does not exist it will be created. ' - 'For multi-contrast registration, ' - 'this path will contain a sub-directory for the images per contrast.') + help='Output a directory containing the input images transformed to the template.' + ' If the folder does not exist it will be created.' + ' For multi-contrast registration,' + ' this path will contain a sub-directory for the images per contrast.') options.add_argument('-linear_transformations_dir', type=app.Parser.DirectoryOut(), - help='Output a directory containing the linear transformations used to generate the template. ' - 'If the folder does not exist it will be created') + help='Output a directory containing the linear transformations' + ' used to generate the template.' + ' If the folder does not exist it will be created') options.add_argument('-template_mask', type=app.Parser.ImageOut(), - help='Output a template mask. ' - 'Only works if -mask_dir has been input. ' - 'The template mask is computed as the intersection of all subject masks in template space.') + help='Output a template mask.' + ' Only works if -mask_dir has been input.' + ' The template mask is computed as the intersection' + ' of all subject masks in template space.') options.add_argument('-noreorientation', action='store_true', - help='Turn off FOD reorientation in mrregister. ' - 'Reorientation is on by default if the number of volumes in the 4th dimension ' - 'corresponds to the number of coefficients in an antipodally symmetric spherical harmonic series ' - '(i.e. 6, 15, 28, 45, 66 etc)') + help='Turn off FOD reorientation in mrregister.' + ' Reorientation is on by default if the number of volumes in the 4th dimension' + ' corresponds to the number of coefficients' + ' in an antipodally symmetric spherical harmonic series' + ' (i.e. 6, 15, 28, 45, 66 etc)') options.add_argument('-leave_one_out', choices=LEAVE_ONE_OUT, default='auto', - help='Register each input image to a template that does not contain that image. ' - f'Valid choices: {", ".join(LEAVE_ONE_OUT)}. ' - '(Default: auto (true if n_subjects larger than 2 and smaller than 15))') + help='Register each input image to a template that does not contain that image.' + f' Valid choices: {", ".join(LEAVE_ONE_OUT)}.' + ' (Default: auto (true if n_subjects larger than 2 and smaller than 15))') options.add_argument('-aggregate', choices=AGGREGATION_MODES, - help='Measure used to aggregate information from transformed images to the template image. ' - f'Valid choices: {", ".join(AGGREGATION_MODES)}. ' - 'Default: mean') + help='Measure used to aggregate information from transformed images to the template image.' + f' Valid choices: {", ".join(AGGREGATION_MODES)}.' + ' Default: mean') options.add_argument('-aggregation_weights', type=app.Parser.FileIn(), - help='Comma-separated file containing weights used for weighted image aggregation. ' - 'Each row must contain the identifiers of the input image and its weight. ' - 'Note that this weighs intensity values not transformations (shape).') + help='Comma-separated file containing weights used for weighted image aggregation.' + ' Each row must contain the identifiers of the input image and its weight.' + ' Note that this weighs intensity values not transformations (shape).') options.add_argument('-nanmask', action='store_true', - help='Optionally apply masks to (transformed) input images using NaN values to specify include areas for registration and aggregation. ' - 'Only works if -mask_dir has been input.') + help='Optionally apply masks to (transformed) input images using NaN values' + ' to specify include areas for registration and aggregation.' + ' Only works if -mask_dir has been input.') options.add_argument('-copy_input', action='store_true', help='Copy input images and masks into local scratch directory.') diff --git a/python/bin/responsemean b/python/bin/responsemean index 627d47e766..d34eaff2d6 100755 --- a/python/bin/responsemean +++ b/python/bin/responsemean @@ -22,16 +22,16 @@ import math, sys def usage(cmdline): #pylint: disable=unused-variable from mrtrix3 import app #pylint: disable=no-name-in-module, import-outside-toplevel - cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au) ' - 'and David Raffelt (david.raffelt@florey.edu.au)') + cmdline.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and David Raffelt (david.raffelt@florey.edu.au)') cmdline.set_synopsis('Calculate the mean response function from a set of text files') - cmdline.add_description('All response function files provided must contain the same number of unique b-values (lines), ' - 'as well as the same number of coefficients per line.') - cmdline.add_description('As long as the number of unique b-values is identical across all input files, ' - 'the coefficients will be averaged. ' - 'This is performed on the assumption that the actual acquired b-values are identical. ' - 'This is however impossible for the responsemean command to determine based on the data provided; ' - 'it is therefore up to the user to ensure that this requirement is satisfied.') + cmdline.add_description('All response function files provided must contain the same number of unique b-values (lines),' + ' as well as the same number of coefficients per line.') + cmdline.add_description('As long as the number of unique b-values is identical across all input files,' + ' the response functions will be averaged.' + ' This is performed on the assumption that the actual acquired b-values are identical.' + ' This is however impossible for the responsemean command to determine based on the data provided;' + ' it is therefore up to the user to ensure that this requirement is satisfied.') cmdline.add_example_usage('Usage where all response functions are in the same directory:', 'responsemean input_response1.txt input_response2.txt input_response3.txt output_average_response.txt') cmdline.add_example_usage('Usage selecting response functions within a directory using a wildcard:', @@ -47,9 +47,9 @@ def usage(cmdline): #pylint: disable=unused-variable help='The output mean response function file') cmdline.add_argument('-legacy', action='store_true', - help='Use the legacy behaviour of former command "average_response": ' - 'average response function coefficients directly, ' - 'without compensating for global magnitude differences between input files') + help='Use the legacy behaviour of former command "average_response":' + ' average response function coefficients directly,' + ' without compensating for global magnitude differences between input files') diff --git a/python/lib/mrtrix3/dwi2mask/b02template.py b/python/lib/mrtrix3/dwi2mask/b02template.py index 019cea50ed..b086fe0e7b 100644 --- a/python/lib/mrtrix3/dwi2mask/b02template.py +++ b/python/lib/mrtrix3/dwi2mask/b02template.py @@ -54,16 +54,19 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser = subparsers.add_parser('b02template', parents=[base_parser]) parser.set_author('Robert E. Smith (robert.smith@florey.edu.au)') parser.set_synopsis('Register the mean b=0 image to a T2-weighted template to back-propagate a brain mask') - parser.add_description('This script currently assumes that the template image provided via the first input to the -template option is T2-weighted, ' + parser.add_description('This script currently assumes that the template image ' + 'provided via the first input to the -template option is T2-weighted, ' 'and can therefore be trivially registered to a mean b=0 image.') - parser.add_description('Command-line option -ants_options can be used with either the "antsquick" or "antsfull" software options. ' + parser.add_description('Command-line option -ants_options can be used ' + 'with either the "antsquick" or "antsfull" software options. ' 'In both cases, image dimensionality is assumed to be 3, ' 'and so this should be omitted from the user-specified options.' 'The input can be either a string ' '(encased in double-quotes if more than one option is specified), ' 'or a path to a text file containing the requested options. ' 'In the case of the "antsfull" software option, ' - 'one will require the names of the fixed and moving images that are provided to the antsRegistration command: ' + 'one will require the names of the fixed and moving images ' + 'that are provided to the antsRegistration command: ' 'these are "template_image.nii" and "bzero.nii" respectively.') parser.add_citation('M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. ' 'FSL. ' diff --git a/python/lib/mrtrix3/dwi2mask/consensus.py b/python/lib/mrtrix3/dwi2mask/consensus.py index 10a4b0c7f5..db9995bcd0 100644 --- a/python/lib/mrtrix3/dwi2mask/consensus.py +++ b/python/lib/mrtrix3/dwi2mask/consensus.py @@ -33,7 +33,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable options.add_argument('-algorithms', type=str, nargs='+', - help='Provide a (space- or comma-separated) list of dwi2mask algorithms that are to be utilised') + help='Provide a (space- or comma-separated) list ' + 'of dwi2mask algorithms that are to be utilised') options.add_argument('-masks', type=app.Parser.ImageOut(), metavar='image', @@ -46,7 +47,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable options.add_argument('-threshold', type=app.Parser.Float(0.0, 1.0), default=DEFAULT_THRESHOLD, - help='The fraction of algorithms that must include a voxel for that voxel to be present in the final mask ' + help='The fraction of algorithms that must include a voxel ' + 'for that voxel to be present in the final mask ' f'(default: {DEFAULT_THRESHOLD})') diff --git a/python/lib/mrtrix3/dwi2mask/mtnorm.py b/python/lib/mrtrix3/dwi2mask/mtnorm.py index 0503d881c1..f99a41dc81 100644 --- a/python/lib/mrtrix3/dwi2mask/mtnorm.py +++ b/python/lib/mrtrix3/dwi2mask/mtnorm.py @@ -38,9 +38,10 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable 'and subsequent mask image cleaning operations are performed.') parser.add_description('The operation of this script is a subset of that performed by the script "dwibiasnormmask". ' 'Many users may find that comprehensive solution preferable; ' - 'this dwi2mask algorithm is nevertheless provided to demonstrate specifically the mask estimation portion of that command.') - parser.add_description('The ODFs estimated within this optimisation procedure are by default of lower maximal spherical harmonic ' - 'degree than what would be advised for analysis. ' + 'this dwi2mask algorithm is nevertheless provided ' + 'to demonstrate specifically the mask estimation portion of that command.') + parser.add_description('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.') parser.add_citation('Jeurissen, B; Tournier, J-D; Dhollander, T; Connelly, A & Sijbers, J. ' diff --git a/python/lib/mrtrix3/dwi2mask/trace.py b/python/lib/mrtrix3/dwi2mask/trace.py index 923621baf7..aa760e9dde 100644 --- a/python/lib/mrtrix3/dwi2mask/trace.py +++ b/python/lib/mrtrix3/dwi2mask/trace.py @@ -46,7 +46,9 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable iter_options = parser.add_argument_group('Options for turning "dwi2mask trace" into an iterative algorithm') iter_options.add_argument('-iterative', action='store_true', - help='(EXPERIMENTAL) Iteratively refine the weights for combination of per-shell trace-weighted images prior to thresholding') + help='(EXPERIMENTAL) ' + 'Iteratively refine the weights for combination of per-shell trace-weighted images ' + 'prior to thresholding') iter_options.add_argument('-max_iters', type=app.Parser.Int(1), default=DEFAULT_MAX_ITERS, diff --git a/python/lib/mrtrix3/dwi2response/dhollander.py b/python/lib/mrtrix3/dwi2response/dhollander.py index 4dbb1ce73a..a0b2634d9d 100644 --- a/python/lib/mrtrix3/dwi2response/dhollander.py +++ b/python/lib/mrtrix3/dwi2response/dhollander.py @@ -31,10 +31,13 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser.set_author('Thijs Dhollander (thijs.dhollander@gmail.com)') parser.set_synopsis('Unsupervised estimation of WM, GM and CSF response functions ' 'that does not require a T1 image (or segmentation thereof)') - parser.add_description('This is an improved version of the Dhollander et al. (2016) algorithm for unsupervised estimation of WM, GM and CSF response functions, ' - 'which includes the Dhollander et al. (2019) improvements for single-fibre WM response function estimation ' - '(prior to this update, ' - 'the "dwi2response tournier" algorithm had been utilised specifically for the single-fibre WM response function estimation step).') + parser.add_description('This is an improved version of the Dhollander et al. (2016) algorithm' + ' for unsupervised estimation of WM, GM and CSF response functions,' + ' which includes the Dhollander et al. (2019) improvements' + ' for single-fibre WM response function estimation' + ' (prior to this update,' + ' the "dwi2response tournier" algorithm had been utilised' + ' specifically for the single-fibre WM response function estimation step).') parser.add_citation('Dhollander, T.; Raffelt, D. & Connelly, A. ' 'Unsupervised 3-tissue response function estimation from single-shell or multi-shell diffusion MR data without a co-registered T1 image. ' 'ISMRM Workshop on Breaking the Barriers of Diffusion MRI, 2016, 5') diff --git a/python/lib/mrtrix3/dwi2response/tax.py b/python/lib/mrtrix3/dwi2response/tax.py index 7310f473a5..2fb4248517 100644 --- a/python/lib/mrtrix3/dwi2response/tax.py +++ b/python/lib/mrtrix3/dwi2response/tax.py @@ -24,7 +24,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser = subparsers.add_parser('tax', parents=[base_parser]) parser.set_author('Robert E. Smith (robert.smith@florey.edu.au)') - parser.set_synopsis('Use the Tax et al. (2014) recursive calibration algorithm for single-fibre voxel selection and response function estimation') + parser.set_synopsis('Use the Tax et al. (2014) recursive calibration algorithm' + ' for single-fibre voxel selection and response function estimation') parser.add_citation('Tax, C. M.; Jeurissen, B.; Vos, S. B.; Viergever, M. A. & Leemans, A. ' 'Recursive calibration of the fiber response function for spherical deconvolution of diffusion MRI data. ' 'NeuroImage, 2014, 86, 67-80') diff --git a/python/lib/mrtrix3/dwi2response/tournier.py b/python/lib/mrtrix3/dwi2response/tournier.py index 333c48a603..7ef04eb76c 100644 --- a/python/lib/mrtrix3/dwi2response/tournier.py +++ b/python/lib/mrtrix3/dwi2response/tournier.py @@ -24,7 +24,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser = subparsers.add_parser('tournier', parents=[base_parser]) parser.set_author('Robert E. Smith (robert.smith@florey.edu.au)') - parser.set_synopsis('Use the Tournier et al. (2013) iterative algorithm for single-fibre voxel selection and response function estimation') + parser.set_synopsis('Use the Tournier et al. (2013) iterative algorithm' + ' for single-fibre voxel selection and response function estimation') parser.add_citation('Tournier, J.-D.; Calamante, F. & Connelly, A. ' 'Determination of the appropriate b-value and number of gradient directions for high-angular-resolution diffusion-weighted imaging. ' 'NMR Biomedicine, 2013, 26, 1775-1786') diff --git a/python/lib/mrtrix3/dwibiascorrect/ants.py b/python/lib/mrtrix3/dwibiascorrect/ants.py index 784e890ee9..4fbf2c7233 100644 --- a/python/lib/mrtrix3/dwibiascorrect/ants.py +++ b/python/lib/mrtrix3/dwibiascorrect/ants.py @@ -21,7 +21,8 @@ OPT_N4_BIAS_FIELD_CORRECTION = { 's': ('4','shrink-factor applied to spatial dimensions'), - 'b': ('[100,3]','[initial mesh resolution in mm, spline order] This value is optimised for human adult data and needs to be adjusted for rodent data.'), + 'b': ('[100,3]','[initial mesh resolution in mm, spline order]' + ' This value is optimised for human adult data and needs to be adjusted for rodent data.'), 'c': ('[1000,0.0]', '[numberOfIterations,convergenceThreshold]')} diff --git a/python/lib/mrtrix3/dwibiascorrect/mtnorm.py b/python/lib/mrtrix3/dwibiascorrect/mtnorm.py index 59bd443628..d86125f9bf 100644 --- a/python/lib/mrtrix3/dwibiascorrect/mtnorm.py +++ b/python/lib/mrtrix3/dwibiascorrect/mtnorm.py @@ -22,8 +22,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser = subparsers.add_parser('mtnorm', parents=[base_parser]) - parser.set_author('Robert E. Smith (robert.smith@florey.edu.au) ' - 'and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') + parser.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') parser.set_synopsis('Perform DWI bias field correction using the "mtnormalise" command') parser.add_description('This algorithm bases its operation almost entirely on the utilisation of multi-tissue ' 'decomposition information to estimate an underlying B1 receive field, ' diff --git a/python/lib/mrtrix3/dwinormalise/mtnorm.py b/python/lib/mrtrix3/dwinormalise/mtnorm.py index 49f31a085d..e8e01647b3 100644 --- a/python/lib/mrtrix3/dwinormalise/mtnorm.py +++ b/python/lib/mrtrix3/dwinormalise/mtnorm.py @@ -26,8 +26,8 @@ def usage(base_parser, subparsers): #pylint: disable=unused-variable parser = subparsers.add_parser('mtnorm', parents=[base_parser]) - parser.set_author('Robert E. Smith (robert.smith@florey.edu.au) ' - 'and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') + parser.set_author('Robert E. Smith (robert.smith@florey.edu.au)' + ' and Arshiya Sangchooli (asangchooli@student.unimelb.edu.au)') parser.set_synopsis('Normalise a DWI series to the estimated b=0 CSF intensity') parser.add_description('This algorithm determines an appropriate global scaling factor to apply to a DWI series ' 'such that after the scaling is applied, '