MRtrix 3.0_RC3 -> 3.0.0 changelog

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