aslprep.sdcflows.interfaces.fmap module

Interfaces to deal with the various types of fieldmap sources.

class FUGUEvsm2ANTSwarp(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Convert a voxel-shift-map to ants warp.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input displacements field map.

Optional Inputs:

pe_dir (‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’) – Phase-encoding axis.

Outputs:

  • fieldmap (a pathlike object or string representing a file) – Field map in mm.

  • out_file (a pathlike object or string representing a file) – The output warp field.

class FieldEnhance(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

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

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input fieldmap.

Optional Inputs:

  • bspline_smooth (a boolean) – Run 3D bspline smoother. (Nipype default value: True)

  • despike (a boolean) – Run despike filter. (Nipype default value: True)

  • despike_threshold (a float) – Mask erosion iterations. (Nipype default value: 0.2)

  • in_magnitude (a pathlike object or string representing an existing file) – Input magnitude.

  • in_mask (a pathlike object or string representing an existing file) – Brain mask.

  • mask_erode (an integer) – Mask erosion iterations. (Nipype default value: 1)

  • num_threads (an integer) – Number of jobs. (Nipype default value: 1)

  • unwrap (a boolean) – Run phase unwrap. (Nipype default value: False)

Outputs:

  • out_file (a pathlike object or string representing a file) – The output fieldmap.

  • out_unwrapped (a pathlike object or string representing a file) – Unwrapped fieldmap.

class FieldToHz(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Convert from arbitrary units to Hz.

Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Input fieldmap.

  • range_hz (a float) – Range of input field map.

Outputs:

out_file (a pathlike object or string representing a file) – The output fieldmap.

class FieldToRadS(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Convert from arbitrary units to rad/s.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input fieldmap.

Optional Inputs:

fmap_range (a float) – Range of input field map.

Outputs:

  • fmap_range (a float) – Range of input field map.

  • out_file (a pathlike object or string representing a file) – The output fieldmap.

class PhaseMap2rads(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

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

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input (wrapped) phase map.

Outputs:

out_file (a pathlike object or string representing a file) – The phase map in the range 0 - 6.28.

class Phasediff2Fieldmap(from_file=None, resource_monitor=None, **inputs)[source]

Bases: 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).

Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Input fieldmap.

  • metadata (a dictionary with keys which are any value and with values which are any value) – BIDS metadata dictionary.

Outputs:

out_file (a pathlike object or string representing a file) – The output fieldmap.

class SubtractPhases(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Calculate a phase difference map.

Optional Inputs:

  • in_meta (a list of items which are a dictionary with keys which are any value and with values which are any value) – Metadata corresponding to the inputs.

  • in_phases (a list of items which are a pathlike object or string representing an existing file) – Input phase maps.

Outputs:

  • metadata (a dictionary with keys which are any value and with values which are any value) – Output metadata.

  • phase_diff (a pathlike object or string representing an existing file) – Phase difference map.

au2rads(in_file, newpath=None)[source]

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

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
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
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.