qsiprep.workflows.fieldmap package

Fieldmap estimation and unwarping workflows

Automatic selection of the appropriate SDC method

If the dataset metadata indicate that more than one field map acquisition is IntendedFor (see BIDS Specification section 8.9) the following priority will be used:

1. Phase Encoding POLARity (PEPOLAR) techniques (or blip-up/blip-down)

2. Direct B0 mapping sequences

3. Phase-difference B0 estimation

4. Fieldmap-less estimation (experimental)

Table of behavior (fieldmap use-cases):

Fieldmaps found	use_syn	force_syn	Action
True		True	Fieldmaps + SyN
True		False	Fieldmaps
False		True	SyN
False	True	False	SyN
False	False	False	HMC only

qsiprep.workflows.fieldmap.base.init_sdc_wf(fieldmap_info, dwi_meta)

This workflow implements the heuristics to choose a SDC strategy. When no field map information is present within the BIDS inputs, the EXPERIMENTAL “fieldmap-less SyN” can be performed, using the --use-syn argument. When --force-syn is specified, then the “fieldmap-less SyN” is always executed and reported despite of other fieldmaps available with higher priority. In the latter case (some sort of fieldmap(s) is available and --force-syn is requested), then the SDC method applied is that with the highest priority.

(Source code)

Parameters:

• fmaps (list of pybids dicts) – A list of dictionaries with the available fieldmaps (and their metadata using the key 'metadata' for the case of epi fieldmaps)

• dwi_meta (dict) – BIDS metadata dictionary corresponding to the DWI run

Inputs:

• b0_ref – A b0 reference calculated at a previous stage

• b0_ref_brain – Same as above, but brain-masked

• b0_mask – Brain mask for the DWI run

• t1_brain – T1w image, brain-masked, for the fieldmap-less SyN method

• t1_2_mni_reverse_transform – MNI-to-T1w transform to map prior knowledge to the T1w fo the fieldmap-less SyN method

• template (str) – Name of template targeted by template output space

Outputs:

• b0_ref – An unwarped b0 reference

• b0_mask – The corresponding new mask after unwarping

• out_warp – The deformation field to unwarp the susceptibility distortions

• syn_b0_ref – If --force-syn, an unwarped b0 reference with this method (for reporting purposes)

• method – Name of the method used for SDC

• fieldmap_hz – The fieldmap in Hz for eddy

Phase Encoding POLARity (PEPOLAR) techniques

qsiprep.workflows.fieldmap.pepolar.init_extended_pepolar_report_wf(segment_t2w, omp_nthreads=1, name='extended_pepolar_report_wf')

qsiprep.workflows.fieldmap.pepolar.init_pepolar_unwarp_wf(dwi_meta, epi_fmaps, name='pepolar_unwarp_wf')

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.

(Source code)

Inputs

in_reference

the reference image

in_reference_brain

the reference image skullstripped

in_mask

a brain mask corresponding to in_reference

Outputs

out_reference

the in_reference after unwarping

out_warp

the corresponding DFM compatible with ANTs

qsiprep.workflows.fieldmap.pepolar.init_prepare_dwi_epi_wf(omp_nthreads, orientation='LPS', name='prepare_epi_wf')

This workflow takes in a set of dwi files with with the same phase encoding direction and returns a single 3D volume ready to be used in field distortion estimation. It removes b>0 volumes.

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.

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 8.9.2 in BIDS 1.0.0: two phases and at least one magnitude image

qsiprep.workflows.fieldmap.phdiff.init_phdiff_wf(phasetype='phasediff', name='phdiff_wf')

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)

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

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.

qsiprep.workflows.fieldmap.fmap.init_fmap_wf(name='fmap_wf')

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)

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 qsiprep will be corrected using the fieldmap-based estimates.

Feedback will be enthusiastically received.

