We have recently identified a bug in our import & export of FSL-style bvecs files. This caused a flip of the x component for some (but not all) images, leading to grossly incorrect fibre orientations and tractography. While most users will be unaffected, the gradient reorientation performed by the recently added dwipreproc script will be subtly incorrect - but only if EDDY version 5.0.9 is installed, and only if subject motion is non-negligible (note that dwipreproc was made available on 12 March 2016). This bug has now been rectified on GitHub; users are urged to update now to avoid problems later.


Over the last couple of weeks, we’ve been investigating issues with inconsistent behaviour when interacting with FSL. With the help of the FSL team (thanks in particular to Mark Jenkinson), the problem was eventually tracked down to our interpretation of the bvecs format - but only when the images are in a specific internal layout (in simple terms, when the data are stored using the neurological convention). This issue leads to the DW directions being flipped along the image’s x axis for those particular images. Thankfully, since this would lead to grossly incorrect fibre orientations and tractography, it should be easy to spot when things have gone wrong. Importantly, given that the handling was self-consistent within MRtrix3, this hasn’t caused any issues for almost all of the MRtrix3 commands and scripts - only when data were subsequently fed through to FSL’s diffusion toolbox commands, or if bvecs/bvals files generated by some other software were fed to MRtrix3, may there have been a problem.

However, one script where this bug is potentially problematic is dwipreproc, released recently as part of our syntax overhaul (released on 12 March 2016). This is due to the reorientation of the gradient directions performed within the latest version of EDDY (5.0.9), which dwipreproc will use if provided. While the motion and eddy-current correction that EDDY performs is largely unaffected by getting the DW gradients wrong, the reorientation is applied to the wrong gradients, and is hence not correct. Thankfully, this is only going to be a problem when subject motion is large enough to actually induce large rotations - but in those cases, the reoriented gradients produced by dwipreproc will be wrong to some extent. If you are affected by this problem, we can only apologise for this oversight.

This issue has now been fixed on the GitHub repository. Users are strongly encouraged to update their installations as soon as is practical, using the standard git pull; ./build procedure. Those users who have pre-processed their data specifically using dwipreproc and FSL 5.0.9 are also encouraged to rerun their preprocessing if possible (note that users with earlier versions of FSL are unaffected), particularly if motion is expected to be a problem.

What is the cause of the problem?

The issue occurred due to our incorrect interpretation of the bvecs format. We had assumed that the gradient vectors in a bvecs file were provided with respect to the coordinate system defined by the image axes. While this is true, it unfortunately isn’t the whole story. As we learned recently, this is only true if the image is stored using radiological convention. More precisely, if the image axes form a left-handed coordinate system; equivalently, if the determinant of the 3×3 rotation part of the transform is negative (this was the convention used in the now deprecated Analyse format, since superseded by the NIfTI format).

However, the default coordinate system in NIfTI is a right-handed system (often referred to as neurological). In this case, the correct coordinate system by which to interpret the bvecs is that formed by the image axes as if the image had been stored in radiological convention. What this means is that when the coordinate system is right-handed (positive determinant), the x component of the bvecs should be inverted. At the time, this was not documented (although the relevant section has now been updated), and we failed to identify this through our own testing. This has now been rectified in the latest version of MRtrix3.

What is affected?

In practice, we expect most users will be largely unaffected. However we are providing as much information on the issue as we can, so that users can make their own judgement. For further information on how MRtrix3 handles these data storage issues, we recommend you look at the relevant documentation on image strides.

  • Users operating primarily on NIfTI/bvecs data, using MRtrix3 as ‘supplementary’ software, may have imported their raw image data using a converter that produces ‘FSL-compatible’ NIfTI images - i.e. stored using a left-handed, radiological coordinate system (although FSL is now capable of operating on any standard-compliant NIfTI image). In this case, the import into MRtrix3 was, and remains, correct.

  • Issues might arise when producing NIfTI images along with their corresponding bvecs using MRtrix3, and subsequently analysing them using FSL’s diffusion toolbox; but only if the NIfTI images produced happen to be stored using a right-handed coordinate system. In this case, the directions would be clearly incorrect, and any subsequent tractography would be obviously wrong (although DTI metrics such as FA or ADC would be unaffected). We therefore expect such cases to be easily picked up by users - note however that for testing this, performing tractography in FSL is preferable to visualisation of the tensor eigenvectors in FSLview.

  • A similar issue may occur if some other conversion software was used to convert from another image format to NIfTI and bvecs/bvals files, the resulting NIfTI was created using a right-handed convention, and these were subsequently imported into MRtrix. This should be evident through visualisation of FODs, where the fibre orientations will not correctly follow the underlying anatomy. However, since we would expect most users primarily operating with MRtrix3 to have also performed any initial image conversions using MRtrix3, this scenario should be relatively rare.

  • As stated earlier, more subtle problems may arise if the dwipreproc script has been used to process data with FSL 5.0.9 installed. In this case, the reoriented gradient directions produced by EDDY will be utilized by that script. The correction applied by EDDY will be wrong, since the image supplied to EDDY within this script used a NIfTI-standard right-handed coordinate system, and the bvecs will therefore have contained a flip of the x component relative to EDDY’s expectations. Unless the motion was severe enough to introduce large rotations, the effect of this correction is subtle, and hence errors are difficult to pick up on visual inspection. For this reason, we recommend that users who have processed data using dwipreproc should update their installation and run their processing again, particularly if their data are likely to be affected by significant amounts of motion (if the motion remains reasonably small, the gradient reorientation will be correspondingly small, both for correct and erroneous reorientations).

What can you do about this?

The first thing is to update MRtrix3 to avoid the issue in future. The next thing is to check whether existing data could have been affected. If you use MRtrix3 both for image conversion and tractography analysis, you only need to worry about this if you have used dwipreproc and you have FSL 5.0.9 installed. In this case, you will need to decide whether to rerun the preprocessing, depending on the amount of motion present in your data; if in doubt, run the updated version of dwipreproc again. If you do use images and bvecs produced by MRtrix3 with FSL’s diffusion toolbox, then you should check whether the directions and tractography results are correct within FSL.

You may also find that after this update, NIfTI / bvecs data that were generated previously by MRtrix3 will not be interpreted correctly by the updated MRtrix3 code: the x component may be flipped due to our correction to the interpretation of these directions. In this case, the x component of the bvecs file (i.e. the first row in the file) will need to be inverted manually.

View comments on the community site