Utilities for running various MRtrix3’s DWI preprocessing tools

designer.preprocessing.mrpreproc.brainmask(input, output, thresh=0.25, nthreads=None, force=False, verbose=False)

Creates a brainmask using FSL’s Brain Extraction Tool (BET) and MRtrix3’s file manipulation tools.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .nii brainmask file

  • thresh (float) – BET threshold ranging from 0 to 1 (Default: 0.25)

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.csfmask(input, output, method='fsl', coeff=2, thresh=0.25, nthreads=None, force=False, verbose=False)

Creates a cerebral spinal fluid (CSF) mask from FSL’s FAST tool.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .nii CSF mask file

  • method (str, optional) – Define method to use for computing a CSF mask. ‘fsl’ relies on FSL FAST segmentation, and adc uses pseudo-diffusion coefficient more than 2 (default) to compute a mask

  • coeff (float, optional) – Diffusion coefficient to use in thresholding a pseudo-diffusion map to estimate CSF (Default: 2)

  • thresh (float, optional) – BET threshold ranging from 0 to 1 (Default: 0.25)

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.degibbs(input, output, nthreads=None, force=False, verbose=False)

Runs MRtrix3’s mrdegibbs command with optimal parameters for PyDesigner.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.denoise(input, output, noisemap=True, extent='5,5,5', nthreads=None, force=True, verbose=False)

Runs MRtrix3’s dwidenoise command with optimal parameters for PyDesigner.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • noisemap (bool, optional) – Specify whether or not to save the noisemap as a nifti file (Default: True)

  • extent (str, optional) – Set the window size of the denoising filter. (Default: ‘5,5,5’)

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.dwiextract(input, output, start, end, nthreads=None, force=False, verbose=False)

Extracts a range of volumes from input .mif file in the start:end range. Take note that the first volume starts with 0.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output file, usually .mif or .nii

  • start (int) – Starting index, inclusive

  • end (int) – Ending index, inclusive

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.epiboost(input, output, num=1, nthreads=None, force=False, verbose=False)

Analyzes an input .mif’s PE direction to split into two different phase encoding (PE) DWIs. B0s from opposing PE are then extracted and concatenated with the DWI. This reduces the number of B0s used in undistortion for a better and speedier estimation of the distortion field.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • num (int) – Number of B0s pairs to use in EPI correction (Default: 1)

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.extractbzero(input, output, nthreads=None, force=False, verbose=False)

Extracts only bzero shells from an input mif file.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.extractmeanbzero(input, output, nthreads=None, force=False, verbose=False)

Extracts average B0 from all B0 shells, with NaNs removed.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif or .nii file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.extractmeanshell(input, output, shell, nthreads=None, force=False, verbose=False)

Extracts mean of specified from an input mif file.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • shell (int) – Approximate b-value to extract

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.extractnonbzero(input, output, nthreads=None, force=False, verbose=False)

Extracts only non-bzero shells from an input mif file.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.extractshell(input, output, shell, nthreads=None, force=False, verbose=False)

Extracts specified shell from an input mif file.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • shell (int) – Approximate b-value to extract

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.miftonii(input, output, nthreads=None, force=True, verbose=False)

Converts input .mif images to output .nii images

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .nii file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

See also

niitomif

designer.preprocessing.mrpreproc.niitomif(input, output, nthreads=None, force=True, verbose=False)

Converts input .nii images to output .nif images provided that all BVEC, BVAL and JSON files are provided and named same as input .nii

Parameters

  • input (str) – Path to input .nii file

  • output (str) – Path to output .mif file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

See also

miftonii

designer.preprocessing.mrpreproc.reslice(input, output, size, interp='linear', nthreads=None, force=False, verbose=False)

Reslices input image to target voxel size

Parameters

  • input (str) – Path to input file; .mif or .nii

  • output (str) – Path to output file; .mif or .nii

  • size (tuple of float) – x, y, z voxel size in mm or output dimensions.

  • interp (str, {‘linear’, ‘nearest’, ‘cubic’ , ‘sinc’}, optional) – set the interpolation method to use when resizing (Default: ‘linear’)

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

Notes

If any of the axes in size is specified to be over 9 mm, this functions reslices to defined output dimensions, instead of voxel size. This is done to automatically reslice with minimal user input, and also because voxel size beyond 9 mm in unrealistic.

Additionally, if target resolution is the same as input file’s resolution, reslicing is skipped but the output file is still generated.

designer.preprocessing.mrpreproc.riciancorrect(input, output, noise=None)

Performs Rician correction on input .mif

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • noise (str) – Path to noise map from dwidenoise in .nii format (Default: None)

Return type

None; writes out file

designer.preprocessing.mrpreproc.smooth(input, output, csfname=None, fwhm=1.25, size=5)

Performs Gaussian smoothing on input .mif image

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • csfname (str) – Path to CSF mask file in .nii format

  • fwhm (float) – The full width half max in voxels to be smoothed (Default: 1.25)

Return type

None; writes out file

designer.preprocessing.mrpreproc.stride_match(target, moving, output, nthreads=None, force=True, verbose=False)

Matches strides on inputs target and moving by converting strides on moving image to those of target image.

Parameters

  • target (str) – Path to target image .nii or .mif file

  • moving (str) – Path to moving image .nii or .mif file

  • output (str) – Path to output .nii or .mif file

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file

designer.preprocessing.mrpreproc.undistort(input, output, rpe='rpe_header', epib0=1, qc=None, nthreads=None, force=False, verbose=False)

Runs MRtrix3’s distortion correction command with optimal parameters for PyDesigner.

Parameters

  • input (str) – Path to input .mif file

  • output (str) – Path to output .mif file

  • rpe (str, {‘rpe_header’, ‘rpe-pair’, ‘rpe_all, ‘rpe_all’}, optional) – Reverse phase encoding of the dataset. (Default: ‘rpe_header’)

  • epib0 (int) – Number of reverse PE dir B0 pairs to use in TOPUP correction (Default: 1)

  • qc (str) – Specify path to QC directior. No QC metrics generated if None

  • nthreads (int, optional) – Specify the number of threads to use in processing (Default: all available threads)

  • force (bool, optional) – Force overwrite of output files if pre-existing (Default:False)

  • verbose (bool, optional) – Specify whether to print console output (Default: False)

Return type

None; writes out file