class qsiprep.workflows.fieldmap.syn.ThreshAndBin(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

in_file (a pathlike object or string representing a file) – File to modify, atlas.

Optional Inputs:

atlas_threshold (an integer) – Threshold value.

Outputs:

out_file (a pathlike object or string representing an existing file) – File with threshold and binarization applied.

qsiprep.workflows.fieldmap.syn.init_syn_sdc_wf(bold_pe=None, atlas_threshold=2)

This workflow takes a skull-stripped T1w image and reference b0 image and estimates a susceptibility distortion correction warp, using ANTs symmetric normalization (SyN) and the average fieldmap atlas described in [Treiber2016].

SyN deformation is restricted to the phase-encoding (PE) direction. If no PE direction is specified, anterior-posterior PE is assumed.

SyN deformation is also restricted to regions that are expected to have a >2mm (approximately 1 voxel) warp, based on the fieldmap atlas.

This technique is a variation on those developed in [Huntenburg2014] and [Wang2017].

(Source code)

Inputs

b0_ref

reference image

templatestr

Name of template targeted by template output space

t1_brain

skull-stripped, bias-corrected structural image

t1_2_mni_reverse_transform

inverse registration transform of T1w image to MNI template

Outputs

out_reference

the bold_ref image after unwarping

out_reference_brain

the bold_ref_brain image after unwarping

out_warp

the corresponding DFM compatible with ANTs

out_mask

mask of the unwarped input file

Unwarping

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)

qsiprep.workflows.fieldmap.unwarp.init_fmap_unwarp_report_wf(name='fmap_unwarp_report_wf')

This workflow generates and saves a reportlet showing the effect of fieldmap unwarping a DWI image.

(Source code, png, svg, pdf)

Parameters:

name (str, optional) – Workflow name (default: fmap_unwarp_report_wf)

Inputs:

• in_pre – Reference image, before unwarping

• in_post – Reference image, after unwarping

• in_seg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)

• in_xfm – Affine transform from T1 space to b0 space (ITK format)

qsiprep.workflows.fieldmap.unwarp.init_sdc_unwarp_wf(name='sdc_unwarp_wf')

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.

Inputs:

• in_reference – the reference image

• in_reference_brain – the reference image (skull-stripped)

• in_mask – a brain mask corresponding to in_reference

• metadata – metadata associated to the in_reference EPI input

• 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_hz – fieldmap in Hz that can be sent to eddy

qsiprep.workflows.fieldmap.init_drbuddi_wf(scan_groups, t2w_sdc)

This workflow implements the heuristics to choose a SDC strategy.

(Source code)

Parameters:

• scan_groups (dict of distortion groupings) – Inputs configuration for distortion correction

• t2w_sdc (bool) – Should a T2w image be included in the DRBUDDI run?

Inputs:

• dwi_file (str) – Path to a motion/eddy corrected DWI file (in LPS+)

• bval_file (str) – Corresponding bval file for dwi_file

• bvec_file (str) – Corresponding bvec file for dwi_file (in LPS+)

• original_files (list) – List of the original BIDS file for each image in dwi_file

• t1_brain – T1w image, brain-masked

• t2_brain – T2w image, brain masked

Outputs:

• b0_ref – An unwarped b0 reference

• b0_mask – The corresponding new mask after unwarping

• sdc_warps – The deformation fields to unwarp the susceptibility distortions in each image in dwi_file

qsiprep.workflows.fieldmap.init_fmap_unwarp_report_wf(name='fmap_unwarp_report_wf')

This workflow generates and saves a reportlet showing the effect of fieldmap unwarping a DWI image.

(Source code, png, svg, pdf)

Parameters:

name (str, optional) – Workflow name (default: fmap_unwarp_report_wf)

Inputs:

• in_pre – Reference image, before unwarping

• in_post – Reference image, after unwarping

• in_seg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)

• in_xfm – Affine transform from T1 space to b0 space (ITK format)

qsiprep.workflows.fieldmap.init_pepolar_unwarp_wf(dwi_meta, epi_fmaps, name='pepolar_unwarp_wf')

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.

