MRtrix 3.0 (release candidate 3)

Announcements
1

We are pleased to announce the immediate release of our third release candidate, tagged as 3.0_RC3, which brings a large number of improvements and bug fixes. We recommend users upgrade as soon as practical, using the usual procedure, with an additional call to configure:

git pull
./configure
./build

Of the many changes introduced in this release, one is particularly important, and described in detail below. See subsequent sections for the full changelog.

Important changes in tckgen

The most important bug fix, and primary motivation for pushing out this candidate release now, concerns a mistake in our handling of spherical harmonics, introduced in version 0.3.11 (originally released on 12 Feb 2014). The good news is only one MRtrix3 command is affected by this bug. The bad news is that the command affected is tckgen, a prominent component of any tractography analysis.

Since uncovering this bug, we have spent some time investigating its likely impact in various practical situations, and trying to get a feel for the severity of the issue – (see full discussion on GitHub in issues 1204 and 1206). While it’s difficult to quantify its effect on tractography output, we feel that the impact, while undeniable, is likely to be minor, and likely to be countered by the subsequent application of SIFT/SIFT2. We are therefore confident that this bug is unlikely to introduce any detectable biases in quantitative tractography analyses, and is also unlikely to lead to any observable differences in other applications (e.g. targeted tractography studies).

However, fixing this bug also prompted us to revisit the fODF threshold used during tracking (the -cutoff option in tckgen). The primary impact of this bug consisted of an overestimation of the fODF amplitude, which in effect means that tractography was performed with a lower cutoff than specified. The optimal value for the cutoff is somewhat subjective and context-dependent: there are differences in output between regular single-shell CSD and its more recent multi-shell multi-tissue variant (respectively, the csd and msmt_csd algorithms in dwi2fod), and different requirements for anatomically-constrained tractography. Based on a comprehensive comparison of the output of tckgen under the various relevant conditions, we came to the conclusion that a reduction of the default cutoff value to 0.05 was warranted (from its previous value of 0.1). Note that while manually specified thresholds will not be affected by the change in the default value, the output produced will nonetheless differ somewhat due to the bug itself.

All the best from the MRtrix3 team!

2 Likes
2

Interface changes

  • dwi2noise: Removed from the repository in favour of -noise option in dwidenoise.

  • dwipreproc: -cuda option removed. The script will instead automatically detect the presence of a CUDA version of eddy; if this is run but fails, the script will then instead run the OpenMP version of eddy (if present).

  • fod2dec: Option -outputmap renamed to -contrast.

  • mesh2pve: Renamed to mesh2voxel, for consistency with other command names e.g. fixel2voxel, voxel2fixel, voxel2mesh (formerly mrmesh).

  • mrinfo: Options -shells and -shellcounts renamed to -shell_bvalues and -shell_counts to avoid ambiguity with renaming of -shell to -shells in other commands.

  • mrmesh: Renamed to voxel2mesh for consistency with other command names, e.g. fixel2voxel, voxel2fixel, mesh2voxel (formerly mesh2pve).

  • mtbin: Removed from the repository in favour of mtnormalise.

  • tcknormalise: Renamed to tcktransform, for consistency with other command names related to spatial transformation & separation from other command names related to intensity normalisation.

  • warpconvert: Change conversion type from a command-line option to a compulsory argument.

  • Multiple commands:

    • -failonwarn: Removal of -failonwarn option from all commands. This behaviour can still be controlled via the FailOnWarn MRtrix3 config file entry.
    • -shell option: This has been renamed to -shells, to reflect the fact that in many instances more than one b-value shell may be specified.
    • -stride: -stride option has been renamed to -strides to reflect the fact that strides for all image axes must be specified.

