Home · Quickstart · Documentation · Citation · NiPy

# workflows.dmri.fsl.epi

## `create_dmri_preprocessing()`

Link to code

Creates a workflow that chains the necessary pipelines to correct for motion, eddy currents, and, if selected, susceptibility artifacts in EPI dMRI sequences.

IMPORTANT NOTICE: this workflow rotates the b-vectors, so please be adviced that not all the dicom converters ensure the consistency between the resulting nifti orientation and the b matrix table (e.g. dcm2nii checks it).

### Example

    >>> nipype_dmri_preprocess = create_dmri_preprocessing('nipype_dmri_prep')
    >>> nipype_dmri_preprocess.inputs.inputnode.in_file = 'diffusion.nii'
    >>> nipype_dmri_preprocess.inputs.inputnode.in_bvec = 'diffusion.bvec'
    >>> nipype_dmri_preprocess.inputs.inputnode.ref_num = 0
    >>> nipype_dmri_preprocess.inputs.inputnode.fieldmap_mag = 'magnitude.nii'
    >>> nipype_dmri_preprocess.inputs.inputnode.fieldmap_pha = 'phase.nii'
    >>> nipype_dmri_preprocess.inputs.inputnode.te_diff = 2.46
    >>> nipype_dmri_preprocess.inputs.inputnode.epi_echospacing = 0.77
    >>> nipype_dmri_preprocess.inputs.inputnode.epi_rev_encoding = False
    >>> nipype_dmri_preprocess.inputs.inputnode.pi_accel_factor = True
    >>> nipype_dmri_preprocess.run()

Inputs:

    inputnode.in_file - The diffusion data
    inputnode.in_bvec - The b-matrix file, in FSL format and consistent with the in_file orientation
    inputnode.ref_num - The reference volume (a b=0 volume in dMRI)
    inputnode.fieldmap_mag - The magnitude of the fieldmap
    inputnode.fieldmap_pha - The phase difference of the fieldmap
    inputnode.te_diff - TE increment used (in msec.) on the fieldmap acquisition (generally 2.46ms for 3T scanners)
    inputnode.epi_echospacing - The EPI EchoSpacing parameter (in msec.)
    inputnode.epi_rev_encoding - True if reverse encoding was used (generally False)
    inputnode.pi_accel_factor - Parallel imaging factor (aka GRAPPA acceleration factor)
    inputnode.vsm_sigma - Sigma (in mm.) of the gaussian kernel used for in-slice smoothing of the deformation field (voxel shift map, vsm)

Outputs:

    outputnode.dmri_corrected
    outputnode.bvec_rotated

Optional arguments::
  use_fieldmap - True if there are fieldmap files that should be used (default True) fieldmap_registration - True if registration to fieldmap should be performed (default False)

### Graph

## `create_eddy_correct_pipeline()`

Link to code

Creates a pipeline that replaces eddy_correct script in FSL. It takes a series of diffusion weighted images and linearly co-registers them to one reference image. No rotation of the B-matrix is performed, so this pipeline should be executed after the motion correction pipeline.

### Example

    >>> nipype_eddycorrect = create_eddy_correct_pipeline('nipype_eddycorrect')
    >>> nipype_eddycorrect.inputs.inputnode.in_file = 'diffusion.nii'
    >>> nipype_eddycorrect.inputs.inputnode.ref_num = 0
    >>> nipype_eddycorrect.run()

Inputs:

    inputnode.in_file
    inputnode.ref_num

Outputs:

    outputnode.eddy_corrected

### Graph

## `create_epidewarp_pipeline()`

Link to code

