dwi2mask overhaul (replacement PR)

.gitignore

@@ -31,6 +31,7 @@ build.*
 /dev/
 /bin/
 /tmp/
+/compiled_docs/
 /.vscode/
 .cproject
 .idea

bin/dwi2mask

@@ -0,0 +1,103 @@
+#!/usr/bin/python3
+
+# Copyright (c) 2008-2021 the MRtrix3 contributors.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Covered Software is provided under this License on an "as is"
+# basis, without warranty of any kind, either expressed, implied, or
+# statutory, including, without limitation, warranties that the
+# Covered Software is free of defects, merchantable, fit for a
+# particular purpose or non-infringing.
+# See the Mozilla Public License v. 2.0 for more details.
+#
+# For more details, see http://www.mrtrix.org/.
+
+
+
+def usage(cmdline): #pylint: disable=unused-variable
+  from mrtrix3 import algorithm, app #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_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\'.')
+
+  # General options
+  #common_options = cmdline.add_argument_group('General dwi2mask options')
+  app.add_dwgrad_import_options(cmdline)
+
+  # Import the command-line settings for all algorithms found in the relevant directory
+  algorithm.usage(cmdline)
+
+
+
+def execute(): #pylint: disable=unused-variable
+  from mrtrix3 import MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
+  from mrtrix3 import algorithm, app, image, path, run #pylint: disable=no-name-in-module, import-outside-toplevel
+
+  # Find out which algorithm the user has requested
+  alg = algorithm.get_module(app.ARGS.algorithm)
+
+  app.check_output_path(app.ARGS.output)
+
+  input_header = image.Header(path.from_user(app.ARGS.input, False))
+  image.check_3d_nonunity(input_header)
+  grad_import_option = app.read_dwgrad_import_options()
+  if not grad_import_option and 'dw_scheme' not in input_header.keyval():
+    raise MRtrixError('Script requires diffusion gradient table: '
+                      'either in image header, or using -grad / -fslgrad option')
+
+  app.make_scratch_dir()
+
+  # Get input data into the scratch directory
+  run.command('mrconvert ' + path.from_user(app.ARGS.input) + ' ' + path.to_scratch('input.mif')
+              + ' -strides 0,0,0,1' + grad_import_option)
+  alg.get_inputs()
+
+  app.goto_scratch_dir()
+
+  # Generate a mean b=0 image (common task in many algorithms)
+  if alg.needs_mean_bzero():
+    run.command('dwiextract input.mif -bzero - | '
+                'mrmath - mean - -axis 3 | '
+                'mrconvert - bzero.nii -strides +1,+2,+3')
+
+  # Get a mask of voxels for which the DWI data are valid
+  #   (want to ensure that no algorithm includes any voxels where
+  #   there is no valid DWI data, regardless of how they operate)
+  run.command('mrmath input.mif max - -axis 3 | '
+              'mrthreshold - -abs 0 -comparison gt input_pos_mask.mif')
+
+  # Make relative strides of three spatial axes of output mask equivalent
+  #   to input DWI; this may involve decrementing magnitude of stride
+  #   if the input DWI is volume-contiguous
+  strides = image.Header('input.mif').strides()[0:3]
+  strides = [(abs(value) + 1 - min(abs(v) for v in strides)) * (-1 if value < 0 else 1) for value in strides]
+
+  # From here, the script splits depending on what algorithm is being used
+  # The return value of the execute() function should be the name of the
+  #   image in the scratch directory that is to be exported
+  mask_path = alg.execute()
+
+  # Before exporting the mask image, get a mask of voxels for which
+  #   the DWI data are valid
+  #   (want to ensure that no algorithm includes any voxels where
+  #   there is no valid DWI data, regardless of how they operate)
+  run.command('mrcalc '
+              + mask_path
+              + ' input_pos_mask.mif -mult -'
+              + ' |'
+              + ' mrconvert - '
+              + path.from_user(app.ARGS.output)
+              + ' -strides ' + ','.join(str(value) for value in strides),
+              mrconvert_keyval=path.from_user(app.ARGS.input, False),
+              force=app.FORCE_OVERWRITE)
+
+
+
+# Execute the script
+import mrtrix3  #pylint: disable=wrong-import-position
+mrtrix3.execute() #pylint: disable=no-member

bin/dwi2response

@@ -42,7 +42,7 @@ def usage(cmdline): #pylint: disable=unused-variable
 
 
 def execute(): #pylint: disable=unused-variable
-  from mrtrix3 import MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
+  from mrtrix3 import CONFIG, MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
   from mrtrix3 import algorithm, app, image, path, run #pylint: disable=no-name-in-module, import-outside-toplevel
 
   # Find out which algorithm the user has requested
@@ -106,7 +106,7 @@ def execute(): #pylint: disable=unused-variable
       raise MRtrixError('Provided mask image needs to be a 3D image')
   else:
     app.console('Computing brain mask (dwi2mask)...')
-    run.command('dwi2mask dwi.mif mask.mif', show=False)
+    run.command('dwi2mask ' + CONFIG.get('Dwi2maskAlgorithm', 'legacy') + ' dwi.mif mask.mif', show=False)
 
   if not image.statistics('mask.mif', mask='mask.mif').count:
     raise MRtrixError(('Provided' if app.ARGS.mask else 'Generated') + ' mask image does not contain any voxels')