Enhancements

  • 5ttcheck: Better reporting of number and severity of issues detected in 5TT format compliance.

  • 5ttgen gif: New 5ttgen algorithm. Converts the results of the Geodesic Information Flow (GIF) algorithm into the 5TT format.

  • dirstat:

    • A much wider range of direction set statistics are calculated and reported.
    • Support for multiple types of input: az-el pairs, x-y-z triplets, x-y-z-b gradient tables, image-header-embedded DW schemes.
    • -output option to simplify script interfacing.

  • dwibiascorrect -ants:

    • Command-line options: Additional command-line options for controlling N4 bias field estimation.
    • Scaling: Globally scale magnitude of bias field estimated by N4 in order to prevent gross differences in DWI magnitudes between subjects.

  • dwipreproc:

    • -align_seepi: New option. This can be used in cases where spin-echo EPI images are explicitly provided via the -se_epi option. It ensures alignment between estimation of the inhomogeneity field in topup, and application of the inhomogeneity field in eddy. Note however that this option should not be used if the SE-EPI images and DWI b=0 images do not have matching contrast.
    • -cuda option: Better detection of binary path for CUDA version of eddy based on CUDA version numbers.
    • -eddyqc options: New options -eddyqc_text and -eddyqc_all to export various outputs (either only text files, or both text and images) from eddy for quality control.
    • Non-spherical acquisition schemes: DWI acquisitions where diffusion sensitisation gradients are not evenly distributed over the sphere are detected, and use of the --slm=linear option in eddy recommended.
    • Odd axis sizes: When input images have an odd size along a spatial axis, pad rather than truncating images (to achieve topup compatibility), and remove the padding afterwards. This gives the output image series the same dimensions as the input.
    • Slice-to-volume correction: Support for slice-to-volume correction in eddy. Where possible, relevant acquisition protocol information will be captured from DICOM, stored in image headers, and used to provide slice axis & timing information to eddy automatically.

  • fod2fixel: New option -maxnum, to specify maximum number of fixels per voxel.

  • labelconvert:

    • HCPMMP1: New files share/mrtrix3/labelconvert/hcpmmp1_original.txt and hcpmmp1_ordered.txt for visualising the Human Connectome Project (HCP) Multi-Modal Parcellation (MMP), and conversion to parcel indices incrementing from 1 for the purpose of connectome construction.

    • LPBA40:New file share/mrtrix3/labelconvert/lpba40.txt for converting LPBA40 parcellation.

  • mrcalc: New option -replace, to replace all instances of some value with some other value.

  • mrcat: Operates using native type required to support input images (including complex types).

  • mrdegibbs: Automatic detection of slice encoding direction where applicable.

  • mrhistmatch: New algorithms for matching contrast between images that are linear rather than non-linear. This is for matching images that are of the same modality and comparable contrast, but raw intensities are not identical.

  • mrtransform: New option -strides.

  • mrview:

    • Command-line: Additional options: -target, -overlay.colour, -overlay.intensity, -overlay.threshold_min, -overlay.threshold_max, -overlay.no_threshold_min, -overlay.no_threshold_max, -roi.colour, -tractography.lighting

    • Connectome tool: Improved mechanism for controlling which edges are visible based on visibility of the connected nodes.

    • Tractography tool: Support for different display geometries for streamlines within the tractography tool: Pseudo-tubes (current behaviour & default), lines (older MRtrix behaviour), points. Behaviour can also be set via new command-line option or config file entry.

  • sh2peaks: New option -fast; uses SH precomputer rather than SH transformation matrix.

  • tckdfc: New command. Provides the Track-Weighted Dynamic Functional Connectivity (TW-dFC) method.

  • tckmap: New option -backtrack. Does something similar to back-tracking in Anatomically-Constrained Tractography (ACT): If seeking to sample underlying image values at streamline endpoints, but no valid image information appears underneath the streamline endpoint, back-track along the streamline until valid image data are found.

  • tckstats: New option -explicit. Explicitly calculate the length of each streamline based on the distance between every pair of vertices, rather than relying on the step size information stored in the header. This should be used whenever the step size information is known to be untrustworthy, or a non-rigid transformation has been applied to the streamlines data.

  • tsfvalidate: New command. Performs a comprehensive validation of a Track Scalar File (.tsf) against the corresponding track file (.tck), to ensure that not only do the relevant header entries match, but also that the number of tracks and number of vertices / values within each track match exactly.

  • warpinvert: New command. Calculates the inverse of a non-linear warp field.

  • Continuous Integration Testing:

    • OSX: CI testing is now performed for OSX in addition to Linux.
    • pylint: Python scripts and libraries are verified using pylint to reduce prevalence of coding errors.
    • Documentation:
      • Correspondence between code and auto-generated documentation is verified before code can be merged (which could otherwise result in mismatches between executable commands and their online documentation).
      • Errors and warnings in online documentation generation are detected, to prevent missing links from appearing online.

  • DICOM import:

    • Siemens CSA: Support Siemens CSA data that is stored using a wider range of identification codes.
    • Slice timing: Capture information relating to slice encoding & slice timing.
    • Philips private fields: Recognition of a larger number of Philips private fields.
    • Date & time: Better import & display of date and time information.

  • JSON import/export: Better support of non-trivial data, e.g. arrays / matrices.

  • Multiple commands:

    • 5ttgen fsl and labelsgmfix: Automatically up-sample T1 image provided to FIRST if input image is of a lower resolution; this should reduce prevalence of FIRST failures.
    • Directory input/output: Native support for command-line arguments / options as file system directories. This will hopefully reduce mis-use of commands that use the new fixel directory format.
    • Lookup tables: More informative error message when connectome look-up table (LUT) file reading fails.
    • MRTRIX_CONFIGFILE: Use MRTRIX_CONFIG environment variable to set location of MRtrix3 configuration file.
    • MRTRIX_QUIET: Use MRTRIX_QUIET environment variable to suppress non-critical terminal output from all MRtrix3 commands.
    • Parcellation images: Better warnings / errors when interpreting input images as integer label images (e.g. parcellations).
    • Versioning: Better reporting of build date in version information, and robust checking of compatibility between binary executables and shared library.
    • -stride option: A template image can be provided as input to this option to define the axis data strides of output images.
    • -version output: The build type requested in the configure script will be reported in each command’s -version output.

  • Multi-threading: Distinguish between implicit and explicit multi-threading concurrency requests, for rare cases where this alters how many threads MRtrix3 should in fact spawn.

  • Python scripts:

    • -debug option: When using the -debug option, command-line outputs of nested executables will be indented, for better distinguishing what text is emanating from each level of execution.
    • Exception handling: Better handling of errors emitted when internal Python functions are called but fail.
    • Progress bars: A progress bar comparable to that used in MRtrix3 binary commands is utilised in some scripts where appropriate.

