Warning: This document is for an old version of sdcflows. The main version is master.

sdcflows.workflows.fit.syn module

Estimating the susceptibility distortions without fieldmaps.

Fieldmap-less approaches

Many studies acquired (especially with legacy MRI protocols) do not have any information to estimate susceptibility-derived distortions. In the absence of data with the specific purpose of estimating the \(B_0\) inhomogeneity map, researchers resort to nonlinear registration to an «anatomically correct» map of the same individual (normally acquired with T1w, or T2w sequences). One of the most prominent proposals of this approach is found in [Studholme2000].

SDCFlows includes an (experimental) procedure (see init_syn_sdc_wf() below), based on nonlinear image registration with ANTs’ symmetric normalization (SyN) technique. This workflow takes a skull-stripped T1w image and a reference EPI image, and estimates a field of nonlinear displacements that accounts for susceptibility-derived distortions. To more accurately estimate the warping on typically distorted regions, this implementation uses an average \(B_0\) mapping described in [Treiber2016]. The implementation is a variation on those developed in [Huntenburg2014] and [Wang2017]. Feedback will be enthusiastically received.

References

Studholme2000

Studholme et al. (2000) Accurate alignment of functional EPI data to anatomical MRI using a physics-based distortion model, IEEE Trans Med Imag 19(11):1115-1127, 2000, doi: 10.1109/42.896788.

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.

Huntenburg2014

Huntenburg, J. M. (2014) Evaluating Nonlinear Coregistration of BOLD EPI and T1w Images, Berlin: Master Thesis, Freie Universität.

sdcflows.workflows.fit.syn.init_syn_preprocessing_wf(*, debug=False, name='syn_preprocessing_wf', omp_nthreads=1, auto_bold_nss=False, t1w_inversion=False)[source]

Prepare EPI references and co-registration to anatomical for SyN.

Workflow Graph
../_images/sdcflows-workflows-fit-syn-1.png

(Source code, png, svg, pdf)

Parameters

  • debug (bool) – Whether a fast (less accurate) configuration of the workflow should be applied.

  • name (str) – Name for this workflow

  • omp_nthreads (int) – Parallelize internal tasks across the number of CPUs given by this option.

  • auto_bold_nss (bool) – Set up the reference workflow to automatically execute nonsteady states detection of BOLD images.

  • t1w_inversion (bool) – Run T1w intensity inversion so that it looks more like a T2 contrast.

Inputs

  • in_epis (list of str) – Distorted EPI images that will be merged together to create the EPI reference file.

  • t_masks (list of bool) – (optional) mask of timepoints for calculating an EPI reference. Not used if auto_bold_nss=True.

  • in_meta (list of dict) – Metadata dictionaries corresponding to the in_epis input.

  • in_anat (str) – A preprocessed anatomical (T1w or T2w) image.

  • mask_anat (str) – A brainmask corresponding to the anatomical (T1w or T2w) image.

  • std2anat_xfm (str) – inverse registration transform of T1w image to MNI template.

Outputs

  • epi_ref (tuple (str, dict)) – A tuple, where the first element is the path of the distorted EPI reference map (e.g., an average of b=0 volumes), and the second element is a dictionary of associated metadata.

  • anat_ref (str) – Path to the anatomical, skull-stripped reference in EPI space.

  • anat_mask (str) – Path to the brain mask corresponding to anat_ref in EPI space.

  • sd_prior (str) – A template map of areas with strong susceptibility distortions (SD) to regularize the cost function of SyN.

sdcflows.workflows.fit.syn.init_syn_sdc_wf(*, atlas_threshold=3, sloppy=False, debug=False, name='syn_sdc_wf', omp_nthreads=1)[source]

Build the fieldmap-less susceptibility-distortion estimation workflow.

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 >3mm (approximately 1 voxel) warp, based on the fieldmap atlas.

Workflow Graph
../_images/sdcflows-workflows-fit-syn-2.png

(Source code, png, svg, pdf)

Parameters

  • atlas_threshold (float) – Exclude from the registration metric computation areas with average distortions below this threshold (in mm).

  • sloppy (bool) – Whether a fast (less accurate) configuration of the workflow should be applied.

  • debug (bool) – Run in debug mode

  • name (str) – Name for this workflow

  • omp_nthreads (int) – Parallelize internal tasks across the number of CPUs given by this option.

Inputs

  • epi_ref (tuple (str, dict)) – A tuple, where the first element is the path of the distorted EPI reference map (e.g., an average of b=0 volumes), and the second element is a dictionary of associated metadata.

  • epi_mask (str) – A path to a brain mask corresponding to epi_ref.

  • anat_ref (str) – A preprocessed, skull-stripped anatomical (T1w or T2w) image resampled in EPI space.

  • anat_mask (str) – Path to the brain mask corresponding to anat_ref in EPI space.

  • sd_prior (str) – A template map of areas with strong susceptibility distortions (SD) to regularize the cost function of SyN

Outputs

  • fmap (str) – The path of the estimated fieldmap.

  • fmap_ref (str) – The path of an unwarped conversion of files in epi_ref.

  • fmap_coeff (str or list of str) – The path(s) of the B-Spline coefficients supporting the fieldmap.

  • method (str) – Short description of the estimation method that was run.