MRtrix 3.0_RC3 -> 3.0.0 changelog

1

Changelog: 3.0_RC3 -> 3.0.0

  1. Changes for priority attention

  2. Major software changes

  3. Bug fixes

  4. New or renamed commands

  5. All other changes

2 Likes
2

1. Changes for priority attention

dwidenoise

  • Noise level estimator: Fix denoising efficacy when the number of DWI volumes closely matches the number of volumes in the patch. (Thanks for reports @Kar, @uclpz, @Shawn_Yeh, @Forrest, @DorianP)

    • The noise level estimator as initially defined in MP-PCA is biased when the number of DWI volumes closely matches the number of voxels in the patch. Crucially, this bias manifested itself differently in cases M < N and M > N, M being the no. dMRI images and N being the patch size, leading to inconsistent results in some cases. This issue has been fixed in a new noise level estimator that reduces the bias and has symmetric behaviour across patch size. A detailed comparison is described in Cordero-Grande et al. (2019). This new estimator is now the default.

    • Users can revert to the legacy behaviour (not recommended) with the new command option -estimator. However, this will match the previous release candidate if and only if the patch size exceeds the number of DWI volumes in the dataset. The opposite case is handled symmetrically by using the matrix transpose.

dwifslpreproc (previously dwipreproc)

  • Brain mask: The brain mask generated within the script to constrain the optimisation within FSL eddy was erroneous if the input DWI was not in native RAS orientation. This is expected to not have been severely problematic in many cases, since it is only used to control which voxels contribute to the estimation of motion / eddy current distortion / outlier classification parameters, but users may wish to investigate the presence and magnitude of this issue in their own data. (Thanks for report @HelenaV)

fixelcfestats

  • Output parameter magnitudes: Specifically the beta coefficients, absolute effect size and standard deviation images were affected by a bug in the smoothing of subject fixel data; all other outputs (e.g. p-values, standardized effect size, t-values) were unaffected. In each fixel, the magnitudes of these values were erroneously scaled by some factor, where that factor was different for each fixel.

    The effect was self-cancelling for internally self-consistent calculations; e.g. the standardized effect size, which is the ratio of the absolute effect size and the standard deviation, was unaffected. Direct interpretation of e.g. beta coefficient magnitudes was however affected.

tckgen

  • SH precomputer: Fix quantification of FOD amplitudes specifically during FOD-based tractography, where pre-computed versions of complex mathematical functions are used to speed up execution. Effect was that FODs were interpreted as being 30-40% smaller than reality, and therefore comparable to the threshold being 30-40% larger than intended. Orientation dependency was minimal; i.e. the interpreted FOD shapes were not particularly affected.

  • Tracking parameter updates:

    • Changed default tracking angles for some algorithms, and made these angles independent of step size for all algorithms. Previously the maximum angle per step was calculated based on a minimal radius of curvature and the tracking step size; they are now instead hard-coded to a fixed value for each algorithm, and the value utilised will not change if the user manually sets only the step size.

    • Changed default step size to 1/4 voxel size when using 4th-order Runge-Kutta.

    • Changed default FOD amplitude cutoff for iFOD1 & iFOD2. In 3.0_RC3, these were changed from 0.10 to 0.05, due to a combination of fixing of an SH amplitude calculation bug and increased use of multi-tissue CSD. Based on the updated SH amplitude calculation fix and alterations to the recommended WM response function estimator, these have been reverted to 0.10. A lower value may however be preferable in some cases, particularly if using multi-tissue CSD; precise tuning of this parameter cannot currently be performed using automated heuristics and so is deferred to the user.

    • Default tracking cutoff threshold is halved for all algorithms if ACT is employed.

3

2. Major software changes

Documentation

  • MRtrix3 reference: Include reference to the MRtrix3 manuscript in all commands.

    Please cite this manuscript in all publications that have used any component of MRtrix3. The ongoing support and development of MRtrix3 is contingent upon evidence of its utilisation and impact in the field!

  • Wiki: Some MRtrix3-related documentation has been moved from the online software documentation into the “wiki” section of the community forum. This will enable more dynamic updates of documentation when recommendations change, and also permit user contributions.

Package management

Binary installers/packages are now available at https://www.mrtrix.org/download for multiple platforms:

Python scripts

  • API: Considerable changes to the MRtrix3 Python API. These will mostly be irrelevant for most users (-tempdir renamed to -scratch is the only interface change), but will affect anyone writing their own scripts to run against the API.

Registration

  • registration Added support for multi-contrast registration in mrregister and population_template. mrregister results will differ slightly from previous results due to changes to the midway-space calculation. This and changes to the population template grid and masking will also affect population_template results.

Statistical inference

  • CFE: fixelcfestats defaults to an intrinsically normalised version of the CFE equation, which provides an effect comparable to non-stationarity correction but without computational penalty. The former behaviour can be accessed using the -cfe_legacy option.

  • F-tests: Ability to perform F-tests (-ftests option).

  • FBA: Calculations previously performed internally within fixelcfestats are now spread across multiple commands. See new commands fixelconnectivity and fixelfilter.

  • Fixel matrix format: A new format for storing the sparse fixel-fixel connectivity matrix on the fileysstem has been produced. This is generated by new command fixelconnectivity, and utilised as input by new command fixelfilter as well as fixelcfestats. Interested developers can use this format for direct, easy-to-read access to these data for their own projects.

  • Heteroscedasticity: Ability to define variance groups (-variance option). Also fun to say. :upside_down_face:

  • Limited shuffles: Better handling of use cases where the maximal number of possible shuffles is small.

  • Model errors: Model errors can be treated as exchangeable (randomly permuted), independent & symmetric (randomly negated), or both (-errors option).

  • Multiple hypotheses: Multiple hypotheses can be tested in a single command invocation (and not just the “inverse contrast”). Achieved by providing a contrast matrix rather than a vector. Note that this also means that the -negative command-line option is no longer present; equivalent functionality is achieved by providing a contrast matrix with two rows, where the values in the second row are negated relative to the first.

  • Per-element design matrices: Design matrix can vary between individual elements (e.g. fixels) tested; due to regressors (of interest or of no interest) where the value is unique for each fixel / voxel / connectome edge tested (-column option), and/or data exclusion on a per-element basis (non-finite input data values). Useful for dealing with inconsistent brain cropping due to incomplete coverage or subject motion (documentation page).

  • Restricted exchangeability: Ability to define (non-hierarchical) restricted exchangeability (-exchange_within and -exchange_whole options).

  • Z-statistic: Statistical enhancement algorithms are applied to the corresponding Z-statistics for each hypothesis. This makes empirical statistical enhancement behaviour more consistent across studies of different sizes, between t-tests and F-tests, and reduces non-stationarity when excluding data on a per-element basis.

dwi2response dhollander

dwidenoise

  • Complex data: Command can now operate natively on complex data. This facilitates denoising datasets that contain both magnitude and phase images, provided the latter have also been exported. A key advantage of denoising in the complex domain is that it offers a means to reduce Rician bias.
population_template

  • leave-one-out-registration: registers each image to the current template that was created without this image in the intensity aggregation.

  • robust initialisation: allows more robust template initialisation of images with extreme intensity values.

  • aggregation: Added options for intensity value aggregation across images in population_template. It now supports mean, median, and weighted average aggregation.

  • NaN-masking: The template does not contain contributions from areas outside the original field-of-view of input images. Previously these counted as zero in the averaging, biasing the template towards zero if input images were cropped. Added a NaN-masking option to also exclude areas outside the masks from contributing to the template intensity.

4

3. Bug fixes

(Note: If checking out the master branch – which is the default behaviour – rather than the explicit 3.0_RC3 tag, you may have received many of these fixes already)

DICOM

  • Null characters: Fix import of DICOM fields with dangling null characters. (Thanks for report @sniogi)

  • Slice timing (2, 3): Fix import of slice timing vector, particularly in Siemens mosaics. (Thanks for report @mblesac)

  • Whitespace data: Strip excess whitespace from DICOM fields prior to numerical conversion to prevent import failures.

  • Whitespace keys: Prevent read_mrtrix() from failing when a header key contains whitespace; as Matlab variable names cannot contain such.

Documentation

  • FBA pipeline (2 3): Fixes to FBA pipelines following 3.0_RC3 update.

Matlab

  • write_mrtrix(): Fix function operation when output is a .mih / .dat file pair rather than a .mif.

Multiple commands

  • Affine transformations: Fix image header information load when header transformation is not rigid (scaling component will be applied to voxel sizes so that transform contains unit-length cosine vectors).

  • b-value clustering: Extract volumes classified as b=0 before running clustering algorithm to prevent low non-b=0 shells being merged with b=0 volumes. (Thanks for report @MikaelNoven)

  • Command-line interface: Fix parsing of abbreviated command-line options when there are identically-named options.

  • JSON orientations: Import and export of orientation-dependent information (e.g. phase / slice encoding directions) has been modified and extensively tested under various scenarios (e.g. different file formats, with / without MRtrix3 internal RAS realignment).

  • Multi-file numbered images: Multiple fixes to cases where more than one image axis is concatenated / split using the square-bracket notation.

  • Progress bars in binaries (2): Restrict construction of progress bars to the main thread. This should prevent various race conditions when performing multi-threaded operations; particularly operations in mrview that take sufficient time for a progress bar to appear.

  • Terminal warnings: Prevent erroneous command-line usage warnings due to presence of piped images.

  • Track files: Prevent erroneous duplication of ROI entries within track file headers.

