nipype.interfaces.mrtrix3.preprocess module

ACTPrepareFSL

Link to code

Bases: CommandLine

Wrapped executable: act_anat_prepare_fsl.

Generate anatomical information necessary for Anatomically Constrained Tractography (ACT).

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> prep = mrt.ACTPrepareFSL()
>>> prep.inputs.in_file = 'T1.nii.gz'
>>> prep.cmdline                               
'act_anat_prepare_fsl T1.nii.gz act_5tt.mif'
>>> prep.run()                                 
in_filea pathlike object or string representing an existing file

Input anatomical image. Maps to a command-line argument: %s (position: -2).

out_filea pathlike object or string representing a file

Output file after processing. Maps to a command-line argument: %s (position: -1). (Nipype default value: act_5tt.mif)

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

out_filea pathlike object or string representing an existing file

The output response file.

DWIBiasCorrect

Link to code

Bases: MRTrix3Base

Wrapped executable: dwibiascorrect.

Perform B1 field inhomogeneity correction for a DWI volume series.

For more information, see <https://mrtrix.readthedocs.io/en/latest/reference/scripts/dwibiascorrect.html>

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> bias_correct = mrt.DWIBiasCorrect()
>>> bias_correct.inputs.in_file = 'dwi.mif'
>>> bias_correct.inputs.use_ants = True
>>> bias_correct.cmdline
'dwibiascorrect ants dwi.mif dwi_biascorr.mif'
>>> bias_correct.run()                             
in_filea pathlike object or string representing an existing file

Input DWI image. Maps to a command-line argument: %s (position: -2).

use_antsa boolean

Use ANTS N4 to estimate the inhomogeneity field. Maps to a command-line argument: ants (position: 0). Mutually exclusive with inputs: use_fsl.

use_fsla boolean

Use FSL FAST to estimate the inhomogeneity field. Maps to a command-line argument: fsl (position: 0). Mutually exclusive with inputs: use_ants.

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

biasa pathlike object or string representing a file

Bias field. Maps to a command-line argument: -bias %s.

bval_scale‘yes’ or ‘no’

Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

grad_filea pathlike object or string representing an existing file

Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

grad_fsla tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)

(bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

in_bvala pathlike object or string representing an existing file

Bvals file in FSL format.

in_bveca pathlike object or string representing an existing file

Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

in_maska pathlike object or string representing a file

Input mask image for bias field estimation. Maps to a command-line argument: -mask %s.

nthreadsan integer

Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

out_bvala pathlike object or string representing a file

Export bval file in FSL format.

out_bveca pathlike object or string representing a file

Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

out_filea pathlike object or string representing a file

The output bias corrected DWI image. Maps to a command-line argument: %s (position: -1).

biasa pathlike object or string representing an existing file

The output bias field.

out_filea pathlike object or string representing an existing file

The output bias corrected DWI image.

DWIDenoise

Link to code

Bases: MRTrix3Base

Wrapped executable: dwidenoise.

Denoise DWI data and estimate the noise level based on the optimal threshold for PCA.

DWI data denoising and noise map estimation by exploiting data redundancy in the PCA domain using the prior knowledge that the eigenspectrum of random covariance matrices is described by the universal Marchenko Pastur distribution.

Important note: image denoising must be performed as the first step of the image processing pipeline. The routine will fail if interpolation or smoothing has been applied to the data prior to denoising.

Note that this function does not correct for non-Gaussian noise biases.

For more information, see <https://mrtrix.readthedocs.io/en/latest/reference/commands/dwidenoise.html>

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> denoise = mrt.DWIDenoise()
>>> denoise.inputs.in_file = 'dwi.mif'
>>> denoise.inputs.mask = 'mask.mif'
>>> denoise.inputs.noise = 'noise.mif'
>>> denoise.cmdline                               
'dwidenoise -mask mask.mif -noise noise.mif dwi.mif dwi_denoised.mif'
>>> denoise.run()                                 
in_filea pathlike object or string representing an existing file

Input DWI image. Maps to a command-line argument: %s (position: -2).

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

bval_scale‘yes’ or ‘no’

Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

extenta tuple of the form: (an integer, an integer, an integer)

Set the window size of the denoising filter. (default = 5,5,5). Maps to a command-line argument: -extent %d,%d,%d.

grad_filea pathlike object or string representing an existing file

Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

grad_fsla tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)

(bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

in_bvala pathlike object or string representing an existing file

Bvals file in FSL format.

in_bveca pathlike object or string representing an existing file

Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

maska pathlike object or string representing an existing file

Mask image. Maps to a command-line argument: -mask %s (position: 1).

noisea pathlike object or string representing a file

The output noise map. Maps to a command-line argument: -noise %s.

nthreadsan integer

Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

out_bvala pathlike object or string representing a file

Export bval file in FSL format.

out_bveca pathlike object or string representing a file

Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

out_filea pathlike object or string representing a file

The output denoised DWI image. Maps to a command-line argument: %s (position: -1).

noisea pathlike object or string representing an existing file

The output noise map.

out_filea pathlike object or string representing an existing file

The output denoised DWI image.

DWIPreproc

Link to code

Bases: MRTrix3Base

Wrapped executable: dwifslpreproc.

Perform diffusion image pre-processing using FSL’s eddy tool; including inhomogeneity distortion correction using FSL’s topup tool if possible

For more information, see <https://mrtrix.readthedocs.io/en/latest/reference/commands/dwifslpreproc.html>

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> preproc = mrt.DWIPreproc()
>>> preproc.inputs.in_file = 'dwi.mif'
>>> preproc.inputs.rpe_options = 'none'
>>> preproc.inputs.out_file = "preproc.mif"
>>> preproc.inputs.eddy_options = '--slm=linear --repol'     # linear second level model and replace outliers
>>> preproc.inputs.export_grad_mrtrix = True    # export final gradient table in MRtrix format
>>> preproc.inputs.ro_time = 0.165240   # 'TotalReadoutTime' in BIDS JSON metadata files
>>> preproc.inputs.pe_dir = 'j'     # 'PhaseEncodingDirection' in BIDS JSON metadata files
>>> preproc.cmdline
'dwifslpreproc dwi.mif preproc.mif -rpe_none -eddy_options "--slm=linear --repol" -export_grad_mrtrix grad.b -pe_dir j -readout_time 0.165240'
>>> preproc.run()                             
in_filea pathlike object or string representing an existing file

Input DWI image. Maps to a command-line argument: %s (position: 0).

out_filea pathlike object or string representing a file

Output file after preprocessing. Maps to a command-line argument: %s (position: 1). (Nipype default value: preproc.mif)

pe_dira string

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). Maps to a command-line argument: -pe_dir %s.

rpe_options‘none’ or ‘pair’ or ‘all’ or ‘header’

Specify acquisition phase-encoding design. “none” for no reversed phase-encoding image, “all” for all DWIs have opposing phase-encoding acquisition, “pair” for using a pair of b0 volumes for inhomogeneity field estimation only, and “header” for phase-encoding information can be found in the image header(s). Maps to a command-line argument: -rpe_%s (position: 2).

align_seepia boolean

Achieve alignment between the SE-EPI images used for inhomogeneity field estimation, and the DWIs. Maps to a command-line argument: -align_seepi.

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

bval_scale‘yes’ or ‘no’

Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

eddy_optionsa string

Manually provide additional command-line options to the eddy command. Maps to a command-line argument: -eddy_options "%s".

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

export_grad_fsla boolean

Export gradient files in FSL format. Maps to a command-line argument: -export_grad_fsl.

export_grad_mrtrixa boolean

Export new gradient files in mrtrix format. Maps to a command-line argument: -export_grad_mrtrix.

grad_filea pathlike object or string representing an existing file

Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

grad_fsla tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)

(bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

in_bvala pathlike object or string representing an existing file

Bvals file in FSL format.

in_bveca pathlike object or string representing an existing file

Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

in_epia pathlike object or string representing an existing file

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). Maps to a command-line argument: -se_epi %s.

nthreadsan integer

Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

out_bvala pathlike object or string representing a file

Export bval file in FSL format.

out_bveca pathlike object or string representing a file

Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

out_grad_fsla tuple of the form: (a pathlike object or string representing a file, a pathlike object or string representing a file)

Output (bvecs, bvals) gradients FSL format. Maps to a command-line argument: %s, %s. Requires inputs: export_grad_fsl.

out_grad_mrtrixa pathlike object or string representing a file

Name of new gradient file. Maps to a command-line argument: %s. Requires inputs: export_grad_mrtrix. (Nipype default value: grad.b)

ro_timea float

Total readout time of input series (in seconds). Maps to a command-line argument: -readout_time %f.

topup_optionsa string

Manually provide additional command-line options to the topup command. Maps to a command-line argument: -topup_options "%s".

out_filea pathlike object or string representing a file

Output preprocessed image series. Maps to a command-line argument: %s.

out_fsl_bvala pathlike object or string representing a file

Exported fsl gradient bval file. Maps to a command-line argument: %s. (Nipype default value: grad.bvals)

out_fsl_bveca pathlike object or string representing a file

Exported fsl gradient bvec file. Maps to a command-line argument: %s. (Nipype default value: grad.bvecs)

out_grad_mrtrixa pathlike object or string representing a file

Preprocessed gradient file in mrtrix3 format. Maps to a command-line argument: %s. (Nipype default value: grad.b)

MRDeGibbs

Link to code

Bases: MRTrix3Base

Wrapped executable: mrdegibbs.

Remove Gibbs ringing artifacts.

This application attempts to remove Gibbs ringing artefacts from MRI images using the method of local subvoxel-shifts proposed by Kellner et al.

This command is designed to run on data directly after it has been reconstructed by the scanner, before any interpolation of any kind has taken place. You should not run this command after any form of motion correction (e.g. not after dwipreproc). Similarly, if you intend running dwidenoise, you should run this command afterwards, since it has the potential to alter the noise structure, which would impact on dwidenoise’s performance.

Note that this method is designed to work on images acquired with full k-space coverage. Running this method on partial Fourier (‘half-scan’) data may lead to suboptimal and/or biased results, as noted in the original reference below. There is currently no means of dealing with this; users should exercise caution when using this method on partial Fourier data, and inspect its output for any obvious artefacts.

For more information, see <https://mrtrix.readthedocs.io/en/latest/reference/commands/mrdegibbs.html>

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> unring = mrt.MRDeGibbs()
>>> unring.inputs.in_file = 'dwi.mif'
>>> unring.cmdline
'mrdegibbs -axes 0,1 -maxW 3 -minW 1 -nshifts 20 dwi.mif dwi_unr.mif'
>>> unring.run()                                 
in_filea pathlike object or string representing an existing file

Input DWI image. Maps to a command-line argument: %s (position: -2).

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

axesa list of items which are a value of class ‘int’

Indicate the plane in which the data was acquired (axial = 0,1; coronal = 0,2; sagittal = 1,2. Maps to a command-line argument: -axes %s. (Nipype default value: [0, 1])

bval_scale‘yes’ or ‘no’

Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

grad_filea pathlike object or string representing an existing file

Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

grad_fsla tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)

(bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

in_bvala pathlike object or string representing an existing file

Bvals file in FSL format.

in_bveca pathlike object or string representing an existing file

Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

maxWan integer

Right border of window used for total variation (TV) computation (default = 3). Maps to a command-line argument: -maxW %d. (Nipype default value: 3)

minWan integer

Left border of window used for total variation (TV) computation (default = 1). Maps to a command-line argument: -minW %d. (Nipype default value: 1)

nshiftsan integer

Discretization of subpixel spacing (default = 20). Maps to a command-line argument: -nshifts %d. (Nipype default value: 20)

nthreadsan integer

Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

out_bvala pathlike object or string representing a file

Export bval file in FSL format.

out_bveca pathlike object or string representing a file

Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

out_filea pathlike object or string representing a file

The output unringed DWI image. Maps to a command-line argument: %s (position: -1).

out_filea pathlike object or string representing an existing file

The output unringed DWI image.

ReplaceFSwithFIRST

Link to code

Bases: CommandLine

Wrapped executable: fs_parc_replace_sgm_first.

Replace deep gray matter structures segmented with FSL FIRST in a FreeSurfer parcellation.

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> prep = mrt.ReplaceFSwithFIRST()
>>> prep.inputs.in_file = 'aparc+aseg.nii'
>>> prep.inputs.in_t1w = 'T1.nii.gz'
>>> prep.inputs.in_config = 'mrtrix3_labelconfig.txt'
>>> prep.cmdline                               
'fs_parc_replace_sgm_first aparc+aseg.nii T1.nii.gz mrtrix3_labelconfig.txt aparc+first.mif'
>>> prep.run()                                 
in_filea pathlike object or string representing an existing file

Input anatomical image. Maps to a command-line argument: %s (position: -4).

in_t1wa pathlike object or string representing an existing file

Input T1 image. Maps to a command-line argument: %s (position: -3).

out_filea pathlike object or string representing a file

Output file after processing. Maps to a command-line argument: %s (position: -1). (Nipype default value: aparc+first.mif)

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

in_configa pathlike object or string representing an existing file

Connectome configuration file. Maps to a command-line argument: %s (position: -2).

out_filea pathlike object or string representing an existing file

The output response file.

ResponseSD

Link to code

Bases: MRTrix3Base

Wrapped executable: dwi2response.

Estimate response function(s) for spherical deconvolution using the specified algorithm.

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> resp = mrt.ResponseSD()
>>> resp.inputs.in_file = 'dwi.mif'
>>> resp.inputs.algorithm = 'tournier'
>>> resp.inputs.grad_fsl = ('bvecs', 'bvals')
>>> resp.cmdline                               
'dwi2response tournier -fslgrad bvecs bvals dwi.mif wm.txt'
>>> resp.run()                                 

# We can also pass in multiple harmonic degrees in the case of multi-shell >>> resp.inputs.max_sh = [6,8,10] >>> resp.cmdline ‘dwi2response tournier -fslgrad bvecs bvals -lmax 6,8,10 dwi.mif wm.txt’

algorithm‘msmt_5tt’ or ‘dhollander’ or ‘tournier’ or ‘tax’

Response estimation algorithm (multi-tissue). Maps to a command-line argument: %s (position: 1).

in_filea pathlike object or string representing an existing file

Input DWI image. Maps to a command-line argument: %s (position: -5).

argsa string

Additional parameters to the command. Maps to a command-line argument: %s.

bval_scale‘yes’ or ‘no’

Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

csf_filea pathlike object or string representing a file

Output CSF response text file. Maps to a command-line argument: %s (position: -1).

environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

Environment variables. (Nipype default value: {})

gm_filea pathlike object or string representing a file

Output GM response text file. Maps to a command-line argument: %s (position: -2).

grad_filea pathlike object or string representing an existing file

Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

grad_fsla tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)

(bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

in_bvala pathlike object or string representing an existing file

Bvals file in FSL format.

in_bveca pathlike object or string representing an existing file

Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

in_maska pathlike object or string representing an existing file

Provide initial mask image. Maps to a command-line argument: -mask %s.

max_sha list of items which are an integer

Maximum harmonic degree of response function - single value for single-shell response, list for multi-shell response. Maps to a command-line argument: -lmax %s.

mtt_filea pathlike object or string representing a file

Input 5tt image. Maps to a command-line argument: %s (position: -4).

nthreadsan integer

Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

out_bvala pathlike object or string representing a file

Export bval file in FSL format.

out_bveca pathlike object or string representing a file

Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

wm_filea pathlike object or string representing a file

Output WM response text file. Maps to a command-line argument: %s (position: -3). (Nipype default value: wm.txt)

csf_filea pathlike object or string representing a file

Output CSF response text file. Maps to a command-line argument: %s.

gm_filea pathlike object or string representing a file

Output GM response text file. Maps to a command-line argument: %s.

wm_filea pathlike object or string representing a file

Output WM response text file. Maps to a command-line argument: %s.