MRtrix 3.0.4 release

[jdtournier]

Full changelog

---

Package setup

• configure: ignore CFLAGS & LDFLAGS from qmake
  Prevent the LTO options introduced with Qt 5.15 from causing non-trivial conflicts with clang++.

• Eigen 3.4 compatibility
  Fixes compilation from source on macOS, since homebrew now ships with Eigen 3.4.

• Fix MIME & icon handling on linux
  On Linux, the ./install_mime_types.sh command should now produce a working launcher for mrview, with recognised mime types that launch correctly and show up with the MRtrix icon.

• build: Fix build progress
  Prevents the different lines on the build progress feedback from claiming that there are different numbers of total compilation tasks.

Containers

• Multiple changes (2):
  • Embed licenses of external neuroimaging software packages in the container.
  • Fix missing FSL command fslsplit when running dwifslpreproc with -eddy_options " ... --cnr_maps ..."
  • Fix direct invocation of Singularity containers as executable
  • Fix mrview appearance in Singularity when built based on the Docker container.
  • Various fixes to mitigate warning messages when invoking containerized mrview
    (Note that some of these involve revisions to documentation instructions)

Documentation

• CONTRIBUTING.md: General revisions (2)
  Based on interactions with both internal and external contributors, revise and clarify documentation page that provides guidance for generation of novel MRtrix3 contributions.

• Fix link to advanced debugging help page
  Replace dead hyperlink with one to relevant wiki page on community forum.

• Fixels (and Dixels): Double negative typo
  Tiny fix affecting Fixel docs page

• README.md: Add Twitter reference
  Thanks to BIDS Specification for the idea.

Specific commands

• connectomestats:

  • Output paths
    Change output paths for some files to be consistent with other statistical inference commands.

  • Fix GLM mode selection
    Improve execution speed in case where design matrix is identical per edge, and fix operation in case where design matrix changes per edge.

• dwicat: Support 3D images
  Fixes processing when an input image to dwicat is a 3D image containing a single b=0 volume.

• dwifslpreproc:

  • Strip DW encoding from padding slice
    Prevents an error regarding absence of a diffusion gradient table following the applytopup step.

  • Refine slspec modification Corrects use case where slice encoding direction is negative, slice-to-volume correction is used, the number of slices is odd, and EddyQC is invoked.

• dwi2response manual: avoid unnecessary brain mask calculation
  This algorithm is based entirely on manual selection of voxels, and therefore execution of a brain masking algorithm is superfluous. This step is now appropriately skipped.

• mrconvert: Fix gradient table export
  Export external gradient table files in the specific use case where only a linear transform is applied.

• mrclusterstats: Fix for multiple variance groups
  Where multiple variance groups are used, command was erroneously trying to write the standard deviation map for all variance groups to a single image path.

• mrtransform: DWI grad export
  Where it is requested that the DWI gradient table be exported to an external file, such export erroneously did not occur if only a linear transform was applied.

• mrview:

  • Fix -tractography.tsf_colourmap option
    Fixes handling in cases of erroneous usage.

  • ODF tool: Permit SH lmax=0

  • Connectome tool: fix display of empty nodes
    Permits use of tool for parcellations that have not been converted in order to increment sequentially from 1.
    Thanks for report @adsouza.

• population_template: Correct transformation of mask data
  Where initial alignment was explicitly disabled by the user, mrtransform was erroneously applied to the last contrast instead of the mask.

• tckconvert:

  • Capability to write binary .vtk files
    New command-line option -binary, which applies only to the .vtk format.

  • PLY output: Fix incorrect face orientation
    The cap placed on the end of each streamline was previously incorrectly oriented, resulting in erroneous interpretation in 3D printing software.

• tcksift2: Fix fixel masking
  Fixels that are only traversed by a solitary streamline will now be excluded from the optimisation as originally intended.

• tensor2metric: avoid crash when supplying input with wrong size
  Check if the input image consists of 6 volumes, and thus can be interpreted as tensor data.

• population_template: Fix incorrect handling of masks when using -initial_alignment none
  When no initial alignment was requested, the last available contrast was transformed as opposed to the mask. This would lead to unwanted behaviour (in case of a scalar contrast) or an exception (in case of an ODF). Only affected outcome of population_template when initial alignment was explicitly turned off, so most studies are probably not affected.

• mrclusterstats: Fix incorrect writing of standard deviation maps when using multiple variance blocks
  When multiple variance blocks were specified with the -variance option, all of the output standard deviation maps were written to the same file instead of a different file per variance block.

Multiple commands

DICOM handling

• Various Philips data handling updates:

  • Ignore unwanted fields in Philips data
  • Capture additional orientation information in Philips data
  • New environment variable MRTRIX_PRESERVE_PHILIPS_ISO can be set to override the MRtrix3 default behaviour of ignoring the pre-generated trace-weighted image.

• Import additional Siemens enhanced fields
  Fixes absent fields SliceTiming, EchoTime, MultibandAccelerationFactor & SliceEncodingDirection for some data.

• Fix XA10A data parsing
  Thanks to @neurolabusc for contributions to resolving these issues.

• Fix GE data gradient table import
  Thanks to @blezek for reporting, @neurolabusc for assistance in diagnosis and rectification, and Jaemin Shin for testing, providing test data, and providing insights from GE.

PNG handling

• Export: Exception on too few axes
  If command-line usage results in too few axes to produce one or more meaningful PNG images, produce a meaningful error message rather than crashing.

Streamlines data

• Avoid invalid memory access when ROI is malformed in tck header
  If a .tck file header contains an entry for the ROI that doesn’t have the expected 2 fields, this leads to a segfault when using e.g. tckinfo or tck2fixel. The change here consists simply of making sure that if only one token is parsed, a second empty string is added as the second, which then avoids the invalid memory access, and permits these headers to be used (the alternative is simply to ignore them, but I’m not sure that’s the best thing to do here).

APIs

Matlab

• Multiline key-value metadata
  Added handling of struct field with cell array values, which otherwise cause an error as fprintf doesn’t take cell array arguments.

Python

• mrtrix3.run: Fix default MRTRIX_LOGLEVEL
  Default value for environment variable MRTRIX_LOGLEVEL was being erroneously written as an integer type rather than a string. In some environments, the subprocess module attempts to check whether environment variables correspond to filesystem paths, and this results in a TypeError due to this specific envvar not being a string.

• mrtrix3.utils.RunList
  Pass kwargs to run.command().

• Fix help page generation
  Handle upstream changes in ArgParse, whereby the name for the default option group has now been changed from ‘optional arguments’ to the (arguably more sensible) ‘options’.