workflows.dmri.fsl.artifacts

all_fmb_pipeline()

Link to code

Builds a pipeline including three artifact corrections: head-motion correction (HMC), susceptibility-derived distortion correction (SDC), and Eddy currents-derived distortion correction (ECC).

The displacement fields from each kind of distortions are combined. Thus, only one interpolation occurs between input data and result.

Warning

this workflow rotates the gradients table (b-vectors) [Leemans09].

Examples

>>> from nipype.workflows.dmri.fsl.artifacts import all_fmb_pipeline
>>> allcorr = all_fmb_pipeline()
>>> allcorr.inputs.inputnode.in_file = 'epi.nii'
>>> allcorr.inputs.inputnode.in_bval = 'diffusion.bval'
>>> allcorr.inputs.inputnode.in_bvec = 'diffusion.bvec'
>>> allcorr.inputs.inputnode.bmap_mag = 'magnitude.nii'
>>> allcorr.inputs.inputnode.bmap_pha = 'phase.nii'
>>> allcorr.inputs.inputnode.epi_param = 'epi_param.txt'
>>> allcorr.run() 

Graph

all_fsl_pipeline()

Link to code

Workflow that integrates FSL topup and eddy.

Warning

this workflow rotates the gradients table (b-vectors) [Leemans09].

Warning

this workflow does not perform jacobian modulation of each DWI [Jones10].

Examples

>>> from nipype.workflows.dmri.fsl.artifacts import all_fsl_pipeline
>>> allcorr = all_fsl_pipeline()
>>> allcorr.inputs.inputnode.in_file = 'epi.nii'
>>> allcorr.inputs.inputnode.alt_file = 'epi_rev.nii'
>>> allcorr.inputs.inputnode.in_bval = 'diffusion.bval'
>>> allcorr.inputs.inputnode.in_bvec = 'diffusion.bvec'
>>> allcorr.run() 

Graph

all_peb_pipeline()

Link to code

Builds a pipeline including three artifact corrections: head-motion correction (HMC), susceptibility-derived distortion correction (SDC), and Eddy currents-derived distortion correction (ECC).

Warning

this workflow rotates the gradients table (b-vectors) [Leemans09].

Examples

>>> from nipype.workflows.dmri.fsl.artifacts import all_peb_pipeline
>>> allcorr = all_peb_pipeline()
>>> allcorr.inputs.inputnode.in_file = 'epi.nii'
>>> allcorr.inputs.inputnode.alt_file = 'epi_rev.nii'
>>> allcorr.inputs.inputnode.in_bval = 'diffusion.bval'
>>> allcorr.inputs.inputnode.in_bvec = 'diffusion.bvec'
>>> allcorr.run() 

Graph

ecc_pipeline()

Link to code

ECC stands for Eddy currents correction.

Creates a pipeline that corrects for artifacts induced by Eddy currents in dMRI sequences. It takes a series of diffusion weighted images and linearly co-registers them to one reference image (the average of all b0s in the dataset).

DWIs are also modulated by the determinant of the Jacobian as indicated by [Jones10] and [Rohde04].

A list of rigid transformation matrices can be provided, sourcing from a hmc_pipeline() workflow, to initialize registrations in a motion free framework.

A list of affine transformation matrices is available as output, so that transforms can be chained (discussion here).

References

[Jones10]

(1, 2) Jones DK, The signal intensity must be modulated by the determinant of the Jacobian when correcting for eddy currents in diffusion MRI, Proc. ISMRM 18th Annual Meeting, (2010).

[Rohde04]

Rohde et al., Comprehensive Approach for Correction of Motion and Distortion in Diffusion-Weighted MRI, MRM 51:103-114 (2004).

Example

>>> from nipype.workflows.dmri.fsl.artifacts import ecc_pipeline
>>> ecc = ecc_pipeline()
>>> ecc.inputs.inputnode.in_file = 'diffusion.nii'
>>> ecc.inputs.inputnode.in_bval = 'diffusion.bval'
>>> ecc.inputs.inputnode.in_mask = 'mask.nii'
>>> ecc.run() 

Inputs:

inputnode.in_file - input dwi file
inputnode.in_mask - weights mask of reference image (a file with data range sin [0.0, 1.0], indicating the weight of each voxel when computing the metric.
inputnode.in_bval - b-values table
inputnode.in_xfms - list of matrices to initialize registration (from head-motion correction)

Outputs:

outputnode.out_file - corrected dwi file
outputnode.out_xfms - list of transformation matrices

Graph

hmc_pipeline()

Link to code

HMC stands for head-motion correction.

Creates a pipeline that corrects for head motion artifacts in dMRI sequences. It takes a series of diffusion weighted images and rigidly co-registers them to one reference image. Finally, the b-matrix is rotated accordingly [Leemans09] making use of the rotation matrix obtained by FLIRT.

Search angles have been limited to 4 degrees, based on results in [Yendiki13].

A list of rigid transformation matrices is provided, so that transforms can be chained. This is useful to correct for artifacts with only one interpolation process (as previously discussed here), and also to compute nuisance regressors as proposed by [Yendiki13].

Warning

This workflow rotates the b-vectors, so please be advised that not all the dicom converters ensure the consistency between the resulting nifti orientation and the gradients table (e.g. dcm2nii checks it).

References

[Leemans09]

(1, 2, 3, 4) Leemans A, and Jones DK, The B-matrix must be rotated when correcting for subject motion in DTI data, Magn Reson Med. 61(6):1336-49. 2009. doi: 10.1002/mrm.21890.

[Yendiki13]

(1, 2) Yendiki A et al., Spurious group differences due to head motion in a diffusion MRI study. Neuroimage. 21(88C):79-90. 2013. doi: 10.1016/j.neuroimage.2013.11.027

Example

>>> from nipype.workflows.dmri.fsl.artifacts import hmc_pipeline
>>> hmc = hmc_pipeline()
>>> hmc.inputs.inputnode.in_file = 'diffusion.nii'
>>> hmc.inputs.inputnode.in_bvec = 'diffusion.bvec'
>>> hmc.inputs.inputnode.in_bval = 'diffusion.bval'
>>> hmc.inputs.inputnode.in_mask = 'mask.nii'
>>> hmc.run() 

Inputs:

inputnode.in_file - input dwi file
inputnode.in_mask - weights mask of reference image (a file with data range in [0.0, 1.0], indicating the weight of each voxel when computing the metric.
inputnode.in_bvec - gradients file (b-vectors)
inputnode.ref_num (optional, default=0) index of the b0 volume that should be taken as reference

Outputs:

outputnode.out_file - corrected dwi file
outputnode.out_bvec - rotated gradient vectors table
outputnode.out_xfms - list of transformation matrices

Graph

remove_bias()

Link to code

This workflow estimates a single multiplicative bias field from the averaged b0 image, as suggested in [Jeurissen2014].

References

[Jeurissen2014]

Jeurissen B. et al., Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data. NeuroImage (2014). doi: 10.1016/j.neuroimage.2014.07.061

Example

>>> from nipype.workflows.dmri.fsl.artifacts import remove_bias
>>> bias = remove_bias()
>>> bias.inputs.inputnode.in_file = 'epi.nii'
>>> bias.inputs.inputnode.in_bval = 'diffusion.bval'
>>> bias.inputs.inputnode.in_mask = 'mask.nii'
>>> bias.run() 

Graph

sdc_fmb()

Link to code

SDC stands for susceptibility distortion correction. FMB stands for fieldmap-based.

The fieldmap based (FMB) method implements SDC by using a mapping of the B0 field as proposed by [Jezzard95]. This workflow uses the implementation of FSL (FUGUE). Phase unwrapping is performed using PRELUDE [Jenkinson03]. Preparation of the fieldmap is performed reproducing the script in FSL fsl_prepare_fieldmap.

Example

>>> from nipype.workflows.dmri.fsl.artifacts import sdc_fmb
>>> fmb = sdc_fmb()
>>> fmb.inputs.inputnode.in_file = 'diffusion.nii'
>>> fmb.inputs.inputnode.in_ref = list(range(0, 30, 6))
>>> fmb.inputs.inputnode.in_mask = 'mask.nii'
>>> fmb.inputs.inputnode.bmap_mag = 'magnitude.nii'
>>> fmb.inputs.inputnode.bmap_pha = 'phase.nii'
>>> fmb.inputs.inputnode.settings = 'epi_param.txt'
>>> fmb.run() 

Warning

Only SIEMENS format fieldmaps are supported.

References

[Jezzard95]

Jezzard P, and Balaban RS, Correction for geometric distortion in echo planar images from B0 field variations, MRM 34(1):65-73. (1995). doi: 10.1002/mrm.1910340111.

[Jenkinson03]

Jenkinson M., Fast, automated, N-dimensional phase-unwrapping algorithm, MRM 49(1):193-197, 2003, doi: 10.1002/mrm.10354.

Graph

sdc_peb()

Link to code

SDC stands for susceptibility distortion correction. PEB stands for phase-encoding-based.

The phase-encoding-based (PEB) method implements SDC by acquiring diffusion images with two different enconding directions [Andersson2003]. The most typical case is acquiring with opposed phase-gradient blips (e.g. A>>>P and P>>>A, or equivalently, -y and y) as in [Chiou2000], but it is also possible to use orthogonal configurations [Cordes2000] (e.g. A>>>P and L>>>R, or equivalently -y and x). This workflow uses the implementation of FSL (TOPUP).

Example

>>> from nipype.workflows.dmri.fsl.artifacts import sdc_peb
>>> peb = sdc_peb()
>>> peb.inputs.inputnode.in_file = 'epi.nii'
>>> peb.inputs.inputnode.alt_file = 'epi_rev.nii'
>>> peb.inputs.inputnode.in_bval = 'diffusion.bval'
>>> peb.inputs.inputnode.in_mask = 'mask.nii'
>>> peb.run() 

References

[Andersson2003]

Andersson JL et al., How to correct susceptibility distortions in spin-echo echo-planar images: application to diffusion tensor imaging. Neuroimage. 2003 Oct;20(2):870-88. doi: 10.1016/S1053-8119(03)00336-7

[Cordes2000]

Cordes D et al., Geometric distortion correction in EPI using two images with orthogonal phase-encoding directions, in Proc. ISMRM (8), p.1712, Denver, US, 2000.

[Chiou2000]

Chiou JY, and Nalcioglu O, A simple method to correct off-resonance related distortion in echo planar imaging, in Proc. ISMRM (8), p.1712, Denver, US, 2000.

Graph