Package management

Python scripts

  • FSL: Change FSL command detection. Previously, the MRtrix3 Python API was erroneously giving precedence to executables present in PATH beginning with “fsl-5.0-”, which should in fact ideally not be in PATH, and in some instances do not execute correctly; this change ensures that executables corresponding to a properly-installed FSL are instead given precedence.

  • Header key-values: Handle import of image headers when key-value entries in the header contain exotic characters. (Thanks for report @lrq3000)

  • Number of threads: Ensure that if -nthreads 0 is specified, this is appropriately propagated to any underlying MRtrix3 commands executed. (Thanks for report @kjamison & @ThijsDhollander)

  • Progress bars: Fix glitch in progress bar completion messages. (Thanks for report @gfreches)

configure

connectome2tck

  • Non-valid exemplars: Fix to -exemplars output for label images with absent parcels. (Thanks for report @JeroenBlommaert)

  • Non-visited nodes: Fix potential memory bug when one or more nodes within the parcellation image did not have any streamlines assigned to them, and therefore did not appear in the input assignments file (bug only triggered if it was those nodes with the greatest index value that were not visited). (Thanks for report @SyamGadde)

connectomestats

  • Standard deviations: Fix output of per-edge standard deviations (only the standard deviation of edge (1,2) was being written).

dcminfo

dirflip

  • Interface: Fix parsing of -permutations command-line option.

dirmerge

dirsplit

  • Interface: Fix parsing of -permutations command-line option.

dwi2mask

  • Cleaning filter: Fix operation of mask cleaning filter specifically for data where voxels are filled with NaN values.

  • -fslgrad: Fix command failure when using this specific command-line option.

dwi2response

  • Gradient table: Fix for when no gradient table is present in the input image header, and -mask option is not used.

dwiextract

  • Phase encoding: Fix to selection of DWI volumes based on phase encoding information where there are volumes with the same phase encoding direction but different readout times. (Thanks for report @treanus)

dwifslpreproc

  • FSL6 topup: Provide compatibility with FSL6.0.0 when performing explicit volume recombination due to erroneous topup output (subsequently fixed in 6.0.1). (Thanks for report @Ingomar_Gutmann)

  • -eddyqc_all: Fix operation of this option for FSL version 6.0.0. (Thanks for report @araikes)

  • -se_epi: Fixes case where SE-EPI volumes are defined on a different image grid to the DWIs, and do not internally possess any phase-encoding contrast. (Thanks for report @araikes)

dwigradcheck

fixel2voxel

  • Output dimensionality: Fix voxel-wise metric outputs erroneously being 4D images with 2 volumes rather than 3D images.

fixelcfestats

  • Erroneous warnings: Remove erroneous warning about voxels sizes and transforms when -mask option is not used.

label2mesh

  • Absent parcels: Properly ignore index values that are less than the maximum in the image, but for which no voxels are present. (Thanks for report @paul-triebkorn)

labelconvert

  • HCPMMP1 files: Fix some label names in HCPMMP1 parcellation lookup table files (the two files provided were previously self-consistent with one another, but inconsistent with the source parcellation data). (Thanks for report @paul-triebkorn)

mrcat

  • Single-voxel image: Fix segmentation fault in the rare instance where the input images consist of one voxel each.

mrclusterstats

  • Mask: Make sure template mask is 3D (command would hang if mask was erroneously 4D).

mrconvert

  • -axes: Fix interpretation of negative axis indices in the specification of the new axes, which is required to insert additional axes (e.g. going from dimensions [ X Y Z 3 ] to [ X Y Z 1 3 ]).

  • -json_export: Fix to the export of phase encoding information when the output image was in NIfTI format, and the output image was not natively axially aligned.

mrdegibbs

  • -axes: Validate user input to this command-line option.

mrmetric

mrpad

  • Header transform: Fix bug in generation of output image transform in cases where padding in 2nd or 3rd axis did not match that of the 1st.

mrtransform

  • Erroneous warning: Fix erroneous warning message in cases where no linear transform is specified. (Thanks for report @roeysc)

mrview

population_template

  • -continue: Fix error when using -continue option due to attempting to delete a non-existent file. (Thanks for report @anege)

tckdfc

  • -static: Fix absence of output image data when this command-line option was used.