Fixes

  • 5tt2gmwmi: Fix operation of -mask_in option.

  • 5ttgen fsl: Fix use of -mask option when mask does not match share voxel grid with T1 image.

  • configure: Better detection of FFTW3 libraries (for mrdegibbs) using pkg-config.

  • dwi2mask: Fix command operation when image intensities are all below 1.0.

  • dwigradcheck: Fix operation when no brain mask is provided, and gradient table is provided via -grad or -fslgrad options rather than the input image header.

  • fixel2tsf: Prevent issues in correspondence between Track Scalar Files (.tsf) and track files (.tck) where underlying fixels contain non-finite values.

  • fixelcfestats: Fix subject file import issue arising from empty lines in text file.

  • label2colour: Fix for when the command is used without an explicit lookup table (i.e. randomised node colouring).

  • mrtransform: Fix application of a non-linear warp field that does not lie on the same voxel grid as the template image.

  • mrview:

    • Connectome tool: Fix issue displaying nodes using surface mesh geometry, caused by attempting to load .obj file using a different localisation to that used when saving the file.

    • Lightbox mode:

      • Rendering: Fix inconsistent rendering of tool contents in lightbox view mode.
      • Memory error: Fix memory error that could occur when altering the number of rows / columns in lightbox mode.

    • Overlay tool: Ensure that -overlay.* options are only applied to the overlay image that last appeared on the command-line using the -overlay.load option.

    • Touchpads: Fix issue with use of pan gesture on touchpad resulting in mrview becoming unresponsive.

    • Tractography tool: Fixes to streamline visualisation with large line thickness: better calculation of streamline downsampling ratio, and ensure streamline endpoints are always drawn.

    • Volume render: Fix volume render mode on ATI hardware.

    • ROI tool:

      • Black ROIs: Fix some ROIs being automatically coloured as (almost) black.

      • Save-on-exit: Fix ROI tool save-on-exit popup window on Qt4.

  • population_template:

    • Input fix: Python 2/3 compatibility fix when requesting user input.
    • numpy: Fix handling of linear transformation text files with certain versions of Python.
    • Windows: Prevent file metadata issues when run on Windows.
    • -voxel_size option: Fix use of -voxel_size option when defining anisotropic template voxels (using comma-separated values).

  • set_path: Fix automatic detection of binaries location on Windows.

  • tckconvert:

    • ASCII VTK: Proper error message on attempting to read an ASCII-based VTK file.
    • Edge cases: Fix errors that arise when reading / writing empty track data in certain formats.

  • tckgen:

    • Documentation: Fix reporting absence of -select option (previously renamed from -number) when using dynamic seeding.
    • -backtrack: Fix sporadic memory issue when -backtrack is used with a tractography algorithm other than iFOD2.

  • tckmap: Fix combined usage of -dec and -stat_vox mean options.

  • tcknormalise (Note: now tcktransform): Proper handling of streamline vertices (or indeed entire streamlines) that lie outside the valid non-linear warp field data, with the output track file preserving the total number of streamlines in the input file (even if some of those streamlines now have zero vertices).

  • tckresample:

  • tckstats: Prevent command crash when input track file is empty.

  • warpinit: Make output warp field use the same axis strides as the input template image.

  • DICOM import:

  • Multiple commands:

    • dwiintensitynorm and population_template: Ignore hidden files in input directories.
    • labelsgmfix and 5ttgen fsl: Better detection of outcome of FSL FIRST command; should give more informative progress & error messages.
    • Memory mapping: Attempt to terminate commands gracefully if a problem is encountered during writing of a memory-mapped file.
    • MGZ format: Fix handling of matrix data imported from MGH image file format.
    • SH peak finder: Fix behaviour of SH peak-finding algorithm near the Z-axis.
    • SH precomputer: Fix bug in Spherical Harmonic “precomputer”. This resulted in biased calculation of FOD amplitudes in tckgen, and biased FOD peak amplitudes in fod2fixel.
    • Statistical inference: Fix segmentation fault in statistical inference commands when using the -nonstationary option.
    • Streamline weights: Fix streamline weights export bug, where output weights file was erroneously reported as already existing.

  • Python libraries:

    • Encoding: Non-UTF-8 data generated by executed commands no longer crash scripts.
    • File paths: Proper handling of file paths when temporary directory / current working directory contain spaces.

  • Signal handling: Fix setup of signal handler and its interaction with command initialisation / display of help pages.

  • Windows: Improve consistency of / support for the different Python versions provided in MSYS2.

