MRtrix 3.0 (release candidate 2)

Announcements
,
1

The last few months of work have resulted in another batch of updated features. The most important changes motivating this second release candidate relate to the bias field correction and intensity normalisation process previously performed by the mtbin command, which affects the fixel-based analysis pipeline in particular. Users who are in the process of performing a fixel-based analysis on their data should pay special attention to the changes this update brings to the bias field and intensity normalisation and other steps (and documentation) of the fixel-based analysis pipeline (see below for details).

This release candidate introduces a number of bug fixes and enhancements, but also other changes that you will need to know about, in particular:

Other more minor enhancements:

  • support for exporting tracks to PLY format via tckconvert (courtesy of Daniel Blezek)
  • improved handling of MGH/NGZ images
  • fix handling of large files on Windows
  • fix of the -shell option for dwi2fod msmt_csd (thanks to @isAarya for reporting!)

As always, you can update your install by performing a git pull followed by ./build at the command line (while in your MRtrix installation folder).

2

Deprecation of mtbin command and introduction of new mtnormalise command

Problems with the stability and some of the underlying theory of the method implemented by mtbin have become apparent, and the method has been radically overhauled to resolve these issues. Some of the issues with the original mtbin method could result in the introduction of extreme image intensity values in certain regions of the corrected images, which could in turn cause problems for subsequent steps in a typical fixel-based analysis pipeline (most notably the creation of or registration to a population template). When these issues manifested, the bias field and intensity estimation in the entire brain region was often affected as well.

After updating your MRtrix installation, the changes to take note of in this context are:

  • mtbin has been deprecated. Running it will by default produce an error message to highlight this. The description lists an option to override this behaviour and allow to consciously run the method anyway. However, we recommend against continuing to use it in any (fixel-based) analysis.
  • A new alternative method is available via the mtnormalise command. The interface and required inputs are similar to the previous mtbin method. The method has undergone thorough testing to perform up to expected standards.
  • The documentation of the multi-tissue fixel-based analysis pipeline has been updated to incorporate this new method.

We should also warn you that the previous version of MRtrix had an existing mtnormalise command, which implemented another method entirely. You should therefore take extra care to fully update your MRtrix installation before following the new (fixel-based analysis) instructions. The easiest way to check whether you are using the correct new mtnormalise command after updating, is to check for the presence of a “lognorm_scale” field/property in the header of the output images produced by mtnormalise. This can for instance be achieved by:

mrinfo wmfod_norm.mif -property lognorm_scale

This should produce a single number, which reflects the global scale detected (and corrected for) by the new mtnormalise method, assuming a log-normal distribution of the intensity normalisation factors (across the spatial domain). More information can also be found in the updated documentation of both the mtnormalise command and the multi-tissue fixel-based analysis pipeline.

Updated documentation for the multi-tissue fixel-based analysis pipeline

The fixel-based analysis pipeline has been updated / changed in a few places. The most notable change is the reintroduction of the dwibiascorrect bias field correction preprocessing step. Via experience in several (real) fixel-based analysis studies, we found that performing this correction early on in the pipeline has potentially important benefits for the subsequent dwi2mask brain mask computation, as well as the estimation of response functions for constrained spherical deconvolution. The new mtnormalise method, which sits further in the pipeline, is still essential for global intensity normalisation, but also accounts for further correction of (residual) intensity inhomogeneities. mtnormalise can automatically deal both with datasets that already underwent (partial) correction of bias fields, as well as datasets that are still entirely uncorrected for bias fields (and mtnormalise will in this scenario correct for those bias fields).

For dwibiascorrect, we still advise to use the ANTS N4 bias field correction algorithm via the -ants option, which requires an installation of the ANTS software. More information can be found in the documentation of dwibiascorrect and the updated multi-tissue fixel-based analysis pipeline. The default parameters used for the N4 algorithm have changed as well, in order to result in a more robust outcome (mostly beneficial for subsequent dwi2mask computation).

3

Fix to dwipreproc & phase encode handling

When all DWI volumes are acquired with reversed phase-encoding (i.e. not just b=0 images for estimating the inhomogeneity field), it’s possible to take each pair of DW volumes that have the same diffusion gradient direction, and combine them into a single volume, in a manner that accounts for the differences in information content when the two images are stretched / compressed relative to one another. This is performed when using the -rpe_all option, as well as the -rpe_header option if the input data are appropriate. However my initial testing of this functionality was not thorough enough, and a couple of users have encountered issues. It should hopefully now be working… :fearful:

There’s also been corresponding changes to the management of phase encoding information in image headers. Some users may have encountered a warning regarding “invalid phase encoding tables”. While this warning will still occur with existing data, newly-generated images will erase this information when it is no longer relevant such that this warning no longer appears.

4

Multi-volume lightbox mode for mrview

mrview's lightbox view mode now supports concurrently visualising multiple volumes for a single image across a grid. To enable this feature, switch to lightbox mode (View → Lightbox), then open the View tool (Tool → View) and select the Cycle through volumes tick-box. A user can additionally modify the Volume increment size to control the range of visible volumes.

This should prove useful for quick visual inspections of multi-volume data:

28414007-963ea502-6d41-11e7-9dcd-3d9426acc909
28414007-963ea502-6d41-11e7-9dcd-3d9426acc909.jpg1920Ă—1200 699 KB

1 Like
5

fixelcfestats now supports -mask option

Due to popular demand (including my own), fixelcfestats now has a new option -mask. Note that this is a fixel mask, not a 3D voxel mask image.

Additionally, during the process of implementing this, I changed some of the internal fixel stats code such that, for my own test case, I experienced a 75% reduction in execution time :muscle: (Note that in some instances, the memory usage of fixelcfestats may appear to drop drastically during permutation testing, e.g. from 50% to 4%; this is not cause for concern).

6

mrdegibbs: a new command to remove Gibbs ringing artefacts

This new command implements the method of local subvoxel shifts recently proposed by Elias Kellner et al. (Magn Reson Med. 2016; 76:1574-1581) to remove Gibbs ringing artefacts. This is likely to become an important part of the DWI preprocessing chain, given how prominent these artefacts can be particularly in the b=0 images, and their corresponding impact on the image analysis.

For optimal performance, we recommend you install the FFTW library (and associated headers), and re-run the ./configure step to make sure the command makes use of it. While FFTW is not a hard requirement (Eigen provides a decent fallback implementation), it does result in considerably faster execution (approximately half the runtime).

Note that this command has been added very recently, and has therefore not been subjected to any community testing. However, on our data, it provides identical results to the authors’ original implementation, while being substantially faster due to the use of multi-threading. We’re fairly confident in our implementation, but if you do notice any unexpected behaviour, please report it!

7

population_template voxel size handling

The voxel size of the template produced by population_template was previously automatically determined from the input images. However, this resulted in suboptimal outcomes under some circumstances, particularly when large rotations exist between the different input images. Furthermore, it became apparent that different voxel sizes were required in different scenarios. To deal with these issues, a new option has been added to population_template to allow the output voxel size to be set manually. We encourage users to set the desired voxel size of their template manually, as is now recommended in the fixel-based analysis documentation.

1 Like
8

correction to energy term in dirgen

The energy term assumed in the cost function for dirgen and other associated commands (e.g. dirstats, dirsplit, dirmerge, …) was incorrect, assuming a 1/r² relationship, when this should be 1/r (corresponding to a 1/r² repulsion force). Thanks to @Kerstin for reporting this.

This has now been rectified, and will change the directions generated by dirgen slightly, and also affect the energy values reported by dirstats. Thankfully, it seems the differences are minor, and not necessarily anything to worry about (see full discussion on GitHub for details).

In addition, dirgen has been modified to perform multiple random restarts (10 by default) to ensure a more globally optimal solution is found.

9

Improved handling of multi-type DICOM series

DICOM series can contain images with different ImageType tags, which can have different properties. This may mean that a single series might contain images with different dimensions or different data scaling parameters; in such cases, MRtrix3 applications would have failed to read the data, producing an error message indicating the reason. This is a common occurrence on Philips DWI data (which frequently includes a computed mean DWI image at the end), or Siemens reformatted (MPR) data (which typically includes a separate image indicating the orientation of the reformatted slices).

This update now splits these different ImageTypes out into distinct selections, making it possible to read these data correctly. This does mean that the datasets containing series with multiple ImageType data will show up with different numbering in the command-line selection menu than might have been the case to date (see discussion on GitHub for an example). This will hopefully only affect those users relying on these numbers to script their data imports - the numbers used will most likely need to be amended to match.

10

support for reading TIFF images

Rudimentary support has now been added to import TIFF images, whether as a series of individual slices, or as a single multi-page TIFF. RGB images will appear as 4D images with 3 volumes, one for each of the red, green & blue channels. Multi-page TIFFs will be loaded with each page assumed to correspond to a different slice.

To be able to use this fully relies on MRtrix3’s existing numbered image support to load a set of image slices or volumes. It will also most likely require further adjustments to various parameters, notably the voxel size, the orientation of the data, and the ordering of the axes.

Examples

To convert a set of single-slice RGB TIFFs as-is:

$ mrconvert tiff/images-[].tif out.nii

This will result in a 5D image, since each TIFF image is concatenated along the last dimension. In other words, the image will look something like this (assuming there were 64 TIFF images):

$ mrinfo out.nii
************************************************
Image:               "b0.nii"
************************************************
  Dimensions:        96 x 96 x 1 x 3 x 64

To deal with this, you can use the -axes option to permute the data:

$ mrconvert tiff/images-[].tif out.nii -axes 0,1,4,3

giving the expected result:

$ mrinfo out.nii
************************************************
Image:               "b0.nii"
************************************************
  Dimensions:        96 x 96 x 64 x 3

You can also use the -vox option to set the correct voxel dimensions, and if needed changes the order of the axes to rotate the data as required.

Loading a multi-page tiff is simpler since each page in the file is assumed to correspond to a different slice. Again, an RGB image will be imported as a 4D image. If required, a set of multi-page TIFF images can be imported as a single dataset using MRtrix3’s numbered file support.

In due course, we hope to add support for TIFF export (the issue is already listed on GitHub)