tckedit

  • -inverse and -mask: Fix operation of command specifically when these two options are used in conjunction: Only streamline vertices outside the mask will be written to the output file.

tckgen

  • Downsampler: Fix crashes in rare cases, due to attempting to downsample a track that contains a single vertex. This was likely only applicable when utilised within the dwigradcheck command: streamlines tractography typically incorporates a non-zero minimum length criterion, but such is explicitly disabled in that particular script.

  • Windows crash: Remove source of command sporadically crashing when running on Windows.

tcksift

  • Sorting: Fix to sorting algorithm for tractograms with very few streamlines.

tckstats

  • -explicit: Ensure that all inter-vertex distances are indeed explicitly calculated, in order to properly handle nonlinearly-transformed streamlines. (Thanks for report @cbajada)

transformcalc

warpcorrect

  • NaN handling: Small fix when using NaN as the out-of-bounds marker.
5

4. New or renamed commands

5ttgen hsvs

New algorithm for generating a 5TT image for ACT. Takes as input a FreeSurfer output, but unlike 5ttgen freesurfer, utilises the surface-based cortical estimates rather than only the aseg image. Cleaner 5TT images than 5ttgen fsl, but not guaranteed to work in all scenarios. Feedback welcome. (Thanks for collaboration @Antonin_Skoch and @cbajada)

connectomeedit

Performs basic operations on connectome matrix numerical data.

dwicat

In addition to concatenating multiple DWI series (which could otherwise be done using mrcat), also accounts for unwanted variations in image intensities across series, by estimating the multiplicative factors required to make the b=0 images in each series of comparable intensity. Intended for platforms whereby multi-shell acquisition is only possible by running multiple protocols, and thus there may re-calibration in any stage of the acquisition & reconstruction process.

dwifslpreproc

dwipreproc has been renamed to dwifslpreproc. This provides greater attribution for the FSL commands principally responsible for performing the image pre-processing, and will reduce likelihood of naming conflicts with future MRtrix3 additions.

dwinormalise

The result of refactoring:

  • dwinormalise is now a Python script rather than a C++ compiled binary.
  • dwinormalise individual duplicates the functionality of former binary dwinormalise.
  • dwinormalise group duplicates the functionality of former Python script dwiintensitynorm.

fixelconnectivity

Generate a fixel-fixel connectivity matrix and write to filesystem. Fixel-fixel connectivity matrix generation is ~ 4-5 times faster and requires ~ 4-5 times less RAM than it did in previous software versions where this step was performed within the fixelcfestats command. This is an essential step for the FBA pipeline. Matrix data are written to the filesystem using a new format.

fixelfilter

Perform filtering operations on fixel data. This includes smoothing, and a preliminary connected-component algorithm. Can operate on individual fixel data files, or all data files within a fixel format directory. Duplicates functionality that previously occurred within the fixelcfestats command (and is therefore a crucial component of the FBA pipeline).

for_each

Renamed from foreach due to the latter being a reserved keyword in zsh, which will be usurping bash as the default on MacOS.

labelstats

Provides statistics on label images (i.e. parcellations): centres of mass and voxel counts.

mrcentroid

Outputs the centre of mass / centre of gravity of an image.

mrcolour

Applies a colour map to an image; particularly useful in conjunction with the PNG image format for exporting quantitative image data to images at their native resolution with stringent intensity / colour mapping control.

mrgrid

mrgrid is a replacement to mrcrop, mrpad and mrresize.

mrtrix_cleanup

Searches for and deletes MRtrix3 piped images and Python script scratch directories.

responsemean

Replacement for former bash script average_response. Default mechanism for response function averaging is slightly different to that of average_response, but in most cases results should be almost identical.

6

5. All other changes

DICOM

  • Caret characters: Show caret characters ("^") in DICOM fields rather than substituting them for spaces.

  • Empty fields: Increase resilience to errors when reading slightly malformed DICOM files with fields present but left empty.

  • New fields: When possible, fields related to inversion time, partial Fourier, monopolar / bipolar diffusion sensitisation, multiple RF flip angles, and pixel bandwidth will be imported.

  • Series selection: Add capability to select specific series from an input DICOM directory using environment variables.

  • Slice timing: Use appropriate precision for slice timing data when importing Siemens mosaic data.

  • Terminal output: Don’t flood the terminal with warning messages when certain DICOM header fields cannot be converted to the intended type.

  • Variable scaling: Handle data with inconsistent offset/scale; required to read some Philips multiframe data produced on R5.4. (Thanks for report @ameoded1)

  • Volume-varying parameters: Correctly import echo time, flip angle & repetition time in cases where these vary across volumes.

Documentation

Matlab

  • TSF: Provide functions to read and write .tsf files.

  • write_mrtrix(): Increase number of significant figures with which floating-point header information (e.g. voxel sizes, transform, diffusion gradient scheme) are written to mitigate unwanted image differences due to loss of precision.

Multiple commands

  • BValueEpsilon: New configuration file entry for altering the difference between b-values necessary for the corresponding DWI volumes to be classified as belonging to different shells. The default value has additionally been reduced from 100 to 80. (Thanks for report @aminm9822)

  • Command history breadth: The command_history field that is written into the headers of output images, containing the command string used to generate that image and the compiled version of the MRtrix3 software of that command, is now written to other command outputs, such as track files and numerical matrix data in text files. (Thanks for report & testing @matteofrigo)

    NOTE: Any external scripts that parse text files generated by MRtrix3 may need to be revised in order to correctly identify and ignore lines within those files that contain comment text.

  • Command history readability: When updating the command_history field in output headers, don’t surround command-line arguments with quotation marks unless necessary (improves readability).

  • Config file override: New command-line option -config, which enables modifying any MRtrix config file entry just for that particular command invocation.

  • Diffusion scheme handling (2): Alter handling of diffusion gradient tables, with the intent of resolving issues regarding b-value scaling at the point of initial conversion rather than throughout the processing pipeline; changes should only be applicable to those whose DICOM data provide correct b-values but with non-unit-norm vector directions:

    • Option -bvalue_scaling is only available in commands mrconvert and mrinfo;

    • If gradient vector directions differ substantially from unit norm, normalise vectors, perform b-value scaling if appropriate (unless overridden by the -bvalue_scaling option), and update the header so that any output images have the updated gradient table and these operations should not be necessary for any subsequent commands;

    • By default, don’t apply b-value scaling if the vectors only differ marginally from unit norm;

    • The raw diffusion gradient table data, without any MRtrix3 processing, can be accessed using " mrinfo -property dw_scheme ".

  • Input data overwrite: Allow binary command outputs to overwrite command inputs safely. Does not work on Windows. If input is a symlink or hard link, the output will not be the same; it will be written as a new file in the specified location.

  • JSON data types: Preservation of data types of header key-value entries. This should improve compatibility with other softwares interacting with MRtrix3 via JSON data.

  • Matrix delimiters. Output numerical data will use delimiter based on the extension of the output file: “,” delimiter for .csv files, tab for .tsv files, and " " for all other file extensions.

  • Multi-file numbered images (2): Improved handling of 4D schemes within image headers when using multi-file numbered images.

  • Multi-threading: Prevent deep multi-threading (i.e. if a command is intended to run with 8 threads, each thread should not be permitted to itself launch 8 threads to complete a multi-threaded task).

  • PNG support: Native support of PNG images as an image format. Stacks of 2D PNG images can be interpreted as a 3D volume using multi-file numbered images.

  • Progress Bars (2): Disable line wrapping while updating terminal; this means the terminal doesn’t get clogged up with the same line repeated over and over again when the progressbar line width exceeds the terminal’s width.

  • Signal handlers: Allows system signal handlers to be disabled with environment variable MRTRIX_NOSIGNALS.

  • Streamlines lengths: More precise quantification of streamlines lengths throughout software. Unless it is absolutely guaranteed that the distance between each vertex is fixed & known, length is calculated as the sum of inter-vertex distances. This alters behaviour related to streamlines lengths in various locations in the software; e.g.:

    • If using tckgen -act -crop_at_gmwmi, streamline must exceed minimum length after cropping.

    • If using downsampling in tckgen, streamline must satisfy both minimum & maximum length restrictions after downsampling.

  • Temporary file location: New environment variable MRTRIX_TMPFILE_DIR, which has precedence over the MRtrix config file in setting the location of the temporary directory used for piped images. If this is not set, environment variable TMPDIR will also be tested and used if set. (Thanks for report @ikirker)

  • Tractography commands: Commands that take as primary input streamlines data (tckedit, tckresample, tcksample, tcktransform) will preserve the order of their outputs relative to the input streamlines even if running multi-threaded.

  • mrmath / mrstats: More precise variance calculation, using Welford’s online algorithm to fix catastrophic cancellation.

  • tckgen / tckedit high-resolution ROIs: Issue a warning if there is a risk of streamlines “jumping over” a specified ROI because of image voxels / the spherical ROI being very small compared to the streamline step size. (Thanks for report @Lucius & @chamberm)

  • tckgen / tckedit ordered include regions: Provide inclusion ROIs to tckedit and tckgen that must be intersected by a streamline in the specified order.

Package management

  • Catalina: Support setting the path on a default Catalina install via set_path.

  • Compile times: Adds -timings command-line option to build script to print out the build time for each job.

  • Compiler warnings: Various changes to build and configure to prevent compiler warnings arising from non-MRtrix3 dependencies.

  • Conda: Add -conda flag to configure.

  • Miniconda: Remove miniconda from PATH in configure.

  • Outdated binaries: build will move outdated binaries to another directory. This is specifically for those who check out different software versions, to prevent the execution of commands that are not even present in the currently accessed version of the software.

  • Pylint: Perform automated lint testing of build and configure (using the same requirements as those imposed on the MRtrix3 Python scripts and API) to reduce likelihood of obscure bugs or future regressions.

  • Static linking: Update configure flags for static linking.

  • Terminal output: All terminal outputs from build are written to stderr; this prevents buffering of compilation progress information in some environments e.g. containers.

  • Versioning: Enable capture of software version even when software is not compiled from source.

  • set_path external projects: The set_path script can now be used to automatically add the path to executable binaries of external projects built against MRtrix3 to PATH.

  • set_path -remove: New command-line option to erase prior additions to shell configuration files by this script.

PAR/REC files

  • Rudimentary support: Added basic support for this data format. Please treat this capability as experimental, and report any issues encountered to the MRtrix3 developers.

Python scripts

  • Command history: Header key-value field “command_history” will be updated only based on the invocation of that script, rather than being bloated by contents from all of the underlying MRtrix3 commands that were executed within that script.

  • Error message: More explicit error message in cases where an underlying command does not complete successfully, and this was not necessarily the fault of the script, but the underlying command failed to provide any text information that could otherwise have been forwarded to the user.

  • Help pages: Make help pages for MRtrix3 Python scripts match the formatting of MRtrix3 C++ binary commands as closely as possible.

  • Library import: Simplification of importing of MRtrix3 libraries, both for executable scripts provided in MRtrix3 and for external projects utilising the MRtrix3 Python API.

  • matrix module: New module for handling load / save of numeric data from / to file.

  • Piped images: Python scripts will exploit new environment variable MRTRIX_TMPFILE_DIR to instruct any invoked MRtrix3 commands to place piped images within the script’s scratch directory. (Thanks for report @cbajada)

  • Python interpreter: If a script executes a command that is itself written in Python, the latter is now guaranteed to be executed using the same version of Python as the former.

  • Signal handling: Improved system signal handling across OS’s, particularly for when the user terminates a script using Ctrl-C.

  • Testing: New testing suite for MRtrix3 Python scripts. These are not run as part of Continuous Integration, but are intended to more quickly identify regressions in MRtrix3 code and/or incompatibilities introduced by changes to external software dependencies.

.img / .hdr images

  • Analyse compatibility: Writing .img output images will now produce fully NIfTI-compatible split-file format, rather than conforming to Analyze format. Using -strides -1,+2,+3 for image output should still result in an Analyze-compatible image. Config file option “AnalyseLeftToRight” only applies to image read when the input is detected as being specifically Analyze data rather than a split-file NIfTI; note also that this config file option was previously not working.

5ttcheck

  • Raw values: Make sure that individual partial volume fractions lie in the range [0.0, 1.0].

amp2response

  • Execution times (2): Modified implementation and added multi-threading to drastically reduce execution times.

  • Invalid transform: Raise an error when the transformation from DWI signal amplitudes to spherical harmonic coefficients cannot be constructed (typically due to erroneous use of -lmax option).

amp2sh

connectomestats

  • Output files: Alter output file names to be more consistent with other MRtrix3 statistical inference commands.

  • TFNBS: Statistical enhancement algorithm formerly referred to as nbse is now labelled tfnbs, commensurate with the name used in an independently-published journal article.

dcminfo

  • -phoenix: New option that enables printing the contents of the large Siemens CSA Phoenix protocol data. If -csa is used and -phoenix is not, these data will be omitted from the output.

dirorder

  • Exhaustive search: More exhaustive search for optimal ordering. Rather than selecting the first DWI volume at random and then placing the remaining DWIs in the appropriate order, re-run the optimisation routine for every possible selection of the first DWI volume, and select the outcome that provides the best direct distributions upon truncation across all possible truncation lengths.

dwi2fod msmt_csd

  • -predicted_signal: New command-line option to write the DWI signal predicted from the estimated ODF(s) to an image.

dwi2response

dwi2response dhollander

  • -wm_algo: New command-line option to utilise an alternative dwi2response algorithm for selecting exemplar single-fibre WM voxels.

