Distortion correction using interlaced q-space sampling

This page provides a precompiled Matlab implementation ("p-code") of a distortion correction method for diffusion MRI using the interlaced q-space sampling technique. This method uses interlaced phase-encoding directions (IPED) while sampling the q-space, which enables accurate distortion correction without increasing the acquisition time.

Click to enlarge Representative comparison of applying different distortion correction methods to in-vivo data. (top) The average of all distortion-corrected DWIs from an axial slice. (bottom) Corresponding mean absolute error of the DWI image intensities, with respect to the 4-PED Full images (used as a reference since no ground truth exists for the in-vivo data). Colored arrows indicate the PED(s) used for each method. 4-PED requires four-times the regular scan time, reversed gradient (RG) method requires twice the regular scan time, while IPED and single-PED methods require regular scan time.

Please see following references for more details of the method:

  1. C. Bhushan, A. A. Joshi, R. M. Leahy and J. P. Haldar (2014), Improved B0-distortion correction in diffusion MRI using interlaced q-space sampling and constrained reconstruction. Magnetic Resonance in Medicine, 72: 1218-1232. doi: 10.1002/mrm.25026

  2. C. Bhushan, A. A. Joshi, R. M. Leahy and J. P. Haldar (2013), Accelerating data acquisition for reversed-gradient distortion correction in diffusion MRI: A constrained reconstruction approach. 21st Scientific Meeting of International Society for Magnetic Resonance in Medicine (ISMRM), Salt Lake City, p. 55. Abstract PDF, ISMRM presentation video

Data acquisition

4IPED_small.png This implementation makes several assumptions about the data acquisition, data format and sampling pattern in the q-space. All of the following must be satisfied for accurate correction:

Further, take note about following to enable accurate distortion correction with IPED method with this implementation:

This implementation also works with reversed-gradient (Chang and Fitzpatrick, 1992) and its generalized acquisition schemes without any modification. Also see optional inputs below for more options about generalized reversed-gradient schemes.


The distortion correction method is implemented as a Matlab function, named IPEDcorrect, and requires Image processing toolbox. It only supports use of NIfTI-1 data format for image and plain text-files for specifying other parameters. Either of following syntax is supported:

IPEDcorrect(IPED_config_filename, fieldmap_filename, echo_spacing, output_base)
IPEDcorrect(IPED_config_filename, fieldmap_filename, echo_spacing, output_base, opts)


IPED-config file

IPED-config file is a plain text file which describes different acquisition parameters for the diffusion data. The file follows a table-type format, which can be created and saved using a simple text editor. The IPED-config file can be saved with any extension. Each row of the file describes parameter for diffusion images corresponding to one phase-encoding direction. Number of columns in each row should be consistent and must have three, four or five columns. The first column specifies the filename of the 4D NIfTI-1 diffusion file. Second column specifies the phase encoding direction (PED). Rest of the columns specifies filenames which describe diffusion encoding parameters as shown below. In addition, any text coming after a # (hash) is ignored for rest of the line.

Four columns (with bvec, bval file):

4D-nifti-filename.nii.gz  PED  bvec-filename  bval-filename

Three columns (with bmat file):

4D-nifti-filename.nii.gz  PED  bmat-filename

Five columns (with bvec, bval and bmat file):

4D-nifti-filename.nii.gz  PED  bvec-filename  bval-filename bmat-filename

Filenames can be specified either with their full-path or without any path (for the later case, files are assumed to be in the same directory as the IPED-config file. Relative paths (eg: subdirectory/file.nii.gz) are not supported. When the filenames/paths contain spaces then they must be enclosed in double quotes (eg: "subject23 trial2.nii.gz"). Different columns of the config file can also be delimited by comma, like that in standard csv files (in case of csv format, filenames with spaces can be directly specified and must not use double quotes).

IPED_ped_eg_small.png EPI images are most distorted along the phase encoding direction (PED) and IPEDcorrect formulates the distortion correction as a 1D problem. PED can be easily be specified after visualizing the images in BrainSuite software. Valid options for PED are x, x-, y, y-, z and z-. x direction increases towards the right side of the subject, while x- increases towards the left side of the subject. Similarly, y and y- are along the anterior-posterior direction of the subject, and z and z- are along the inferior-superior direction. The figure on the right describes the PED directions in different views. The image shown in the above figure (full BrainSuite view) has PED of y-. The polarity of the PED depends on the sign convention of the fieldmap and it can be best adjusted by trying the function with different polarity.

The bvec and/or bmat files should describe diffusion encoding direction in voxel coordinate of the diffusion data (i.e. in the same frame of reference as the image matrix). Further, the order of entries of gradient direction in the specified .bvec or .bmat file must match the order of volumes in the input 4-D NIfTI data.

Following is an example of the content of an IPED-config file with four different PEDs.

6067JH.DWI.A.nii.gz  y- 6067JH.DWI.A.bvec  6067JH.DWI.A.bval
6067JH.DWI.P.nii.gz  y  6067JH.DWI.P.bvec  6067JH.DWI.P.bval
6067JH.DWI.L.nii.gz  x- 6067JH.DWI.L.bvec  6067JH.DWI.L.bval
6067JH.DWI.R.nii.gz  x  6067JH.DWI.R.bvec  6067JH.DWI.R.bval

Optional inputs

IPEDcorrect can take several optional inputs to change the behavior of the different regularization terms.

Following Matlab structure defines the default options used in IPEDcorrect:

opts = struct(...
   'spatial_beta', 0.27, ...
   'spherical_alpha', 0.04, ...
   'shOrder', 8, ...
   'sph_wt', 'G_mag', ...
   'G_mag_low', 1*2*pi, ...
   'G_mag_high', 9*2*pi, ...
   'estimation_mask', '', ...
   'isfull', false, ...
   'save_SH_coeff', 1 ...

Download & Installation

This code is licensed under the CC Attribution-Noncommercial-Share Alike 4.0 License. Please cite [1] and [2] if you use this code or its derivatives in your own work.

In no event shall the University of Southern California, the Authors, or the Distributors be liable to any party for direct, indirect, special, incidental, or consequential damages, including lost profits, arising out of the use of this software, its documentation, or any derivatives thereof, even if the authors have been advised of the possibility of such damage. The University of Southern California, the Authors, and the Distributors specifically disclaim any warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. This software is provided on an "as is" basis, and the authors and distributors have no obligation to provide maintenance, support, updates, enhancements, or modifications. This software is for research purposes only and has not been approved for clinical use.

System requirements

IPEDcorrect is a Matlab function and requires Image processing toolbox. Only 64-bit platforms (Windows, MacOS, Linux) are supported. It has been only tested with Matlab 2012a and Matlab 2014b. Memory requirement depends of size of the input diffusion dataset. opts.estimation_mask can be used to substantially lower the memory requirement and run-time.


  1. Download the zip file and extract the content to a directory on your computer, say /home/username/matlab/IPED.

  2. Add the directory to Matlab path by using following command on Matlab prompt (appropriately replace the name of directory): addpath(genpath('/home/username/matlab/IPED'))

  3. IPEDcorrect should be available in Matlab after adding path. Test it by typing IPEDcorrect on Matlab command prompt. It should issue an error about missing input arguments, as shown below.

>> addpath(genpath('/home/username/matlab/IPED'))

>> IPEDcorrect
Error using IPEDcorrect (line 12)

Incorrect number of input arguments. IPEDcorrect() needs either 4 or 5 input
arguments. Please see usage details at:

Resources/IPED (last edited 2017-02-12 17:56:30 by ?ChitreshBhushan)