Replaces the epidewarp.fsl script (http://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl) for susceptibility distortion correction of dMRI & fMRI acquired with EPI sequences and the fieldmap information (Jezzard et al., 1995) using FSL’s FUGUE. The registration to the (warped) fieldmap (strictly following the original script) is available using fieldmap_registration=True.

### Example

    >>> nipype_epicorrect = create_epidewarp_pipeline('nipype_epidewarp', fieldmap_registration=False)
    >>> nipype_epicorrect.inputs.inputnode.in_file = 'diffusion.nii'
    >>> nipype_epicorrect.inputs.inputnode.fieldmap_mag = 'magnitude.nii'
    >>> nipype_epicorrect.inputs.inputnode.fieldmap_pha = 'phase.nii'
    >>> nipype_epicorrect.inputs.inputnode.te_diff = 2.46
    >>> nipype_epicorrect.inputs.inputnode.epi_echospacing = 0.77
    >>> nipype_epicorrect.inputs.inputnode.epi_rev_encoding = False
    >>> nipype_epicorrect.inputs.inputnode.ref_num = 0
    >>> nipype_epicorrect.inputs.inputnode.pi_accel_factor = 1.0
    >>> nipype_epicorrect.run()

Inputs:

    inputnode.in_file - The volume acquired with EPI sequence
    inputnode.fieldmap_mag - The magnitude of the fieldmap
    inputnode.fieldmap_pha - The phase difference of the fieldmap
    inputnode.te_diff - Time difference between TE in ms.
    inputnode.epi_echospacing - The echo spacing (aka dwell time) in the EPI sequence
    inputnode.epi_ph_encoding_dir - The phase encoding direction in EPI acquisition (default y)
    inputnode.epi_rev_encoding - True if it is acquired with reverse encoding
    inputnode.pi_accel_factor - Acceleration factor used for EPI parallel imaging (GRAPPA)
    inputnode.vsm_sigma - Sigma value of the gaussian smoothing filter applied to the vsm (voxel shift map)
    inputnode.ref_num - The reference volume (B=0 in dMRI or a central frame in fMRI)

Outputs:

    outputnode.epi_corrected

Optional arguments:

    fieldmap_registration - True if registration to fieldmap should be done (default False)

### Graph

## `create_motion_correct_pipeline()`

Link to code

Creates a pipeline that corrects for motion artifact 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 (Leemans et al. 2009 - http://www.ncbi.nlm.nih.gov/pubmed/19319973), making use of the rotation matrix obtained by FLIRT.

IMPORTANT NOTICE: this workflow rotates the b-vectors, so please be adviced that not all the dicom converters ensure the consistency between the resulting nifti orientation and the b matrix table (e.g. dcm2nii checks it).

### Example

    >>> nipype_motioncorrect = create_motion_correct_pipeline('nipype_motioncorrect')
    >>> nipype_motioncorrect.inputs.inputnode.in_file = 'diffusion.nii'
    >>> nipype_motioncorrect.inputs.inputnode.in_bvec = 'diffusion.bvec'
    >>> nipype_motioncorrect.inputs.inputnode.ref_num = 0
    >>> nipype_motioncorrect.run()

Inputs:

    inputnode.in_file
    inputnode.ref_num
    inputnode.in_bvec

Outputs:

    outputnode.motion_corrected
    outputnode.out_bvec

### Graph

## `fieldmap_correction()`

Link to code

Fieldmap-based retrospective correction of EPI images for the susceptibility distortion artifact (Jezzard et al., 1995). Fieldmap images are assumed to be already registered to EPI data, and a brain mask is required.

Replaces the former workflow, still available as create_epidewarp_pipeline(). The difference with respect the epidewarp pipeline is that now the workflow uses the new fsl_prepare_fieldmap available as of FSL 5.0.

### Example

    >>> nipype_epicorrect = fieldmap_correction('nipype_epidewarp')
    >>> nipype_epicorrect.inputs.inputnode.in_file = 'diffusion.nii'
    >>> nipype_epicorrect.inputs.inputnode.in_mask = 'brainmask.nii'
    >>> nipype_epicorrect.inputs.inputnode.fieldmap_pha = 'phase.nii'
    >>> nipype_epicorrect.inputs.inputnode.fieldmap_mag = 'magnitude.nii'
    >>> nipype_epicorrect.inputs.inputnode.te_diff = 2.46
    >>> nipype_epicorrect.inputs.inputnode.epi_echospacing = 0.77
    >>> nipype_epicorrect.inputs.inputnode.encoding_direction = 'y'
    >>> nipype_epicorrect.run()

Inputs:

    inputnode.in_file - The volume acquired with EPI sequence
    inputnode.in_mask - A brain mask
    inputnode.fieldmap_pha - The phase difference map from the fieldmapping, registered to in_file
    inputnode.fieldmap_mag - The magnitud maps (usually 4D, one magnitude per GRE scan)
                             from the fieldmapping, registered to in_file
    inputnode.te_diff - Time difference in msec. between TE in ms of the fieldmapping (usually a GRE sequence).
    inputnode.epi_echospacing - The effective echo spacing (aka dwell time) in msec. of the EPI sequence. If
                                EPI was acquired with parallel imaging, then the effective echo spacing is
                                eff_es = es / acc_factor.
    inputnode.encoding_direction - The phase encoding direction in EPI acquisition (default y)
    inputnode.vsm_sigma - Sigma value of the gaussian smoothing filter applied to the vsm (voxel shift map)

Outputs:

    outputnode.epi_corrected
    outputnode.out_vsm

### Graph

## `topup_correction()`

Link to code

> Corrects for susceptibilty distortion of EPI images when one reverse encoding dataset has been acquired

### Example

    >>> nipype_epicorrect = topup_correction('nipype_topup')
    >>> nipype_epicorrect.inputs.inputnode.in_file_dir = 'epi.nii'
    >>> nipype_epicorrect.inputs.inputnode.in_file_rev = 'epi_rev.nii'
    >>> nipype_epicorrect.inputs.inputnode.encoding_direction = 'y'
    >>> nipype_epicorrect.inputs.inputnode.ref_num = 0
    >>> nipype_epicorrect.run()

Inputs::
  inputnode.in_file_dir - EPI volume acquired in ‘forward’ phase encoding inputnode.in_file_rev - EPI volume acquired in ‘reversed’ phase encoding inputnode.encoding_direction - Direction encoding of in_file_dir inputnode.ref_num - Identifier of the reference volumes (usually B0 volume)

Outputs:

    outputnode.epi_corrected

### Graph