Other changes

  • build: New option -persistent to enhance Continuous Integration testing.

  • configure: New option -nooptim (no optimisation) to enhance Continuous Integration testing.

  • dwibiascorrect: Altered N4 bias field estimation parameters to reduce subsequent brain masking issues.

  • mrconvert: More comprehensive description of command-line options in help page.

  • Compressed image formats: More expressive messages to indicate when errors occur in handling GZ files specifically.

  • Config file: Various fields renamed for consistency in overall name formatting of config file entries.

  • Documentation:

    • dwipreproc: Information on support for eddy's slice-to-volume correction.
    • Deployment: Information on MRtrix3 deployment.
    • Fixel-based analysis (FBA): Widespread changes based on latest experience.
    • Fixels: Re-arranged concept page describing fixels (and dixels).
    • MGH format: Information on MGH image format custom header information support.
    • Phase encoding: New page describing MRtrix3’s handling of phase encoding information.
    • Template registration: Additional FAQ page entry on template registration / projection of atlas parcellation to subject space.
    • Various: Various changes.

  • Multiple commands:

    • Connectome lookup tables: More informative error messages for those trying to create their own lookup tables and have MRtrix3 import them successfully.
    • Image transforms: Improved detection of when the transforms of different images do or do not match.

  • Python libraries:

    • image.Header class: Access to image header information within Python scripts simplified through use of this new class.
    • External tools: Support for external tools that modify the default command-line option set provided by the library.
    • app.debug() and app.var(): Enhanced debugging capabilities through these functions, for printing messages and variable values that also include code location.
    • System signals: Better handling of various system signals, handling cases where signals are received inside or outside of external command calls, and across OS’s.

  • Spherical Harmonic basis:

    • build and configure: Removal of support for legacy non-orthonormal SH basis.
    • shbasis: Removal of -native conversion option. Note that this command will likely be removed entirely in a future update.

  • Tractography code: Modifications to improve external utilisation of this code (polymorphism).

2 Likes