qsiprep.interfaces.fmap module

Interfaces to deal with the various types of fieldmap sources

class qsiprep.interfaces.fmap.ApplyScalingImages(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• dwi_files (a list of items which are a pathlike object or string representing an existing file) – List of dwi files, already resampled into their output space.

• reference_image (a pathlike object or string representing an existing file) – Output grid.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• b0_to_intramodal_template_transforms (a list of items which are a pathlike object or string representing an existing file) – List of transforms to register the b=0 to the intramodal template.

• copy_dtype (a boolean) – Copy dtype from inputs to outputs. (Nipype default value: False)

• default_value (a float) – Maps to a command-line argument: --default-value %g. (Nipype default value: 0.0)

• dimension (2 or 3 or 4) – This option forces the image to be treated as a specified-dimensional image. If not specified, antsWarp tries to infer the dimensionality from the input image. Maps to a command-line argument: --dimensionality %d.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• float (a boolean) – Use float instead of double for computations. Maps to a command-line argument: --float %d. (Nipype default value: False)

• hmcsdc_dwi_ref_to_t1w_affine (a pathlike object or string representing an existing file) – Affine from dwi ref to t1w.

• input_image (a string or os.PathLike object)

• input_image_type (0 or 1 or 2 or 3) – Option specifying the input image type of scalar (default), vector, tensor, or time series. Maps to a command-line argument: --input-image-type %d.

• interpolation (‘Linear’ or ‘NearestNeighbor’ or ‘CosineWindowedSinc’ or ‘WelchWindowedSinc’ or ‘HammingWindowedSinc’ or ‘LanczosWindowedSinc’ or ‘MultiLabel’ or ‘Gaussian’ or ‘BSpline’ or ‘GenericLabel’) – Maps to a command-line argument: %s. (Nipype default value: Linear)

• interpolation_parameters (a tuple of the form: (an integer) or a tuple of the form: (a float, a float) or a tuple of the form: (a string))

• intramodal_template_to_t1_affine (a pathlike object or string representing an existing file) – Affine from the intramodal template to t1.

• intramodal_template_to_t1_warp (a pathlike object or string representing an existing file) – Warp from the intramodal template to t1.

• invert_transform_flags (a list of items which are a boolean)

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

• out_postfix (a string) – Postfix that is appended to all output files (default = _trans). (Nipype default value: _trans)

• output_image (a string) – Output file name. Maps to a command-line argument: --output %s.

• print_out_composite_warp_file (a boolean) – Output a composite warp file instead of a transformed image. Requires inputs: output_image.

• save_cmd (a boolean) – Write a log of command lines that were applied. (Nipype default value: True)

• scaling_image_files (a list of items which are a pathlike object or string representing an existing file) – List of sdc scaling image files in undistorted b0ref space.

• transforms (a pathlike object or string representing a file)

Outputs:

scaled_images (a list of items which are a pathlike object or string representing an existing file) – Scaled dwi files.

class qsiprep.interfaces.fmap.B0RPEFieldmap(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Prepares b=0 EPI fieldmaps to be used for distortion correction. Some siemens scanners are unable to make a b=0 image by itself, and will produce a dwi series (with bvals and bvecs). This interface removes the b>0 volumes and writes the b=0 images in the resuested orientation (LAS+ for FSL, or LPS+ for everything else).

Inputs

b0_file: str

List of paths to b=0 epi fieldmaps in fmaps/ or an RPE series in dwi/

output_3d_images: bool

Write outputs as multiple 3d images

max_num_b0s: int

Include a maximum number of b=0 images in the outputs

orientation: str

Write the outputs in either ‘LAS’ or ‘LPS’ orientation

Optional Inputs:

• b0_file (a list of items which are a pathlike object or string representing an existing file)

• b0_threshold (an integer) – (Nipype default value: 100)

• max_num_b0s (an integer) – (Nipype default value: 3)

• orientation (‘LPS’ or ‘LAS’) – (Nipype default value: LPS)

• output_3d_images (a boolean) – (Nipype default value: False)

Outputs:

• fmap_file (a list of items which are a pathlike object or string representing an existing file)

• fmap_info (a list of items which are a pathlike object or string representing an existing file)

• fmap_report (a string)

class qsiprep.interfaces.fmap.FieldToHz(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

The FieldToHz converts 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 qsiprep.interfaces.fmap.FieldToRadS(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

The FieldToRadS converts 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 qsiprep.interfaces.fmap.PEPOLARReport(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• b0_down_corrected_image (a pathlike object or string representing an existing file)

• b0_down_image (a pathlike object or string representing an existing file)

• b0_up_corrected_image (a pathlike object or string representing an existing file)

• b0_up_image (a pathlike object or string representing an existing file)

Optional Inputs:

• down_fa_corrected_image (a pathlike object or string representing an existing file)

• down_fa_image (a pathlike object or string representing an existing file)

• fieldmap_type (‘rpe_series’ or ‘epi’)

• t1w_seg (a pathlike object or string representing an existing file)

• t2w_seg (a pathlike object or string representing an existing file)

• up_fa_corrected_image (a pathlike object or string representing an existing file)

• up_fa_image (a pathlike object or string representing an existing file)

Outputs:

• b0_sdc_report (a pathlike object or string representing an existing file)

• fa_sdc_report (a pathlike object or string representing an existing file)

• out_report (a pathlike object or string representing a file) – Filename for the visual report.

class qsiprep.interfaces.fmap.ParallelTOPUP(**inputs)

Bases: TOPUP

Wrapped executable: topup.

Mandatory Inputs:

• encoding_direction (a list of items which are ‘y’ or ‘x’ or ‘z’ or ‘x-’ or ‘y-’ or ‘z-’) – Encoding direction for automatic generation of encoding_file. Maps to a command-line argument: --datain=%s. Mutually exclusive with inputs: encoding_file. Requires inputs: readout_times.

• encoding_file (a pathlike object or string representing an existing file) – Name of text file with PE directions/times. Maps to a command-line argument: --datain=%s. Mutually exclusive with inputs: encoding_direction.

• in_file (a pathlike object or string representing an existing file) – Name of 4D file with images. Maps to a command-line argument: --imain=%s.

• readout_times (a list of items which are a float) – Readout times (dwell times by # phase-encode steps minus 1). Mutually exclusive with inputs: encoding_file. Requires inputs: encoding_direction.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• config (a string) – Name of config file specifying command line arguments. Maps to a command-line argument: --config=%s. (Nipype default value: b02b0.cnf)

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• estmov (1 or 0) – Estimate movements if set. Maps to a command-line argument: --estmov=%d.

• fwhm (a float) – FWHM (in mm) of gaussian smoothing kernel. Maps to a command-line argument: --fwhm=%f.

• interp (‘spline’ or ‘linear’) – Image interpolation model, linear or spline. Maps to a command-line argument: --interp=%s.

• max_iter (an integer) – Max # of non-linear iterations. Maps to a command-line argument: --miter=%d.

• minmet (0 or 1) – Minimisation method 0=Levenberg-Marquardt, 1=Scaled Conjugate Gradient. Maps to a command-line argument: --minmet=%d.

• nthreads (an integer) – Maps to a command-line argument: --nthr=%d.

• numprec (‘double’ or ‘float’) – Precision for representing Hessian, double or float. Maps to a command-line argument: --numprec=%s.

• out_base (a pathlike object or string representing a file) – Base-name of output files (spline coefficients (Hz) and movement parameters). Maps to a command-line argument: --out=%s.

• out_corrected (a pathlike object or string representing a file) – Name of 4D image file with unwarped images. Maps to a command-line argument: --iout=%s.

• out_field (a pathlike object or string representing a file) – Name of image file with field (Hz). Maps to a command-line argument: --fout=%s.

• out_jac_prefix (a string) – Prefix for the warpfield images. Maps to a command-line argument: --jacout=%s. (Nipype default value: jac)

• out_logfile (a pathlike object or string representing a file) – Name of log-file. Maps to a command-line argument: --logout=%s.

• out_mat_prefix (a string) – Prefix for the realignment matrices. Maps to a command-line argument: --rbmout=%s. (Nipype default value: xfm)

• out_warp_prefix (a string) – Prefix for the warpfield images (in mm). Maps to a command-line argument: --dfout=%s. (Nipype default value: warpfield)

• output_type (‘NIFTI’ or ‘NIFTI_PAIR’ or ‘NIFTI_GZ’ or ‘NIFTI_PAIR_GZ’ or ‘GIFTI’) – FSL output type.

• reg_lambda (a float) – Weight of regularisation, default depending on –ssqlambda and –regmod switches. Maps to a command-line argument: --lambda=%0.f.

• regmod (‘bending_energy’ or ‘membrane_energy’) – Regularisation term implementation. Defaults to bending_energy. Note that the two functions have vastly different scales. The membrane energy is based on the first derivatives and the bending energy on the second derivatives. The second derivatives will typically be much smaller than the first derivatives, so input lambda will have to be larger for bending_energy to yield approximately the same level of regularisation. Maps to a command-line argument: --regmod=%s.

• regrid (1 or 0) – If set (=1), the calculations are done in a different grid. Maps to a command-line argument: --regrid=%d.

• scale (0 or 1) – If set (=1), the images are individually scaled to a common mean. Maps to a command-line argument: --scale=%d.

• splineorder (an integer) – Order of spline, 2->Qadratic spline, 3->Cubic spline. Maps to a command-line argument: --splineorder=%d.

• ssqlambda (1 or 0) – Weight lambda by the current value of the ssd. If used (=1), the effective weight of regularisation term becomes higher for the initial iterations, therefore initial steps are a little smoother than they would without weighting. This reduces the risk of finding a local minimum. Maps to a command-line argument: --ssqlambda=%d.

• subsamp (an integer) – Sub-sampling scheme. Maps to a command-line argument: --subsamp=%d.

• warp_res (a float) – (approximate) resolution (in mm) of warp basis for the different sub-sampling levels. Maps to a command-line argument: --warpres=%f.

Outputs:

• out_corrected (a pathlike object or string representing a file) – Name of 4D image file with unwarped images.

• out_enc_file (a pathlike object or string representing a file) – Encoding directions file output for applytopup.

• out_field (a pathlike object or string representing a file) – Name of image file with field (Hz).

• out_fieldcoef (a pathlike object or string representing an existing file) – File containing the field coefficients.

• out_jacs (a list of items which are a pathlike object or string representing an existing file) – Jacobian images.

• out_logfile (a pathlike object or string representing a file) – Name of log-file.

• out_mats (a list of items which are a pathlike object or string representing an existing file) – Realignment matrices.

• out_movpar (a pathlike object or string representing an existing file) – Movpar.txt output file.

• out_warps (a list of items which are a pathlike object or string representing an existing file) – Warpfield images.

class qsiprep.interfaces.fmap.Phasediff2Fieldmap(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Convert a phase difference map into a fieldmap in Hz

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 qsiprep.interfaces.fmap.Phases2Fieldmap(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Convert a phase1, phase2 into a difference map

Mandatory Inputs:

• metadatas (a list of items which are a dictionary with keys which are any value and with values which are any value) – List of phase1, phase2 metadata dicts.

• phase_files (a list of items which are a pathlike object or string representing an existing file) – List of phase1, phase2 files.

Outputs:

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

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

qsiprep.interfaces.fmap.add_epi_fmaps_to_dwi_b0s(epi_fmaps, b0_threshold, max_per_spec, dwi_spec_lines, dwi_imain)

Add additional images from EPI fieldmaps for distortion correction.

In order to fill out the maximum number of images per distortion group, images from files in the fmap/ directory can be added to those already extracted from the DWI series.

Examples:

>>> epi_fmaps = ["/data/sub-1/fmap/sub-1_dir-AP_epi.nii.gz",
...              "/data/sub-1/fmap/sub-1_dir-PA_epi.nii.gz"]

qsiprep.interfaces.fmap.eddy_inputs_from_dwi_files(origin_file_list, eddy_prefix)

qsiprep.interfaces.fmap.get_distortion_grouping(origin_file_list)

Discover which distortion groups are present, then assign each volume to a group.

qsiprep.interfaces.fmap.get_ees(in_meta, in_file=None)

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

qsiprep.interfaces.fmap.get_evenly_spaced_b0s(b0_indices, max_per_spec)

Choose up to max_per_spec b=0 images from a list of b0 indices.

qsiprep.interfaces.fmap.get_topup_inputs_from(dwi_file, bval_file, b0_threshold, topup_prefix, bids_origin_files, epi_fmaps=None, max_per_spec=3, topup_requested=False)

Create a datain spec and a slspec from a concatenated dwi series.

Create inputs for TOPUP that come from data in dwi/ and epi fieldmaps in fmap/. The nii_file input may be the result of concatenating a number of scans with different distortions present. The original source of each volume in nii_file is listed in bids_origin_files.

The strategy is to select max_per_spec b=0 images from each distortion group. Here, distortion group uses the FSL definition of a phase encoding direction and total readout time, as specified in the datain file used by TOPUP (i.e. “0 -1 0 0.087”).

Case: Two opposing PE direction dwi series

For example if the following b=0 images are found at the following indices into nii_file:

Image Index	BIDS source file for a b=0	Distortion Group
0	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
15	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
30	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
45	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
60	sub-1_dir-AP_run-2_dwi.nii.gz	0 -1 0 0.087
75	sub-1_dir-AP_run-2_dwi.nii.gz	0 -1 0 0.087
90	sub-1_dir-AP_run-2_dwi.nii.gz	0 -1 0 0.087
105	sub-1_dir-AP_run-2_dwi.nii.gz	0 -1 0 0.087
120	sub-1_dir-PA_run-1_dwi.nii.gz	0 1 0 0.087
135	sub-1_dir-PA_run-1_dwi.nii.gz	0 1 0 0.087
150	sub-1_dir-PA_run-1_dwi.nii.gz	0 1 0 0.087
165	sub-1_dir-PA_run-1_dwi.nii.gz	0 1 0 0.087

This will select images 0, 45 and 105 to represent the distortion group 0 -1 0 0.087 and images 120, 135 and 165 to represent 0 1 0 0.087. The --datain file would then contain:

0 -1 0 0.087
0 -1 0 0.087
0 -1 0 0.087
0 1 0 0.087
0 1 0 0.087
0 1 0 0.087

Case: one DWI series and an EPI fieldmap

If a reverse-phase encoding fieldmap image (or images) are passed in through epi_fmaps, these will undergo the same selection process using max_per_spec. The images will be added to the end of the image series, though, to ensure that the fieldmap correction will be aligned to the first b=0 image in nii_file. For example if nii_file contains

Image Index	BIDS source file for a b=0	Distortion Group
0	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
15	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
30	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087
45	sub-1_dir-AP_run-1_dwi.nii.gz	0 -1 0 0.087

and the file from fmaps contains

Image Index	BIDS source file for a b=0	Distortion Group
0	sub-1_dir-PA_epi.nii.gz	0 1 0 0.087
1	sub-1_dir-PA_epi.nii.gz	0 1 0 0.087

images 0, 15 and 45 would be selected to represent 0 -1 0 0.087 and images 0 and 1 would be selected to represent 0 1 0 0.087, resulting in a --datain file that contains:

0 -1 0 0.087
0 -1 0 0.087
0 -1 0 0.087
0 1 0 0.087
0 1 0 0.087

Parameters:

nii_filestr

A 4D DWI Series

b0_indices: array-like

indices into nii_file that can be used by topup

topup_prefix: str

file prefix for topup inputs

bids_origin_files: list

A list with the original bids file of each image in nii_file. This is necessary because merging may have happened earlier in the pipeline

epi_fmaps:

A list of b=0 images from the fmaps/ directory.

max_per_spec: int

The maximum number of b=0 images to extract from a PE direction / image set

qsiprep.interfaces.fmap.get_trt(in_meta, in_file=None)

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

qsiprep.interfaces.fmap.load_epi_dwi_fieldmaps(fmap_list, b0_threshold)

Creates a 4D image of b=0s from a list of input images.

Parameters:

fmap_list: list

List of paths to epi fieldmap images

b0_threshold: int

Maximum b value for an image to be considered a b=0

Returns:

concatenated_images: spatial image

The b=0 volumes concatenated into a 4D image

b0_indices: list

List of the original indices of the images in concatenated_images

original_files: list

List of the original files where each b=0 image came from.

qsiprep.interfaces.fmap.phases2fmap(phase_files, metadatas, newpath=None)

Calculates a phasediff from two phase images. Assumes monopolar readout.

qsiprep.interfaces.fmap.phdiff2fmap(in_file, delta_te, newpath=None)

Converts the input phase-difference map into a fieldmap in Hz, using the 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}}\]

qsiprep.interfaces.fmap.plot_fa_reg(fa_img, seg_contour_img, div_id, plot_params=None, blip_down_plot_params=None, order=('z', 'x', 'y'), cuts=None, estimate_brightness=False, label=None, compress='auto')

Plot the foreground and background views. Default order is: axial, coronal, sagittal

Updated version from sdcflows and different from in niworkflows.viz.utils so that the contour lines never move. This is accomplished by making an empty image in the grid of the segmentation image and using this as the background.

qsiprep.interfaces.fmap.plot_pepolar(blip_up_img, blip_down_img, seg_contour_img, div_id, plot_params=None, blip_down_plot_params=None, order=('z', 'x', 'y'), cuts=None, estimate_brightness=False, label=None, blip_down_contour=None, upper_label_suffix=': low-b', lower_label_suffix=': high-b', compress='auto', overlay=None, overlay_params=None)

Plot the foreground and background views. Default order is: axial, coronal, sagittal

Updated version from sdcflows and different from in niworkflows.viz.utils so that the contour lines never move. This is accomplished by making an empty image in the grid of the segmentation image and using this as the background.

qsiprep.interfaces.fmap.read_nifti_sidecar(json_file)

qsiprep.interfaces.fmap.topup_inputs_from_4d_file(nii_file, b0_indices, bids_origin_files=None, image_source='combined DWI series', max_per_spec=3)

Represent distortion groups from a concatenated image and its origins.

Create inputs for TOPUP that come from data in dwi/ and epi fieldmaps in fmap/. The nii_file input may be the result of concatenating a number of scans with different distortions present. The original source of each volume in nii_file is listed in bids_origin_files.

The strategy is to select max_per_spec b=0 images from each distortion group. Here, distortion group uses the FSL definition of a phase encoding direction and total readout time, as specified in the datain file used by TOPUP (i.e. “0 -1 0 0.087”).

Parameters

nii_fileNibabel image

A 4D Image

b0_indices: array-like

indices into nii_file that can be used by topup

bids_origin_files: list

A list with the original bids file of each image in nii_file. This is necessary because merging may have happened earlier in the pipeline

max_per_spec: int

The maximum number of b=0 images to extract from a PE direction / image set