BRAIN_Mask
==========

Brain Masking, mask file will be added to the global variables in the result file

:Command: ``dmriprep``
:Module version: 0.1
:Module type: ``prep``
:Attributes: ``utility``
:Notes: `BRAIN_Mask README <https://github.com/NIRALUser/DTIPlayground/blob/master/dtiplayground/dmri/preprocessing/modules/BRAIN_Mask/README.md>`_
:Source: `dtiplayground/dmri/preprocessing/modules/BRAIN_Mask <https://github.com/NIRALUser/DTIPlayground/blob/master/dtiplayground/dmri/preprocessing/modules/BRAIN_Mask>`_

Protocol options
----------------

``method``
    Method to extract the brain

    :Type: ``list``
    :Default: ``fsl``
    :Choices:
        - ``fsl`` -- Use FSL for Brainmasking
        - ``synthstrip`` -- SynthStrip deep learning brain extraction (FreeSurfer's mri\_synthstrip if found, otherwise built in)
        - ``hdbet`` -- HD-BET deep learning brain extraction of the average b0 (hd-bet command, e.g. installed in a separate Python environment)
        - ``medianOtsu`` -- dipy median\_otsu, median filter and Otsu threshold of the average b0
        - ``customMask`` -- Use custom Brainmasking


``averagingMethod``
    Averaging method by which the source image is generated for the mask

    :Type: ``list``
    :Default: ``idwi``
    :Choices:
        - ``direct_average`` -- Direct average on baseline images. If no baseline is found then average whole volume
        - ``idwi`` -- Geometric mean of baseline images. If no baseline is found then whole images will be used.


``betFractionalThreshold``
    FSL bet fractional intensity threshold (-f, between 0 and 1); smaller values give a larger brain outline, larger values a smaller one

    :Type: ``float``
    :Default: ``0.5``
    :Used when: ``method`` is ``fsl``


``synthstripInput``
    Image SynthStrip is applied to

    :Type: ``list``
    :Default: ``ad``
    :Used when: ``method`` is ``synthstrip``
    :Choices:
        - ``ad`` -- Axial diffusivity of a DTI fit of the image (diffusion weighted volumes up to b=1500)
        - ``b0`` -- Average of the baseline (b=0) images


``synthstripBorder``
    Mask border threshold in mm (mri\_synthstrip -b); larger values give a larger mask

    :Type: ``float``
    :Default: ``1.0``
    :Used when: ``method`` is ``synthstrip``


``synthstripNoCSF``
    Exclude the CSF from the brain border (mri\_synthstrip --no-csf)

    :Type: ``boolean``
    :Default: ``false``
    :Used when: ``method`` is ``synthstrip``


``synthstripImplementation``
    FreeSurfer's mri\_synthstrip or the built-in version (torch; the model weights are downloaded on first use)

    :Type: ``list``
    :Default: ``auto``
    :Used when: ``method`` is ``synthstrip``
    :Choices:
        - ``auto`` -- FreeSurfer's mri\_synthstrip if found, otherwise the built-in version
        - ``freesurfer`` -- FreeSurfer's mri\_synthstrip (7.3+)
        - ``builtin`` -- SynthStrip network run in dtiplayground (torch)


``synthstripPath``
    FreeSurfer home directory or path of mri\_synthstrip; if empty, $FREESURFER\_HOME and the PATH are searched

    :Type: ``filepath-remote``
    :Default: not set
    :Used when: ``method`` is ``synthstrip``


``hdbetDevice``
    Device HD-BET runs on

    :Type: ``list``
    :Default: ``auto``
    :Used when: ``method`` is ``hdbet``
    :Choices:
        - ``auto`` -- GPU (cuda) if the torch of hd-bet sees one, otherwise CPU
        - ``cuda`` -- GPU (cuda)
        - ``cpu`` -- CPU


``hdbetTTA``
    Test time augmentation (mirroring); disabling it (--disable\_tta) is faster, mainly on CPU, at a slight cost in quality

    :Type: ``boolean``
    :Default: ``true``
    :Used when: ``method`` is ``hdbet``


``hdbetPath``
    Path of the hd-bet command or of the Python environment (or its bin directory) it is installed in; if empty, the environment of dtiplayground and the PATH are searched

    :Type: ``filepath-remote``
    :Default: not set
    :Used when: ``method`` is ``hdbet``


``medianOtsuRadius``
    Radius (in voxels) of the median filter applied before the Otsu threshold

    :Type: ``integer``
    :Default: ``4``
    :Used when: ``method`` is ``medianOtsu``


``medianOtsuNumpass``
    Number of median filter passes

    :Type: ``integer``
    :Default: ``4``
    :Used when: ``method`` is ``medianOtsu``


``medianOtsuDilate``
    Number of binary dilation iterations applied to the mask (0 for none)

    :Type: ``integer``
    :Default: ``0``
    :Used when: ``method`` is ``medianOtsu``


``modality``
    Modality of the input image

    :Type: ``list``
    :Default: ``t2``
    :Choices:
        - ``t2`` -- T2 Modality
        - ``fa`` -- Fractional Anistropy


``customMaskPath``
    Provide custom mask to override default

    :Type: ``filepath-remote``
    :Default: not set
    :Used when: ``method`` is ``customMask``