Unwarping EPIs

Apply susceptibility distortion correction (SDC)

Abbreviations

fmap
fieldmap
VSM
voxel-shift map – a 3D nifti where displacements are in pixels (not mm)
DFM
displacements field map – a nifti warp file compatible with ANTs (mm)
fmriprep.workflows.fieldmap.unwarp.init_pepolar_unwarp_wf(fmaps, bold_file, omp_nthreads, layout=None, fmaps_pes=None, bold_file_pe=None, name='pepolar_unwarp_wf')[source]

This workflow takes in a set of EPI files with opposite phase encoding direction than the target file and calculates a displacements field (in other words, an ANTs-compatible warp file).

This procedure works if there is only one ‘_epi’ file is present (as long as it has the opposite phase encoding direction to the target file). The target file will be used to estimate the field distortion. However, if there is another ‘_epi’ file present with a matching phase encoding direction to the target it will be used instead.

Currently, different phase encoding dimension in the target file and the ‘_epi’ file(s) (for example ‘i’ and ‘j’) is not supported.

The warp field correcting for the distortions is estimated using AFNI’s 3dQwarp, with displacement estimation limited to the target file phase encoding direction.

It also calculates a new mask for the input dataset that takes into account the distortions.

../_images/unwarping-1.png

(Source code, png, svg, pdf)

Inputs

in_reference
the reference image
in_reference_brain
the reference image skullstripped
in_mask
a brain mask corresponding to in_reference
name_source
not used, kept for signature compatibility with init_sdc_unwarp_wf

Outputs

out_reference
the in_reference after unwarping
out_reference_brain
the in_reference after unwarping and skullstripping
out_warp
the corresponding DFM compatible with ANTs
out_mask
mask of the unwarped input file
out_mask_report
reportlet for the skullstripping
fmriprep.workflows.fieldmap.unwarp.init_prepare_epi_wf(omp_nthreads, name='prepare_epi_wf')[source]

This workflow takes in a set of EPI files with with the same phase encoding direction and returns a single 3D volume ready to be used in field distortion estimation.

The procedure involves: estimating a robust template using FreeSurfer’s ‘mri_robust_template’, bias field correction using ANTs N4BiasFieldCorrection and AFNI 3dUnifize, skullstripping using FSL BET and AFNI 3dAutomask, and rigid coregistration to the reference using ANTs.

../_images/unwarping-2.png

(Source code, png, svg, pdf)

Inputs

fmaps
list of 3D or 4D NIfTI images
ref_brain
coregistration reference (skullstripped and bias field corrected)

Outputs

out_file
single 3D NIfTI file
fmriprep.workflows.fieldmap.unwarp.init_sdc_unwarp_wf(reportlets_dir, omp_nthreads, fmap_bspline, fmap_demean, debug, name='sdc_unwarp_wf')[source]

This workflow takes in a displacements fieldmap and calculates the corresponding displacements field (in other words, an ANTs-compatible warp file).

It also calculates a new mask for the input dataset that takes into account the distortions. The mask is restricted to the field of view of the fieldmap since outside of it corrections could not be performed.

../_images/unwarping-3.png

(Source code, png, svg, pdf)

Inputs

in_reference
the reference image
in_mask
a brain mask corresponding to in_reference
name_source
path to the original _bold file being unwarped
fmap
the fieldmap in Hz
fmap_ref
the reference (anatomical) image corresponding to fmap
fmap_mask
a brain mask corresponding to fmap

Outputs

out_reference
the in_reference after unwarping
out_reference_brain
the in_reference after unwarping and skullstripping
out_warp
the corresponding DFM compatible with ANTs
out_jacobian
the jacobian of the field (for drop-out alleviation)
out_mask
mask of the unwarped input file
out_mask_report
reportled for the skullstripping