qsiprep.interfaces.fmap module

Interfaces to deal with the various types of fieldmap sources.

>>> tmpdir = getfixture('tmpdir')
>>> tmp = tmpdir.chdir() # changing to a temporary directory
>>> nb.Nifti1Image(np.zeros((90, 90, 60)), None, None).to_filename(
...     tmpdir.join('epi.nii.gz').strpath)

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

Bases: SimpleInterface

Transport Jacobian weight maps to the output grid and multiply them in.

The maps arrive in undistorted b=0-reference space. Resampling them through the dwiref and coregistration transforms is what evaluates the gradwarp and SDC determinants at the coordinates the full composite evaluates them at – see the design spec’s coordinate-safety section.

Each unique map costs one antsApplyTransforms subprocess call. That was free when there were at most two unique maps (DRBUDDI’s blip-up/blip-down pair); it stops being free once every DWI volume can carry a distinct eddy-current Jacobian (TORTOISE, quadratic correction mode), collapsing the dedup cache to one unique map per volume. Rather than fanning this out to a MapNode (which cannot accept an empty iterfield – see below), this interface parallelizes its own loop with a ThreadPoolExecutor, exactly as ComposeTransforms (gradients.py) already does for the analogous per-volume antsApplyTransforms calls in the main resampling chain.

Because this stays a plain Node – no iterfield to collapse – a run with no distortion correction at all (no gradwarp, no SDC, no eddy-current Jacobian) is handled by the same early return as before: jacobian_weight_ images is Undefined, so nothing is resampled and the DWIs pass through unmodified. A MapNode-based split cannot make that guarantee: Nipype collapses a defined empty list back to Undefined on a MapNode’s own iterfield trait, so MapNode._check_iterfield raises at run time for exactly this (mainstream: --hmc-method eddy with TOPUP and no gradwarp) configuration.

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

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

• dwiref_to_t1_affine (a pathlike object or string representing an existing file) – Affine from the dwiref to t1.

• dwiref_to_t1_warp (a pathlike object or string representing an existing file) – Warp from the dwiref to t1.

• 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))

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

• jacobian_weight_images (a list of items which are a pathlike object or string representing an existing file) – Per-volume Jacobian weight maps, in undistorted b0ref space.

• 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)

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

Outputs:

• resampled_weight_images (a list of items which are a pathlike object or string representing an existing file) – The unique weight maps, resampled to the output grid, in first-appearance order; indexed by the derivative sidecar.

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

• weight_index (a list of items which are an integer) – For each DWI volume, its index into resampled_weight_images.

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

Bases: SimpleInterface

Prepare 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 requested 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.CleanupEdgeFilter(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Blend despiked edge voxels into the original fieldmap interior.

Tidies the fieldmap edge in nibabel/scipy: the brain mask is eroded with an in-plane 3x3 kernel, the eroded interior keeps the original field, and the one-voxel rim between the mask and its erosion is filled with the despiked values. Needs no external tools.

Mandatory Inputs:

• despiked_file (a pathlike object or string representing an existing file) – Despiked fieldmap.

• in_file (a pathlike object or string representing an existing file) – Original (pre-despike) fieldmap.

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

Outputs:

out_file (a pathlike object or string representing a file) – Edge-cleaned fieldmap.

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

Bases: SimpleInterface

Conditional 2D median despike of a fieldmap (see _despike_2d()).

Removes isolated spikes from a phase-unwrapped fieldmap as part of the edge-cleanup pipeline, using only nibabel/numpy. threshold defaults to the conventional value for this cleanup step.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Fieldmap to despike.

Optional Inputs:

• in_mask (a pathlike object or string representing an existing file) – Brain mask; despiking is restricted to it and out-of-mask neighbors are excluded from the statistics.

• threshold (a float) – Spike threshold: a voxel is despiked when |value - neighbor median| exceeds this multiple of the neighbor range. (Nipype default value: 2.1)

Outputs:

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

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

Bases: SimpleInterface

Convert a fieldmap 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

Convert a fieldmap 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.FieldmapToVSM(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Convert a rad/s fieldmap into a voxel-shift map (VSM).

Uses the standard EPI relationship shift[vox] = fmap[rad/s] / (2*pi) * ees * N_pe, where ees is the effective echo spacing and N_pe the number of voxels along the phase-encoding axis. The shift carries the field’s own sign; the phase-encoding polarity is applied downstream by FUGUEvsm2ANTSwarp. Implemented in nibabel/numpy so the unwarp workflow needs no external tool to build the VSM.

Mandatory Inputs:

• dwell_time (a float) – Effective echo spacing in seconds (BIDS EffectiveEchoSpacing).

• in_file (a pathlike object or string representing an existing file) – Fieldmap in rad/s.

• pe_dir (‘i’ or ‘j’ or ‘k’ or ‘i-’ or ‘j-’ or ‘k-’ or ‘x’ or ‘y’ or ‘z’ or ‘x-’ or ‘y-’ or ‘z-’) – Phase-encoding axis; only the axis is used (the sign is applied downstream).

Outputs:

shift_out_file (a pathlike object or string representing a file) – Voxel-shift map, in voxels along the phase-encoding axis.

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

Bases: SimpleInterface

Median-filter an image with a spherical kernel (radius in mm).

Denoises the fieldmap using scipy; the kernel is the spherical footprint from _sphere_footprint(). Needs no external tools.

Mandatory Inputs:

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

Optional Inputs:

kernel_radius_mm (a float) – Radius (mm) of the spherical median kernel. (Nipype default value: 5.0)

Outputs:

out_file (a pathlike object or string representing a file) – Median-filtered image.

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.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_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.phases2fmap(phase_files, metadatas, newpath=None)

Calculate a phasediff from two phase images.

Assumes monopolar readout.

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

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

Uses eq. (1) of Hutton et al.[1]:

\[\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

[1]

Chloe Hutton, Andreas Bork, Oliver Josephs, Ralf Deichmann, John Ashburner, and Robert Turner. Image distortion correction in fmri: a quantitative evaluation. NeuroImage, 16(1):217–240, 2002. doi:10.1006/nimg.2001.1054.

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, crop_offset=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, crop_offset=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.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_file (Nibabel image) – A 4D Image

• b0_indices (array-like) – indices into nii_file that can be used by topup

• bids_origin_files (list, optional) – 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

• image_source (str, optional) – Description of where the images came from, used in the generated report text.

• max_per_spec (int, optional) – The maximum number of b=0 images to extract from a PE direction / image set