sdcflows.interfaces.fmap module

Interfaces to deal with the various types of fieldmap sources.

class sdcflows.interfaces.fmap.FUGUEvsm2ANTSwarp(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert a voxel-shift-map to ants warp.

input_spec

alias of _FUGUEvsm2ANTSwarpInputSpec

output_spec

alias of _FUGUEvsm2ANTSwarpOutputSpec

class sdcflows.interfaces.fmap.FieldEnhance(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Massage the input fieldmap (masking, despiking, etc.).

input_spec

alias of _FieldEnhanceInputSpec

output_spec

alias of _FieldEnhanceOutputSpec

class sdcflows.interfaces.fmap.FieldToHz(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert from arbitrary units to Hz.

input_spec

alias of _FieldToHzInputSpec

output_spec

alias of _FieldToHzOutputSpec

class sdcflows.interfaces.fmap.FieldToRadS(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert from arbitrary units to rad/s.

input_spec

alias of _FieldToRadSInputSpec

output_spec

alias of _FieldToRadSOutputSpec

class sdcflows.interfaces.fmap.PhaseMap2rads(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert a phase map in a.u. to radians.

input_spec

alias of _PhaseMap2radsInputSpec

output_spec

alias of _PhaseMap2radsOutputSpec

class sdcflows.interfaces.fmap.Phasediff2Fieldmap(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert a phase difference map into a fieldmap in Hz.

This interface is equivalent to running the following steps:
  1. Convert from rad to rad/s (niflow.nipype1.workflows.dmri.fsl.utils.rads2radsec)

  2. FUGUE execution: fsl.FUGUE(save_fmap=True)

  3. Conversion from rad/s to Hz (divide by 2pi, rsec2hz).

input_spec

alias of _Phasediff2FieldmapInputSpec

output_spec

alias of _Phasediff2FieldmapOutputSpec

class sdcflows.interfaces.fmap.SubtractPhases(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Calculate a phase difference map.

input_spec

alias of _SubtractPhasesInputSpec

output_spec

alias of _SubtractPhasesOutputSpec

sdcflows.interfaces.fmap.au2rads(in_file, newpath=None)[source]

Convert the input phase difference map in arbitrary units (a.u.) to rads.

sdcflows.interfaces.fmap.get_ees(in_meta, in_file=None)[source]

Extract the effective echo spacing \(t_\text{ees}\) from BIDS.

Calculate the effective echo spacing \(t_\text{ees}\) for an input EPI scan.

There are several procedures to calculate the effective echo spacing. The basic one is that an EffectiveEchoSpacing field is set in the JSON sidecar. The following examples use an 'epi.nii.gz' file-stub which has 90 pixels in the j-axis encoding direction.

>>> meta = {'EffectiveEchoSpacing': 0.00059,
...         'PhaseEncodingDirection': 'j-'}
>>> get_ees(meta)
0.00059

If the total readout time \(T_\text{ro}\) (TotalReadoutTime BIDS field) is provided, then the effective echo spacing can be calculated reading the number of voxels \(N_\text{PE}\) along the readout direction and the parallel acceleration factor of the EPI

\[= T_\text{ro} \, (N_\text{PE} / f_\text{acc} - 1)^{-1}\]

where \(N_y\) is the number of pixels along the phase-encoding direction \(y\), and \(f_\text{acc}\) is the parallel imaging acceleration factor (GRAPPA, ARC, etc.).

>>> meta = {'TotalReadoutTime': 0.02596,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_ees(meta, in_file='epi.nii.gz')
0.00059

Some vendors, like Philips, store different parameter names (see http://dbic.dartmouth.edu/pipermail/mrusers/attachments/20141112/eb1d20e6/attachment.pdf ):

>>> meta = {'WaterFatShift': 8.129,
...         'MagneticFieldStrength': 3,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_ees(meta, in_file='epi.nii.gz')
0.00041602630141921826
sdcflows.interfaces.fmap.get_trt(in_meta, in_file=None)[source]

Extract the total readout time \(t_\text{RO}\) from BIDS.

Calculate the total readout time for an input EPI scan.

There are several procedures to calculate the total readout time. The basic one is that a TotalReadoutTime field is set in the JSON sidecar. The following examples use an 'epi.nii.gz' file-stub which has 90 pixels in the j-axis encoding direction.

>>> meta = {'TotalReadoutTime': 0.02596}
>>> get_trt(meta)
0.02596

If the effective echo spacing \(t_\text{ees}\) (EffectiveEchoSpacing BIDS field) is provided, then the total readout time can be calculated reading the number of voxels along the readout direction \(T_\text{ro}\) and the parallel acceleration factor of the EPI \(f_\text{acc}\).

\[T_\text{ro} = t_\text{ees} \, (N_\text{PE} / f_\text{acc} - 1)\]
>>> meta = {'EffectiveEchoSpacing': 0.00059,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_trt(meta, in_file='epi.nii.gz')
0.02596

Some vendors, like Philips, store different parameter names:

>>> meta = {'WaterFatShift': 8.129,
...         'MagneticFieldStrength': 3,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_trt(meta, in_file='epi.nii.gz')
0.018721183563864822
sdcflows.interfaces.fmap.phdiff2fmap(in_file, delta_te, newpath=None)[source]

Convert the input phase-difference map into a fieldmap in Hz.

Uses 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}}\]

References

Hutton2002

Hutton et al., Image Distortion Correction in fMRI: A Quantitative Evaluation, NeuroImage 16(1):217-240, 2002. doi:10.1006/nimg.2001.1054.