sdcflows.workflows.fit.fieldmap module#

Processing phase-difference and directly measured \(B_0\) maps.

sdcflows.workflows.fit.fieldmap.init_fmap_wf(omp_nthreads=1, sloppy=False, debug=False, mode='phasediff', name='fmap_wf')[source]#

Estimate the fieldmap based on a field-mapping MRI acquisition.

Estimates the fieldmap using either one phase-difference map or image and one or more magnitude images corresponding to two or more GRE acquisitions.

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.

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

(Source code, png, svg, pdf)

Parameters:

  • omp_nthreads (int) – Maximum number of threads an individual process may use.

  • sloppy (bool) – Whether a fast but less accurate correction should be applied.

  • debug (bool) – Run in debug mode

  • name (str) – Unique name of this workflow.

Inputs:

  • magnitude (list of str) – Path to the corresponding magnitude image for anatomical reference.

  • fieldmap (list of tuple`(:obj:`str, dict)) – Path to the fieldmap acquisition (*_fieldmap.nii[.gz] of BIDS).

Outputs:

  • fmap (str) – Path to the estimated fieldmap.

  • fmap_ref (str) – Path to a preprocessed magnitude image reference.

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

  • fmap_mask (str) – Path to a binary brain mask corresponding to the fmap and fmap_ref pair.

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

sdcflows.workflows.fit.fieldmap.init_magnitude_wf(omp_nthreads, name='magnitude_wf')[source]#

Prepare the magnitude part of GRE fieldmaps.

Average (if not done already) the magnitude part of the GRE images, run N4 to correct for B1 field nonuniformity, and skull-strip the preprocessed magnitude.

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

(Source code, png, svg, pdf)

Parameters:

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • name (str) – Name of workflow (default: magnitude_wf)

Inputs:

magnitude (os.PathLike) – Path to the corresponding magnitude path(s).

Outputs:

  • fmap_ref (os.PathLike) – Path to the fieldmap reference calculated in this workflow.

  • fmap_mask (os.PathLike) – Path to a binary brain mask corresponding to the reference above.

sdcflows.workflows.fit.fieldmap.init_phdiff_wf(omp_nthreads, debug=False, name='phdiff_wf')[source]#

Generate a \(B_0\) field from consecutive-phases and phase-difference maps.

This workflow preprocess phase-difference maps (or generates the phase-difference map should two phase1/phase2 be provided at the input), and generates an image equivalent to BIDS’s fieldmap that can be processed with the general fieldmap workflow.

Besides phase2 - phase1 subtraction, the core of this particular workflow relies in the phase-unwrapping with FSL PRELUDE [Jenkinson2003]. FSL PRELUDE takes wrapped maps in the range 0 to 6.28, as per the user guide.

For the phase-difference maps, recentering back to \([-\pi \dotsb \pi )\) is necessary. After some massaging and with the scaling of the echo separation factor \(\Delta \text{TE}\), the phase-difference maps are converted into an actual \(B_0\) map in Hz units.

Workflow Graph
../_images/sdcflows-workflows-fit-fieldmap-3.png

(Source code, png, svg, pdf)

Parameters:

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • debug (bool) – Run in debug mode

  • name (str) – Name of workflow (default: phdiff_wf)

Inputs:

  • magnitude (os.PathLike) – A reference magnitude image preprocessed elsewhere.

  • phase (list of tuple of (os.PathLike, dict)) – List containing one GRE phase-difference map with its corresponding metadata (requires EchoTime1 and EchoTime2), or the phase maps for the two subsequent echoes, with their metadata (requires EchoTime).

  • mask (os.PathLike) – A brain mask calculated from the magnitude image.

Outputs:

fieldmap (os.PathLike) – The estimated fieldmap in Hz.