MRtrix3 version 3.0 (release candidate 1)

Announcements
1

MRtrix3 is finally about to come out of beta status and hit full release! This is the first release candidate for our forthcoming version 3.0 of MRtrix3, the result of many months of work, with many new features and improvements (see below). Hopefully the proper full release will follow shortly after a few weeks of community testing. You are all encouraged to upgrade and try it out - and if you do come across any issues, don’t hesitate to let us know, either on the community forum, or via the GitHub issue tracker: we’ll get them fixed straight away.

While the bulk of the functionality will behave as before, there are a number of changes in this version that you will need to know about, in particular:

Instructions for upgrading

The arrangement and naming conventions used in the repository structure have been altered, for reasons described here. This has the potential to introduce problems for users upgrading from previous versions - we therefore strongly recommend users follow the detailed upgrade instructions provided below.

Now that these instructions assume there was nothing unusual about your previous installation. If you needed to set any environment variables before, you will most likely need to do so again prior to running ./configure.

  1. update the code to the new version: $ git pull

  2. re-run the configure script: $ ./configure

  3. build the executables: $ ./build

    Note that this step will automatically remove your previous release folder if it exists. This is to avoid conflicts that might arise if the executables from the previous version of MRtrix3 remain in place and in your PATH.

  4. set your PATH to reflect the new location: ./set_path.

    Alternatively, you can add the MRtrix3 bin/ to your PATH yourself if you prefer. However, we recommend you use the ./set_path script to handle this step, unless you are comfortable with manipulating the PATH, use a different shell, or have other specific requirements.

    Note that if you had previously set your PATH manually, we recommend you remove this entry from the relevant shell startup script (most likely ~/.bashrc or ~/.profile).

  5. close your terminal, start a fresh one, and verify that the commands used
    are the correct ones, e.g.:

     $ mrinfo --version
 == mrinfo 3.0_RC1 ==
 ...

    Don’t worry if the version is reported as something like 3.0_RC1-3-gc4349e3f: this simply indicates that you are running a more recent version than 3.0_RC1 (in this example, 3 commits ahead, with latest git commit having SHA1 identifier c4349e3f).`

2

Changes to the file & folder layout

The layout of the code has been changed to make it consistent with the Filesystem Hierarchy Standard, which will greatly simplify the deployment of MRtrix3 across systems, and the process of providing pre-compiled versions of MRtrix3 (these will be provided with forthcoming official releases).

  • The configure script needs to be run afresh in order to test and set up certain new functionalities.

  • The location of compiled binaries and scripts has changed. Previously, binary executables were located in the release/bin/ folder, and scripts were placed in the scripts/ folder. Now all executable files will be located in the bin/ folder. Your PATH environment variable will therefore need to be updated to reflect this. If you have used the set_path script in the past, re-running this script after updating your MRtrix3 installation should make the necessary change to your configuration.

  • The release/ directory, previously used to store compiled executable and object files, will no longer be required, and can hence be deleted. The build script will attempt to do this for you to avoid any conflicts with previous installations.

  • The connectome lookup tables previously provided in src/connectome/tables/ have been moved to share/mrtrix3/labelconvert/.

3

Fixel format

The storage of fixel data on disk has been completely overhauled. Rather than the previously used “MRtrix Sparse File / Header (.msf / .msh)” format, fixel data is now represented using standard images stored in a directory that conforms to a newly-defined format. This increases the flexibility of what type of fixel data can be stored, improves the mrview user interface when visualising different parameters within the same set of fixels, and opens the data up for any users / developers who wish to access or manipulate this information directly. The new format is described in more detail in the documentation.

mrview will continue to support the old .msf / .msh format. Additionally, we now provide a new command fixelconvert for converting between the old and new formats.

4

New features

  • Support for NIfTI-2 images.

  • Support for JSON data. In MRtrix3, JSON files (with the file extension .json) can be used to store key-value fields associated with a particular image externally from an image header. This is useful for image formats that use a fixed-size header (such as NIfTI), and are consequently limited in the amount of associated data that can be stored within that header. If however you regularly use the MRtrix image formats (.mif, .mih), you will most likely not require this feature since these formats already allow any number of key-value fields to be stored directly within the header. Special thanks to JSON for Modern C++ for providing a great library to enable this functionality.

  • System signals (such as manually killing a process, running out of memory etc.) are now handled within the application, so that commands can produce more appropriate error messages, and additionally attempt to clean up any temporary files currently in use. This will hopefully reduce confusion around the dreaded invisible-error-messages and non-interpretable-error-messages that have been reported by a number of users. It should also minimise issues with running out of temporary storage. Note however that this functionality will be incomplete on Windows systems.

  • Some new header key-value entries:

    • command_history will keep a running list of the MRtrix3 commands used in producing an image.
    • prior_dw_scheme will store the diffusion gradient table used in generating an image, in cases where the image volumes no longer reflect the entries in the diffusion gradient table (e.g. after converting from DWIs to an FOD in spherical harmonic representation).

New executables

amp2response

Estimates a response function for spherical deconvolution, as is also performed by sh2response; but uses data from all single-fibre voxels concurrently, and enforces non-negativity and monotonicity of the response function. All dwi2response script algorithms will now use this command. Note also that by default all response functions will now be estimated at lmax=10.

connectomestats

Provides the Network-Based Statistic (NBS) method, and the novel threshold-free Enhanced NBS (NBSE) method (publication pending).

dwigradcheck

A script that attempts to determine whether or not there are erroneous permutations or flips in the diffusion gradient table, based on this method.

fixelconvert

A command to convert between the old .msf / .msh sparse image format and the new fixel directory format. Note that if performing bulk conversion of multiple subjects to conform to a particular fixel template, the -template option should be used in order to ensure that fixel correspondence is maintained.

mrhistmatch

Performs non-linear histogram matching between two images, in the hope of being somehow useful.

mtbin

Multi-Tissue Bias field correction and Intensity Normalisation. Simultaneously estimates a B1 bias field, and modulates the amplitude of tissue response functions to converge the sum of tissue volumes toward unity in every voxel.

transformcompose

Combine multiple linear transformations and/or non-linear warps into a single transformation, such that only a single image interpolation step is needed when undergoing multiple transformations.

vectorstats

Simply performs FWE-controlled permutation testing where the input data consist of a vector of values per subject.

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).