ENH dwi2mask: Python algorithm(s)

[Lestropie]

Initially proposed in #1964.

While naively seeming like a trivial operation, brain masking of DWI data can regularly go awry. This can often be the primary source of requirement of manual inspection / manipulation when processing large cohorts. The existing dwi2mask command is a fairly basic heuristic than can commonly produce unwanted results.

Propose instead providing a more general interface for the task of generating a brain mask based on DWI data, for which any one of a range of different algorithms can be selected. This will allow users to use the approach that works best for their particular data, as well as reduce the barrier of entry for contributions of further novel approaches and heuristics.

Tasks:

• [x] Port MRtrix3's existing dwi2mask algorithm from C++ to Python, by utilising existing MRtrix3 commands to perform the encapsulated steps.

  • [x] Make sure that results match the current implementation.

• [x] Utilise the algorithm module of the MRtrix3 Python APIs to generalise the interface and enable implementation of multiple alternative algorithms from a central interface (see dwi2response code and documentation for example)

• Implement wrappers for new dwi2mask algorithms, that will utilise non-MRtrix3 softwares but within an MRtrix3 interface and with automatic provenance tracking:

  • Interface to other DWI brain masking commands:

    • [x] Execute FSL's bet tool on the mean b=0 image

      • [x] Include option -rescale to change voxel sizes prior to running BET; apparently this assists when feeding rodent data to BET

    • [x] AFNI 3DAutomask (https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dAutomask.html)

      Progress: Lestropie/mrtrix3#3

    • [x] ANTs Brain Extraction: Lestropie/mrtrix3#6

    • x rbet (https://www.nitrc.org/projects/rbet/)

      I couldn't install this; I suspect the zip file from 2014 is not compatible with newer versions of make.

  • [x] Non-linear registration to a template image followed by transformation of the template mask to subject space

    • [x] Option to select what template image is used

    • [x] Option to select what registration software is used

  • Interface(s) to deep-learning-based brain extraction tools, e.g.

    • [x] HD-BET

    • Deep_MRI_brain_extraction

      Have wrapper code in place, but script seems to be taking an unreasonable amount of time. Will look into getting it to work on GPU. Lestropie/mrtrix3#4

    • deepbrain (https://pypi.org/project/deepbrain/)

      "Probability" image I'm getting from the functor isn't scaled between 0.0 and 1.0; also having trouble exporting the resulting data using nibabel. Lestropie/mrtrix3#5

  • [x] Generate per-shell mean image; (optionally) rescale shell mean image intensities across shells; perform mean operation across shells; obtain optimal threshold & clean appropriately. - Lestropie/mrtrix3#9

  • [x] "Consensus" algorithm, which invokes all available dwi2mask algorithms and produces a single brain mask based on the consensus of their results

    • [x] Option to output 4D image containing the masks from all algorithms executed, for manual assessment of consensus

• [x] Implement MRtrix configuration file entry that will allow MRtrix3 scripts that require a DWI brain mask, but for which the explicit providing of such a mask is optional, to automatically use whichever dwi2mask algorithm the user nominates within the configuration file.

• [ ] Collect and collate as much DWI data of varied quality / masking performance as possible for evaluation of options

  • [ ] Arrange data in BIDS format in preparation of automated processing

  • [ ] Quantitatively evaluate algorithms in comparison to manual brain masking

  • [ ] Consider alternative metrics for brain mask mismatch quantification https://github.com/Visceral-Project/EvaluateSegmentation

• [ ] Tool for visual assessment of masking efficacy across cohort

[Lestropie]

Current state of brain masking algorithms:

• [x] dwi2mask 3dautomask

• [x] dwi2mask ants

• [x] dwi2mask consensus

• dwi2mask deep3d (abandoned)

• dwi2mask deepbrain (abandoned)

• [x] dwi2mask fslbet

• [x] dwi2mask hdbet

• [x] dwi2mask legacy

• [x] dwi2mask template -software ants

• [x] dwi2mask template -software fsl

• [x] dwi2mask trace

[Lestropie]

Closing given the amount of content that has been merged to dev in #2197.

Interest in adding new algorithms to dwi2mask from this point can be made in individual dedicated issues.

Evaluation of efficacy of different masking algorithms across a wide range of data sources is being deferred due to a lack of investment at the time.