(Source code)

Inputs

in_reference

the reference image

in_reference_brain

the reference image skullstripped

in_mask

a brain mask corresponding to in_reference

Outputs

out_reference

the in_reference after unwarping

out_warp

the corresponding DFM compatible with ANTs

qsiprep.workflows.fieldmap.init_sdc_unwarp_wf(name='sdc_unwarp_wf')

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.

Inputs:

• in_reference – the reference image

• in_reference_brain – the reference image (skull-stripped)

• in_mask – a brain mask corresponding to in_reference

• metadata – metadata associated to the in_reference EPI input

• 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_hz – fieldmap in Hz that can be sent to eddy

qsiprep.workflows.fieldmap.init_sdc_wf(fieldmap_info, dwi_meta)

This workflow implements the heuristics to choose a SDC strategy. When no field map information is present within the BIDS inputs, the EXPERIMENTAL “fieldmap-less SyN” can be performed, using the --use-syn argument. When --force-syn is specified, then the “fieldmap-less SyN” is always executed and reported despite of other fieldmaps available with higher priority. In the latter case (some sort of fieldmap(s) is available and --force-syn is requested), then the SDC method applied is that with the highest priority.

(Source code)

Parameters:

• fmaps (list of pybids dicts) – A list of dictionaries with the available fieldmaps (and their metadata using the key 'metadata' for the case of epi fieldmaps)

• dwi_meta (dict) – BIDS metadata dictionary corresponding to the DWI run

Inputs:

• b0_ref – A b0 reference calculated at a previous stage

• b0_ref_brain – Same as above, but brain-masked

• b0_mask – Brain mask for the DWI run

• t1_brain – T1w image, brain-masked, for the fieldmap-less SyN method

• t1_2_mni_reverse_transform – MNI-to-T1w transform to map prior knowledge to the T1w fo the fieldmap-less SyN method

• template (str) – Name of template targeted by template output space

Outputs:

• b0_ref – An unwarped b0 reference

• b0_mask – The corresponding new mask after unwarping

• out_warp – The deformation field to unwarp the susceptibility distortions

• syn_b0_ref – If --force-syn, an unwarped b0 reference with this method (for reporting purposes)

• method – Name of the method used for SDC

• fieldmap_hz – The fieldmap in Hz for eddy

qsiprep.workflows.fieldmap.init_syn_sdc_wf(bold_pe=None, atlas_threshold=2)

This workflow takes a skull-stripped T1w image and reference b0 image and estimates a susceptibility distortion correction warp, using ANTs symmetric normalization (SyN) and the average fieldmap atlas described in [Treiber2016].

SyN deformation is restricted to the phase-encoding (PE) direction. If no PE direction is specified, anterior-posterior PE is assumed.

SyN deformation is also restricted to regions that are expected to have a >2mm (approximately 1 voxel) warp, based on the fieldmap atlas.

This technique is a variation on those developed in [Huntenburg2014] and [Wang2017].

(Source code)

Inputs

b0_ref

reference image

templatestr

Name of template targeted by template output space

t1_brain

skull-stripped, bias-corrected structural image

t1_2_mni_reverse_transform

inverse registration transform of T1w image to MNI template

Outputs

out_reference

the bold_ref image after unwarping

out_reference_brain

the bold_ref_brain image after unwarping

out_warp

the corresponding DFM compatible with ANTs

out_mask

mask of the unwarped input file

Submodules

• qsiprep.workflows.fieldmap.base module
• qsiprep.workflows.fieldmap.drbuddi module
• qsiprep.workflows.fieldmap.fmap module
• qsiprep.workflows.fieldmap.pepolar module
• qsiprep.workflows.fieldmap.phdiff module
• qsiprep.workflows.fieldmap.syn module
• qsiprep.workflows.fieldmap.unwarp module
• qsiprep.workflows.fieldmap.utils module