bin/dwibiascorrect

@@ -32,7 +32,7 @@ def usage(cmdline): #pylint: disable=unused-variable
 
 
 def execute(): #pylint: disable=unused-variable
-  from mrtrix3 import MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
+  from mrtrix3 import CONFIG, MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
   from mrtrix3 import algorithm, app, image, path, run #pylint: disable=no-name-in-module, import-outside-toplevel
 
   # Find out which algorithm the user has requested
@@ -67,7 +67,7 @@ def execute(): #pylint: disable=unused-variable
     if not image.match('in.mif', 'mask.mif', up_to_dim=3):
       raise MRtrixError('Provided mask image does not match input DWI')
   else:
-    run.command('dwi2mask in.mif mask.mif')
+    run.command('dwi2mask ' + CONFIG.get('Dwi2maskAlgorithm', 'legacy') + ' in.mif mask.mif')
 
   # From here, the script splits depending on what estimation algorithm is being used
   alg.execute()

bin/dwifslpreproc

@@ -807,7 +807,7 @@ def execute(): #pylint: disable=unused-variable
 
   # Need gradient table if running dwi2mask after applytopup to derive a brain mask for eddy
   run.command('mrinfo dwi.mif -export_grad_mrtrix grad.b')
-
+  dwi2mask_algo = CONFIG.get('Dwi2maskAlgorithm', 'legacy')
 
   eddy_in_topup_option = ''
   dwi_post_eddy_crop_option = ''
@@ -911,10 +911,18 @@ def execute(): #pylint: disable=unused-variable
 
     # Use the initial corrected volumes to derive a brain mask for eddy
     if not app.ARGS.eddy_mask:
+
+      dwi2mask_out_path = 'dwi2mask_out.mif'
       if len(applytopup_image_list) == 1:
-        run.command('dwi2mask ' + applytopup_image_list[0] + ' - | maskfilter - dilate - | mrconvert - eddy_mask.nii -datatype float32 -strides -1,+2,+3')
+        dwi2mask_in_path = applytopup_image_list[0]
       else:
-        run.command('mrcat ' + ' '.join(applytopup_image_list) + ' - -axis 3 | dwi2mask - - | maskfilter - dilate - | mrconvert - eddy_mask.nii -datatype float32 -strides -1,+2,+3')
+        dwi2mask_in_path = 'dwi2mask_in.mif'
+        run.command('mrcat ' + ' '.join(applytopup_image_list) + ' ' + dwi2mask_in_path + ' -axis 3')
+      run.command('dwi2mask ' + dwi2mask_algo + ' ' + dwi2mask_in_path + ' ' + dwi2mask_out_path)
+      run.command('maskfilter ' + dwi2mask_out_path + ' dilate - | mrconvert - eddy_mask.nii -datatype float32 -strides -1,+2,+3')
+      if len(applytopup_image_list) > 1:
+        app.cleanup(dwi2mask_in_path)
+      app.cleanup(dwi2mask_out_path)
 
     app.cleanup(applytopup_image_list)
 
@@ -924,7 +932,10 @@ def execute(): #pylint: disable=unused-variable
 
     # Generate a processing mask for eddy based on the uncorrected input DWIs
     if not app.ARGS.eddy_mask:
-      run.command('dwi2mask ' + dwi_path + ' - | maskfilter - dilate - | mrconvert - eddy_mask.nii -datatype float32 -strides -1,+2,+3')
+      dwi2mask_out_path = 'dwi2mask_out.mif'
+      run.command('dwi2mask ' + dwi2mask_algo + ' ' + dwi_path + ' ' + dwi2mask_out_path)
+      run.command('maskfilter ' + dwi2mask_out_path + ' dilate - | mrconvert - eddy_mask.nii -datatype float32 -strides -1,+2,+3')
+      app.cleanup(dwi2mask_out_path)
 
 
   # Use user supplied mask for eddy instead of one derived from the images using dwi2mask

bin/dwigradcheck

@@ -35,7 +35,7 @@ def usage(cmdline): #pylint: disable=unused-variable
 
 
 def execute(): #pylint: disable=unused-variable
-  from mrtrix3 import MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
+  from mrtrix3 import CONFIG, MRtrixError #pylint: disable=no-name-in-module, import-outside-toplevel
   from mrtrix3 import app, image, matrix, path, run #pylint: disable=no-name-in-module, import-outside-toplevel
 
   image_dimensions = image.Header(path.from_user(app.ARGS.input, False)).size()
@@ -87,7 +87,7 @@ def execute(): #pylint: disable=unused-variable
   # Note that gradient table must be explicitly loaded, since there may not
   #   be one in the image header (user may be relying on -grad or -fslgrad input options)
   if not os.path.exists('mask.mif'):
-    run.command('dwi2mask data.mif mask.mif -grad grad.b')
+    run.command('dwi2mask ' + CONFIG.get('Dwi2maskAlgorithm', 'legacy') + ' data.mif mask.mif -grad grad.b')
 
   # How many tracks are we going to generate?
   number_option = ' -select ' + str(app.ARGS.number)