MRtrix 3.0.3 release

Announcements
1

We are pleased to announce the immediate release of MRtrix 3.0.3.

This is a bug fix release. We recommend users upgrade as soon as practical, using the instructions provided on our downloads pages (for precompiled packages), or the usual procedure for installations from source.

The full changelog is attached below. Noteworthy changes include:

  • When loading a DICOM directory containing multiple patients and/or studies, the order in which they are presented for user selection may differ from previous behavior. Therefore, any user scripts that automatically perform such selections may need to be revised; but the updated code now ensures that these orderings are sensible and reproducible;

  • We now provide official MRtrix3 containers, offering an alternative platform by which to utilise MRtrix3 tools;

  • Further fixes to handling of phase encoding data when stored in sidecar files, which hopefully resolves issues encountered by those with complex phase encoding acquisition strategies and/or interacting with those data directly.

All the best from the MRtrix3 team!

2

Software distribution

  • Container recipes
    We now include recipe files for both Docker and Singularity within the code repository, providing an alternative mechanism for utilising the MRtrix3 software. The pre-built container is available on DockerHub.
    As many will know, a number of the Python scripts provided as part of MRtrix3 invoke tools from neuroimaging softwares other than MRtrix3; and in the absence of those external tools, these scripts cannot function. These containers include only the components of those external tools that are utilized by MRtrix3 scripts; they do not provide comprehensive functional installations of those other softwares. This is achieved using NeuroDocker minify, and reduces the total size of these containers.
    If however you have an analysis pipeline that depend on many functionalities from many neuroimaging software packages, then you may prefer to instead construct a container that encapsulates all of these dependencies. The intent of these official MRtrix3 containers is to only provide container-based execution of MRtrix3 commands.
    As with usage of these scripts in any other context, please ensure that the research methods and non-MRtrix3 neuroimaging software packages utilized by these scripts are appropriately cited and acknowledged.

Software-wide changes

  • Change b-value scaling for zero-length vectors
    Diffusion gradient table entries with a zero-length vector but a non-zero b-value will now by default be interpreted as a b=0 volume. Note however that DWI data from Philips scanners can append to the end of a DWI series a reconstructed volume containing the mean DWI intensity, and with this change such volumes may be erroneously interpreted as a b=0 volume (a terminal warning will notify you of this assumption).

  • Fixes to phase encoding handling
    When exporting a phase encoding table to sidecar file(s), which is to reside alongside an image that MRtrix3 will automatically perform permutation / flipping of axes in order to approximate an axial acquisition (NIfTI / Analyse / MGH), apply those same permutations / flips to the phase encoding table, so that the data contained within will appropriately correspond to the saved image data.
    This fix will primarily affect:

    • Anyone who has used the mrconvert -export_pe_table or export_pe_eddy command-line options.
    • Anyone possessing data with phase encoding strategies other than basic polarity reversal (e.g. 4 phase encoding directions), where dwifslpreproc may have previously provided incorrect phase encoding information to FSL’s topup / applytopup / eddy.

  • Transparently handle UTF-8 dashes as regular ones
    (Thanks for report @mschira and others)
    Ensures that commands copy-pasted into the terminal from documents where dashes have been auto-corrected to other forms of dashes will still work.

  • New envvar MRTRIX_LOGLEVEL
    (Thanks for report @sebastientourbier)
    This environment variable modulates the terminal verbosity of commands in the same fashion as the -quiet / -info / -debug command-line options.
    This capability is additionally utilized to prevent errors with Python scripts when running in an Anaconda environment and utilizing the -debug flag.

  • Enable double-click opening of quarantined files on MacOS

  • MGH/MGZ: Fix Colortable V2 write
    MGH / MGZ images generated by newer versions of FreeSurfer, which contain “Colortable V2” data, will now have those data read correctly by MRtrix3, and MRtrix3 can write those data back to MGH / MGZ files that will be properly interpreted by FreeSurfer commands.

DICOM handling

Multiple-command fixes

  • GLM: Fix all_stats() segfault
    Fixes crash in specific use case where both element-wise design matrices are used, and at least one F-test is requested.

  • Inference: Fix for exotic usage
    Fixes case where GLM varies between elements (either due to the presence of non-finite values, or the addition of element-wise design matrix columns) and variance blocks are defined.

  • Fix help page for algorithm module
    (Thanks for report @crossmanith)
    For Python scripts based on the algorithm module, command-line options cannot be specified before the name of the algorithm to be used; these get ignored by the command-line parser. The example usage in the documentation however violated this.

Individual command fixes

connectome2tck:

dirorder:

  • Fix segfault
    (Thanks for report @mlyon)
    Fixes diroder in the rare scenario where the number of directions is 6 or fewer.

dwi2response:

dwidenoise:

dwifslpreproc:

  • Compatibility between image padding and EddyQC
    (Thanks for reports @Jottoy,
    Fixes usages involving the combination of an odd number of slices, use of eddy's slice-to-volume correction, and invocation of EddyQC.
  • Fix to b=0 volume matching
    (Thanks for report @Elijah)
    Ignore inconsequential differences in b=0 “directions” when identifying matching DWI volumes with opposing phase encoding directions.
  • Handle non-ascii data in eddy error outputs
    Prevents dwifslpreproc from crashing if the text outputs generated by failed FSL commands include non-text data.
  • On -rpe_pair, ensure -se_epi is 4D
    (Thanks for report @dubergonzoni)
    Provide a more meaningful error message if attempting to use the -rpe_pair option but erroneously providing a 3D image.
  • Fix for rare usage
    Fix case where there is no phase encoding contrast present in the SE_EPI images (and hence they need to be combined with the DWI b=0 data for topup to possibly be applicable), and also the SE-EPI volumes are defined on a different image grid to the DWIs.

dwigradcheck:

dwishellmath:

for_each:

  • Fix use of regex for entry exclusion
    If passing many filesystem paths to for_each using wildcard(s), but a subset of those files should not be processed by for_each, it is possible to specify a Regular Expression via the -exclude option to select those inputs that should be ignored.

labelconvert:

mrregister:

mrview:

mtnormalise:

population_template:

tckglobal: