MRtrix3 version 3.0 (release candidate 1)

Announcements
5

Other modifications

Documentation

The online documentation has undergone a reasonable amount of re-structuring. This means that any hyperlinks to specific pages within this documentation that have been generated externally to the MRtrix3 documentation itself may no longer work. However it should still be easy to find any information required from the documentation home page or the sidebar.

Eigen 3.3

MRtrix3 should now be compatible with, and where possible make full use of, the improvements provided in Eigen version 3.3.

FOD segmentation

The results of FOD segmentation (whether through fod2fixel, or a command that performs FOD segmentation internally such as tcksift) will differ to those generated before version 3.0_RC1. This influences both the number of fixels extracted, and the calculation of lobe integrals. Results of such processes should therefore not be mixed between 3.0_RC1 and prior software versions.

Scripts

The Python scripts provided with MRtrix3 will now by default create a temporary working directory within the working directory (i.e. the directory your terminal is pointing to when you execute the script), rather than /tmp/. This may reduce performance in some cases, but will hopefully alleviate issues with users running out of storage space during script execution. The temporary directory location can still be overridden using the -tempdir option, or by setting ‘ScriptTempDir’ in the MRtrix3 config file.

There is also a new option -debug to provide an additional layer of verbosity, for when things really go awry.

Changes to specific commands and scripts

5ttgen

A minor error in 5ttgen fsl was resulting in some voxels not quite having a sum of partial volume fractions of 1.0. This is not ideal, but should not influence the results of tracking. The issue has been rectified, and a new command 5ttcheck can be used to test whether or not a particular image conforms to this requirement in addition to the fundamental 5TT requirements.

dwipreproc

  • The interface for the dwipreproc script has been altered. Users are referred to the new documentation page for this script that compares old and new usage. It is also recommended that users be initially critical of the outputs provided by this new version of the script, since it has not undergone the same extent of testing as the previous version.

  • During DICOM import, MRtrix3 will attempt to capture information relating to the phase encoding used during EPI readout. This information can then be used during image pre-processing using dwipreproc -rpe_header, rather than relying on the user to manually specify how their images were acquired. Some more technical details in this comment if anybody is interested.

population_template

The arguments and default parameters for the population_template script, which generates an unbiased group-average template from a series of images, have been modified to be more consistent with those of mrregister.

  1. Template creation defaults now to run multi-scale rigid registration stages before affine before nonlinear registration stages. The previous default was to start with affine registration.

  2. Any two of the rigid, affine and nonlinear registration stages are now optional.

  3. We changed arguments to be more consistent with mrregister:

    • the option -type specifies the order of stages to run. Default: -type rigid_affine_nonlinear
    • option names referring to either affine or rigid registration are changed
      from -linear_xx to -rigid_xx or -affine_xx depending on which type
      or registration they refer to. Common options remain (i.e.
      -linear_estimator).

The default parameters for the linear registration stages are:

    (00) rigid     scale: 0.3000, niter: 100
    (01) rigid     scale: 0.4000, niter: 100
    (02) rigid     scale: 0.6000, niter: 100
    (03) rigid     scale: 0.8000, niter: 100
    (04) rigid     scale: 1.0000, niter: 100
    (05) rigid     scale: 1.0000, niter: 100
    (06) affine    scale: 0.3000, niter: 500
    (07) affine    scale: 0.4000, niter: 500
    (08) affine    scale: 0.6000, niter: 500
    (09) affine    scale: 0.8000, niter: 500
    (10) affine    scale: 1.0000, niter: 500
    (11) affine    scale: 1.0000, niter: 500

Those for nonlinear registration stages remain:

    (00) nonlinear scale: 0.3000, niter: 5
    (01) nonlinear scale: 0.4000, niter: 5
    (02) nonlinear scale: 0.5000, niter: 5
    (03) nonlinear scale: 0.6000, niter: 5
    (04) nonlinear scale: 0.7000, niter: 5
    (05) nonlinear scale: 0.8000, niter: 5
    (06) nonlinear scale: 0.9000, niter: 5
    (07) nonlinear scale: 1.0000, niter: 5
    (08) nonlinear scale: 1.0000, niter: 5
    (09) nonlinear scale: 1.0000, niter: 5
    (10) nonlinear scale: 1.0000, niter: 5
    (11) nonlinear scale: 1.0000, niter: 5
    (12) nonlinear scale: 1.0000, niter: 5
    (13) nonlinear scale: 1.0000, niter: 5
    (14) nonlinear scale: 1.0000, niter: 5
    (15) nonlinear scale: 1.0000, niter: 5

mrregister

Added convergence check to speed up the linear registration. This may affect linear registration results.

mraverageheader

We changed the way the average space is calculated to allow input images that have coordinate systems rotated towards each other by angles larger than 90 degree. mraverageheader still defines the average space coordinate system to be unbiased in terms of rotation between input image coordinate axes and average space axes but the axes in both coordinate systems do not need to be the same axes or point in the same direction. This may affect registration results.

mrstats

  • Some of the functionalities of mrstats have been moved to other commands, both to make them more discoverable and to make mrstats more amenable to its own enhancements:

    • mrhistogram: Histogram generation (formerly mrstats -histogram.

    • maskdump: Write the positions of non-zero voxels in a mask image (formerly mrstats -position), either to terminal or to a file.

    • mrdump: Dump the image intensities (formerly mrstats -dump), either to terminal or to a file.

  • It is now possible to calculate image statistics across all volumes (-allvolumes option), rather than generating each statistic for each individual volume.

mrview

The focus cursor position can now be copied to the clipboard and written to the terminal using mrview's View options --> Position --> copy. This can come in handy for certain operations, for example providing spherical ROIs to tckgen, or selecting landmark for alignment using transformcalc's new -align_vertices_rigid option (see below).

shview

Multi-shell response functions are now better handled. The display indicates which row of the response file is being shown (i.e. which shell), and the scaling of the response now behaves much more sensibly.

tckgen

The interface and behaviour of this command with respect to streamlines seeding and selection for inclusion in the output track file have been altered to clarify the logic. Of particular interest for users will be the renaming of these two crucial command-line options:

  • -number is now accessed through -select.

  • -maxnum no longer exists, but its approximately equivalent replacement is -seeds.

Previously, -maxnum influenced the maximum number of streamlines that would be generated, irrespective of the desired number of streamlines to be written to the output file. In practise however it tended to be used / interpreted as setting the number of streamline seeds, which is subtly different (some seed positions might not be suitable for generating tracks, e.g. if below threshold or outside the brain mask).

Therefore, the new behaviour is to explicitly control the number of streamline seeds using the -seeds option; and for each seed point attempted, the algorithm will perform a more exhaustive search for an appropriate initial tracking direction.

In addition, the command’s progress message will dynamically report the number of streamline seeds, the number of streamlines actually generated from those seed points, and the number of streamlines selected and written to the output file (previously only the latter two were reported).

The -info option can still be used to report more detailed statistics on how the tracking performed (with respect to e.g. why generated streamlines aren’t being selected and written to the output file).

transformcalc

A new option -align_vertices_rigid has been added to calculate the appropriate rigid transformation to align landmarks in scanner coordinates. This can be used in conjunction with landmarks selected in mrview, using its new copy focus position feature (described above).