Fieldmap estimation¶
Direct B0 mapping sequences¶
When the fieldmap is directly measured with a prescribed sequence (such as SE), we only need to calculate the corresponding B-Spline coefficients to adapt the fieldmap to the TOPUP tool. This procedure is described with more detail here.
This corresponds to the section 8.9.3 –fieldmap image (and one magnitude image)– of the BIDS specification.
-
fmriprep.workflows.fieldmap.fmap.
init_fmap_wf
(reportlets_dir, omp_nthreads, fmap_bspline, name='fmap_wf')[source]¶ Fieldmap workflow - when we have a sequence that directly measures the fieldmap we just need to mask it (using the corresponding magnitude image) to remove the noise in the surrounding air region, and ensure that units are Hz.
(Source code, png, svg, pdf)
Phase-difference B0 estimation¶
The field inhomogeneity inside the scanner (fieldmap) is proportional to the phase drift between two subsequent GRE sequence.
Fieldmap preprocessing workflow for fieldmap data structure 8.9.1 in BIDS 1.0.0: one phase diff and at least one magnitude image
-
fmriprep.workflows.fieldmap.phdiff.
init_phdiff_wf
(reportlets_dir, omp_nthreads, name='phdiff_wf')[source]¶ Estimates the fieldmap using a phase-difference image and one or more magnitude images corresponding to two or more GRE acquisitions. The original code was taken from nipype.
(Source code, png, svg, pdf)
Outputs:
outputnode.fmap_ref - The average magnitude image, skull-stripped outputnode.fmap_mask - The brain mask applied to the fieldmap outputnode.fmap - The estimated fieldmap in Hz
-
fmriprep.workflows.fieldmap.phdiff.
phdiff2fmap
(in_file, delta_te, out_file=None)[source]¶ Converts the input phase-difference map into a fieldmap in Hz, using the eq. (1) of [Hutton2002]:
\[\Delta B_0 (\text{T}^{-1}) = \frac{\Delta \Theta}{2\pi\gamma \Delta\text{TE}}\]In this case, we do not take into account the gyromagnetic ratio of the proton (\(\gamma\)), since it will be applied inside TOPUP:
\[\Delta B_0 (\text{Hz}) = \frac{\Delta \Theta}{2\pi \Delta\text{TE}}\][Hutton2002] Hutton et al., Image Distortion Correction in fMRI: A Quantitative Evaluation, NeuroImage 16(1):217-240, 2002. doi:10.1006/nimg.2001.1054.
Fieldmap-less estimation (experimental)¶
In the absence of direct measurements of fieldmap data, we provide an (experimental)
option to estimate the susceptibility distortion based on the ANTs symmetric
normalization (SyN) technique.
This feature may be enabled, using the --use-syn-sdc
flag, and will only be
applied if fieldmaps are unavailable.
During the evaluation phase, the --force-syn
flag will cause this estimation to
be performed in addition to fieldmap-based estimation, to permit the direct
comparison of the results of each technique.
Note that, even if --force-syn
is given, the functional outputs of FMRIPREP will
be corrected using the fieldmap-based estimates.
Feedback will be enthusiastically received.
-
fmriprep.workflows.bold.
init_nonlinear_sdc_wf
(bold_file, layout, freesurfer, bold2t1w_dof, template, omp_nthreads, atlas_threshold=3, name='nonlinear_sdc_wf')[source]¶ This workflow takes a skull-stripped T1w image and reference BOLD image and estimates a susceptibility distortion correction warp, using ANTs symmetric normalization (SyN) and the average fieldmap atlas described in [Treiber2016].
If the phase-encoding (PE) direction is known, the SyN deformation is restricted to that direction; otherwise, deformation fields are calculated for both the right-left and anterior-posterior directions, and selected based on the unwarped file that can be aligned to the T1w image with the lowest boundary-based registration (BBR) cost.
SyN deformation is also restricted to regions that are expected to have a >3mm (approximately 1 voxel) warp, based on the fieldmap atlas.
This technique is a variation on those developed in [Huntenburg2014] and [Wang2017].
(Source code, png, svg, pdf)
Inputs
- t1_brain
- skull-stripped, bias-corrected structural image
- bold_ref
- skull-stripped reference image
- t1_seg
- FAST segmentation white and gray matter, in native T1w space
- t1_2_mni_reverse_transform
- inverse registration transform of T1w image to MNI template
- subjects_dir
- FreeSurfer subjects directory (if applicable)
- subject_id
- FreeSurfer subject_id (if applicable)
Outputs
- out_reference_brain
- the
bold_ref
image after unwarping - out_warp
- the corresponding DFM compatible with ANTs
- out_mask
- mask of the unwarped input file
- out_mask_report
- reportlet for the skullstripping
[Huntenburg2014] Huntenburg, J. M. (2014) Evaluating Nonlinear Coregistration of BOLD EPI and T1w Images. Berlin: Master Thesis, Freie Universität. PDF. [Treiber2016] Treiber, J. M. et al. (2016) Characterization and Correction of Geometric Distortions in 814 Diffusion Weighted Images, PLoS ONE 11(3): e0152472. doi:10.1371/journal.pone.0152472. [Wang2017] Wang S, et al. (2017) Evaluation of Field Map and Nonlinear Registration Methods for Correction of Susceptibility Artifacts in Diffusion MRI. Front. Neuroinform. 11:17. doi:10.3389/fninf.2017.00017.