dwi2tensor

  • Optimisation algorithm: Add finer control over how the tensor fit is performed:

    • Initial fit either ordinary least squares (the previous behaviour), or weighted by the empirical DWI signal (the new default);

    • Number of iterations, where the measurements are weighted by the signal predictions from the previous step (no chnge to default behaviour).

dwidenoise

  • Image edges: Command now applies denoising to voxels at the outer edges of the image FoV.

  • Patch size: Appropriate selection of default patch size for denoising based on the number of DWI volumes in the input data.

dwifslpreproc

  • CUDA documentation: Additional documentation on the use of the CUDA version of FSL eddy. (Thanks for report @MrRibbits)

  • EddyQC: If either -eddyqc_text or -eddyqc_all are specified, and the new EddyQC software is installed, this will be executed within dwifslpreproc and the resulting files copied to the specified output location in addition to the eddy outputs previously exported via these command-line options.

  • FSL documentation: Improve documentation regarding the propagation of user-requested command-line options to FSL topup and eddy.

  • MacOSX: Better search for the CPU-based version of FSL command eddy on MacOSX. (Thanks for report @tali)

  • -eddy_mask: New command-line option allowing user to manually specify the processing mask for eddy to use rather than relying on dwifslpreproc generating one automatically using dwi2mask.

  • Rigid-body rotation Better support in dwipreproc for a very specific type of image acquisition protocol. The only change is to prevent an unnecessary image re-gridding of the SE-EPI data onto the DWI voxel grid in the case where the image dimensions are identical but the transformation is different. (Thanks for report @araikes)

  • Slice timing:

    • -eddy_slspec: New command-line option for providing FSL eddy “slspec” file explicitly, rather than relying on slice timing information stored in the image header. Note that including “--slspec=...” in the contents of “-eddy_options” is no longer supported.

    • slspec contents: Intelligently handle case where user attempts to use eddy's slice-to-volume motion correction, but manually provides slice timing data rather than the “slspec” format expected by eddy.

    • Parsing: Read input slice timing information in a robust fashion, even if technically malformed (e.g. generated using an older version of MRtrix3).

  • Volume recombination: When identifyping pairs of input DWI volumes with reversed phase encoding for explicit volume recombination, rather than a hard b-value difference threshold, use b-value clustering algorithm to classify volumes as belonging to the same shell. (Thanks for report @Timothee_Jacquesson & @Soichi_Hayashi)

foreach

  • Interface: Terminal output reduced substantially: instead of printing all outputs from all executing commands (even if in parallel), script will instead report how many of the commands to be executed have completed; and if any of the commands executed failed, it will print the terminal outputs of only those invocations.

  • -exclude: New command-line option whereby one can specify a regular expression (or simple search term) by which specific inputs to the script (e.g. that get included due to using an all-encompassing wildcard character) can be excluded from the list of items to process.

  • -test: New command-line option for user to test whether or not the string substitutions will operate as intended prior to executing commands.

mesh2voxel

  • Execution speed: Multi-threaded the bottleneck part of the underlying algorithm.

  • Robustness: Various improvements to the internals of mesh2voxel that were necessary to get the algorithm to yield accurate results when applied to more complex surface shapes.

mrcalc

  • Command-line interface: Improved parsing of input arguments. Interpretation of input complex numbers is improved. Erroneous image paths that commence with a number character will no longer be inappropriately interpreted as numerical values. (Thanks for report @PatronBernard)

  • Complex data: Added -polar and -proj options for working with complex data. The former is particularly useful for constructing native complex data from the magnitude & phase data output by Siemens scanners (note however that phase data must be scaled to radians before using this command).

  • Documentation: More intuitive grouping of available operations in help page.

  • Irrational constants: Mathematical constants pi and e can be provided directly as command-line inputs.

mrcat

  • Slice timing: Add tolerance for minor differences in slice timing vectors when concatenating series (which can be introduced due to phase encoding reversal).

mrconvert

  • JSON import: Preserve existing key-values already present in the image header when using -json_import. This is particularly necessary for correct operation when used in conjunction with -fslgrad.

  • -vox: Providing a single floating-point value to the -vox option will now change the voxel size along all three spatial axes, not just the first axis.

mrgrid

mrhistmatch

mrinfo

  • -imagepath: New option that prints the filename as the first output (to assist in attributing image properties to specific images when providing multiple images to mrinfo in a single invocation).

  • -shell_indices: New option that prints, for each b-value shell, the indices of the volumes that are attributed to that shell.

mrmath

mrstats

  • -output std_rv: For complex input data, compute the real-valued variance (square root of sum of variances of real and imaginary components).

