Distortion correcting BOLD data using FSL's topup

This has been puzzling me for quite some time: what is the ‘best’ or ‘correct’ way to run distortion correction on BOLD data using FSL’s topup in conjunction with opposing spin echo images (R>L and L>R). There seem to be a few different recommendations after running topup itself:

  1. Use applytopup as per FSL documentation on the BOLD images.
  2. Create rad/s and magnitude images instead of applytopup. Steps to do this are outlined here. However, an approach without FEAT is unclear (my guess would be to somehow use the fieldmap options in flirt, or use fugue?)
  3. Create a shiftmap, which then gets converted into a deformation field using convertwarp. I could not find any information on what a convertwarp command here would actually look like, however. I know this was ages ago, @oesteban, but do you remember what you did here?
  4. HCP applies some conversion to topup's dfout, which then can be used to warp the image of interest, followed by additional Jacobian modulation. My impression is that this is basically what applytopup does, just in a different set of commands. Is the convertwarp command here (lines 305, 317) reflective of what should be used above for (3)? Note that they also compute rad/s and magnitude images like in (2).

When I do run applytopup on my BOLD images, there is still some residual distortion that I can clean up nicely with ANTs (SyN). For this reason, one of the approaches above that generates a warp field is ideal, because I could combine transforms for one-step resampling.

I’d be curious to know peoples’ thoughts and how they’ve used topup successfully!

Personally I just use applytopup directly on the BOLD image which have been realigned first. … Nothing special then.
I do agree the correction is not perfect, but less that a voxel shift. Given the big smooth on usually do at the end, this should be good enough …

I do not really understand, why you would need to create the shiftmap (step 2 and 3)
You can simply use -fout option in topup, to get the equivalent fieldmap.

This fieldmap can be usfull if one wish to use SPM realign an unwarp, that take a field map as input


Some people also use more than 6 degrees of freedom (like 9 or 12) in the subsequent linear realignment step to the anatomical in order to remove part of this residual distortion. You could even use non linear realignment toward the anatomical image to remove more of this residual distorsion.
In the upcoming fmriprep version, topup will be introduced as one of the method for susceptibility distorsions correction (SDC) and in this script, all the operations including motion correction, SDC, realignment, normalisation are all applied in one step with Lanczos interpolation.

Interesting, the residual distortions after applytopup are still quite large with my data (rhesus macaques acquired in sphinx position), so I am a bit envious of your experience!

Yes, I agree; I am also curious why option #2 or #3 are specifically recommended in those instances.

This is good to know, thanks! I’m relieved to hear that it’s not uncommon to correct for residual distortion with more aggressive transformations.

Out of curiosity: what kind of acquisition resolution do you use for your macaques to get such big distorsions? Perhaps you also have some strong intensity bias in your image that prevents topup from working optimally? You may also need to tune topup settings for better results.

On the specific topic of using topup for Non-Human Primate imaging, I just found this comment that may interest you:

For the smaller NHP brain, FSL’s TopUp B0 field-map correction needs to be reconfigured from the default set-up, which is designed for the size of the human brain. We recommend adjusting the sampling resolution according to the isometric ratio between the NHP and human brains, as the scaling has a profound impact on the accuracy of distortion correction (Fig. 3f). After the TopUp configuration, the forward and reverse phase-encoded echo-planar images become more similar to each other, as measured by root-mean-square (RMS) deviation (mean RMS before and after configuration, 4596 and 1908, respectively; N=30), implying more accurate distortion correction.

Thanks for the share; I had not seen this and this looks tremendously helpful. Interestingly enough we designed our acquisition protocol around their earlier paper, keeping things as close to their sequences as our scanner would allow. I’ve been using the topup configuration file supplied by the HCP group, which does indeed outperform the default configuration file supplied with FSL.

I do not understand the #2 and #3 here. the rad/s to shiftmap are necessary step when you want to correct EPI distorsion base on a field map acquisition (GRE with 2 short echo)
if you do not have any field map acquisition, then what the point here … ?

Topup is an alternative to field map correction.
Do I understand correctly, that even after topup you want to perform a non linear coregistration (with ant) of the topup’s corrected EPI to anat ?

And you want (if possible) to applytopup and ants deformation in one-step resampling. It seems difficult to me, but may be there is a way

To avoid multiple interpolation is for sure better, but I think it is of little importance, if at the end you smooth your EPI data. (because a second interpolation will just add a small bluring, much less than the final smooth). but I may be wrong …

So I would go with apply topup and then additional nolinear registration with ants. (so 2 resampling at the end)

But I wonder if it worth it : why not just use one step ie: do only nolinear coregistration with ants ? (without topup)

if topup is not good enough with you data, and ants perform better, is there an advantage to perform both ?