mrthreshold

  • Re-write: Entire command has been re-written essentially from scratch:

    • -bottompercent and -toppercent are removed since -percentile covers that functionality;

    • New option -allvolumes that controls, for a 4D input image, whether a threshold will be calculated individually for each volume, or a single threshold will be calculated based on data from all volumes;

    • If selecting some number of voxels becomes degenerate due to duplicate intensities in the input image, report a warning (previously some of such voxels would be selected based on the image strides);

    • If no output image is specified, the value of the determined threshold will be written to the terminal;

    • Command-line option -comparison determines how image intensities are compared to the threshold value to determine the output mask; while this supersedes former option -invert, the latter is retained for backward compatibility.

mrtransform

  • Gradient export: Added command-line options to export the DWI gradient table of the output image. (Thanks for report @broseisaacs)

  • Jacobian modulation: Added option for modulation by the determinant of the Jacobian of the warp or by the determinant of the linear transformation.

  • Spherical Harmonics data: Makes specification of FOD reorientation a mandatory option if the number of volumes indicates that it may be an SH image with lmax >= 2.

mrview

  • Connectome tool: Rename “transparency” to “opacity” to more accurately reflect how parameter affects display.

  • Dark mode: Modifications to make the text in certain UI elements visible when the operating system is in dark mode.

  • File names: Better filename elision in List Views (better shows the differences between file names when horizontal screen space is limited). (Thanks for report @Antonin_Skoch)

  • Fixel plot: Various enhancements:

    • option to display fixel/vectors as unidirectional
    • add support for vector overlay 5th dimension to track main image 4th dimension (useful for angio cine applications)
    • add wrap volume functionality to cycle through volumes (useful for cine applications)
    • wider range of min/max values

  • Focus point: Values of images at focus point will report whether or not interpolation was used in deriving that value (which itself is determined based on whether or not interpolation is being used in displaying the image).

  • Image order: Insert newly opened images after the currently-viewed image, rather than at the end of the list of all open images.

  • MacOSX: Add support for opening images by dragging onto the dash, and by double-clicking in the Finder.

  • Ortho view: Ability to display the three images in a horizontal row rather than a 2x2 matrix.

  • Overlay tool: Overlay tool supports N-dimensional data.

  • ROI editor: Default transparency is 0.5 rather than 1; new config file option “MRViewRoiAlpha” enables control of such.

  • Synchronisation: Add capability to synchronize the focus point location across multiple instances of mrview.

  • Texture sizes: Report both 2D and 3D texture sizes.

  • View tool: Modified output of “Copy” functionality to match the formatting of plain text matrices generated by non-GUI commands.

mtnormalise

  • Internal changes (2):

    • Reduced execution times, particularly for high-resolution datasets.

    • Slight change to selection of outlier voxels during iterative optimisation.

    Thank you for contributions from @JRosnarho.

  • -balanced: New option for output images to incorporate tissue balancing factors (NB. Not to be used for standard AFD workflow).

  • -check_factors: New option to write estimated tissue balance factors to text file.

population_template

  • Dimension mismatch: Use new functionality mrmath -keep_unary_axes to avoid dimension mismatch between template and input data.

  • Terminal feedback: More concise terminal reporting of commands being executed. When a command is executed that takes as input files from all subjects, the command string that is reported to the terminal will be drastically condensed.

responsemean

  • Averaging algorithm: By default, instead of performing a direct average of the zonal spherical harmonic coefficients, the shape and size of the response functions are averaged separately to produce the output response function; this prevents subjects with DWI signal intensities arbitrarily larger in magnitude than other subjects from dominating the shape of the response function. The behaviour of former script average_response (i.e. direct averaging of coefficients) can be accessed by using the -legacy option.

tck2connectome

tckgen

  • Downsampling: Permit using “-downsample 1”, which is necessary to fully disable downsampling of track outputs for iFOD2.

tcksift2

  • -linear: New command-line option. Not recommended for use; its purpose is for presentation of conceptual ideas that will be demonstrated and contextualised in a later publication (@jdtournier: :smirk:).

tckstats

  • “Tracks”: Differentiate between empty streamlines (0 vertices) and zero-length streamlines (1 vertex).

transformcalc

vectorstats

  • General utility: This command is now actually in a mature state. It may be useful for verifying the setup of more complex GLMs, since test data can be fabricated easily and it omits the complexity of statistical enhancement.

warpcorrect

  • -marker: New command-line option to specify input value(s) to be considered out-of-bounds: either a floating-point value or a 3D vector.

  • -tolerance: New command-line option to specify how close the input data must be to the out-of-bounds marker to be considered out-of-bounds.

3 Likes