Thank you Romain for those comments.
We ran such a comparaison: comparing topup + linear registration vs topup + linear registration and we saw an improvement with the addition of the non linear registration.
Please look at figure S2 and S3 in the supplementary materials of this paper:
Brun et al. Diffusion MRI: Assessment of the Impact of Acquisition and Preprocessing Methods Using the BrainVISA-Diffuse Toolbox. Front. Neurosci. 2019, 13, 536. https://doi.org/10.3389/fnins.2019.00536.
But I agree with you, some methods using directly non linear registration with no specific SDC such as topup show interesting results. See this paper for instance:
Wang et al. Evaluation of Field Map and Nonlinear Registration Methods for Correction of Susceptibility Artifacts in Diffusion MRI. Frontiers in Neuroinformatics 2017, 11. https://doi.org/10.3389/fninf.2017.00017.
Such fieldmap-less option is implemented in FMRIPREP for example.

I am not an expert on how to concatenate all transformations to apply them in one step but I saw that fmriprep uses antsApplyTransforms to do so.


For #2, my understanding is that topup can be used to create a rad/s fieldmap from the pair of opposing spin-echo images, which can be used instead. My guess is that people would want to use this approach if they want to use tools like fugue (which uses rad/s fieldmaps).

For #3 I am still not sure why Jan recommends this approach over the others. Puzzling indeed.

Currently my workflow is as follows:

  1. Run applytopup with both opposing SBRefs (R->L, L->R) together, which creates a nearly undistorted single-volume EPI template image. Note that this collapses both SBRefs together into a single average volume.
  2. Use applytopup on the BOLD data (for example, the R->L acquisition) to get a partially distortion corrected BOLD image.
  3. Nonlinearly warp the result from 2) to the EPI template computed in 1) using ANTs, which serves to remove the residual distortion.
  4. Repeat 2) and 3) with the second BOLD image (in the opposite direction, i.e. L->R)

With my data, combining applytopup + ANTs seemed to perform much better than either tool alone. I think it’s because applytopup gets the data ‘close enough’ to give ANTs a good starting point for nonlinear registration. This experience seems to echo @jsein’s experiences (thanks for the references!)

I better understand your workflow, and it makes sense, (and it agrees with the finding of Brun et al article)

Just curious, about your step 3. why a non linear coregistration to EPI template instead of to sujbect anatomical scan ? this is not the same objectiv …

@danjgale , did you use topup with this config file on your macaque data?

The approach of normalisation with no anatomical image reminds me of this article:

Dohmatob, E.; Varoquaux, G.; Thirion, B. Inter-Subject Registration of Functional Images: Do We Need Anatomical Images? Frontiers in Neuroscience 2018, 12. https://doi.org/10.3389/fnins.2018.00064.

Hi @danjgale, sorry for the very slow response.

I think your initial post is more than pertinent. Indeed, we’ve been working on a complete overhaul of SDCFlows, which packs together the susceptibility distortion correction (SDC) workflows used by fMRIPrep and dMRIPrep. The reasons to go for such a large refactor match your questions above:

  • I would agree that applyTopup may run short in some scenarios, esp. when data and fieldmap are not aligned.
  • There’s no common basis to formalize fieldmaps, unless you generate voxel-shift-maps and fieldmaps (in Hz) after TOPUP, and then reconstruct the displacements field (e.g., convertwarp) once everything is aligned with the target.
  • Yes, modulation could be the final relevant piece of the puzzle.

I would think that you could integrate SDCFlows and join forces with us to debug and finalize the refactor. Documentation is found here https://nipreps.org/sdcflows - please do not miss to browse through the API because the theory is stuck in there. Perhaps, this overview would make for a good starter before you skim out the documentation.

Long story short about the new SDCFlows:

  1. Library is separated into fitting (estimating) fieldmaps, and tools to help apply those fieldmaps (actually correcting the distortion). Some TOPUP + applyTopup of sorts, but built with flexibility in mind.
  2. All supported estimations (traditional GRE phasediffs and fieldmaps, PEPOLAR/TOPUP in many flavors, and fieldmapless -using ANTs and SyN-) write out the following standard outputs: the field expressed in one or more grids of B-Spline coefficients, the processed fieldmap in Hz, some anatomical-ish image that serves for reference (e.g., magnitude of GRE, unwarped EPI average, etc.).
  3. The module that applies correction takes in the B-Spline coefficients, moves them into alignment with the target image, reconstructs the distortion and resamples the input data after correction if requested. One of the coolest things of this is that you can provide head-motion correction matrices and the bspline coefficients will be moved with the head motion (i.e., you get a volume-wise distortion). All of that is roughly encapsulated within the B0FieldTransform object.
  4. Inputs checking and curation has been beefed up substantially (see the new representation objects).

Other than that, I think everything available outside SDCFlows has been pretty much covered by @jsein and @Romain_Valabregue

1 Like