Message Boards Message Boards

QMRITools: processing and visualization tools for quantitative MRI data

QMRITools DOI contributions welcome status


wolfram language wolfram workbench eclipse wolfram mathematica


eye candy

I have been working on this toolbox for years and recently started making the code available online which took considerable extra effort putting everything into the proper formats and generating documentation and usage demonstrations. I thought it would be nice to also show this to the wolfram community so here it is.

Contents

Summary

QMRITools is written in Mathematica using Wolfram Workbench and Eclipse and contains a collection of tools and functions for processing quantitative MRI data. The toolbox does not provide a GUI and its primary goal is to allow for fast and batch data processing, and facilitate development and prototyping of new functions. The core of the toolbox contains various functions for data manipulation and restructuring.

The toolbox was developed mostly in the context of quantitative muscle, nerve and cardiac magnetic resonance imaging. The library of functions grows along with the research it is used for and started as a toolbox to analyze DWI data of muscle. Although there exist many different software packages and code repositories for much of the functionality in this toolbox, I was in need of one that did all. Furthermore, most diffusion packages are optimized for brain analysis and provide limited flexibility and i just like writing code my self.

Information

QMRITools is developed for Mathematica. It contains the following toolboxes:

  • CardiacTools
  • CoilTools
  • DenoiseTools
  • DixonTools
  • ElastixTools
  • GeneralTools
  • GradientTools
  • ImportTools
  • IVIMTools
  • JcouplingTools
  • MaskingTools
  • NiftiTools
  • PhysiologyTools
  • PlottingTools
  • ProcessingTools
  • RelaxometryTools
  • SimulationTools
  • VisteTools

Documentation

The website with more information about the toolbox can be found here. Documentation of all functions and their options is fully integrated in the Mathematica documentation. The toolbox always works within the latest version of Mathematica and does not support any backward compatibility. After the toolbox is installed correctly it should show up as a package in the Mathematica add-ons (which was a pain and is badly documented).

QMRITools package

All code and documentation is maintained and uploaded to github using Workbench. An online HTML version of the full documentation can be found here. To fix the HMTL compilation i had to write some custom scripts based on code i found online (again a pain and badly documented).

Guides QMRITools

Install toolbox

The latest release can be found here.

Install the toolbox in the Mathematica UserBaseDirectory > Applications.

FileNameJoin[{$UserBaseDirectory, "Applications"}]

Ideally i would like to push the toolbox as a packlet but again this has proven to be a pain and is badly documented.

Some functions of QMRITools call on external executables and software. These executables need to be present in "QMRITools\Applications" and are included in the release. If for any reason you want to use other (older/newer) versions you can replace them but functionality is not guaranteed. For the latest version of these tools and their user license please visit their website.

All functionality is tested under Windows 10 with the latest Mathematica version. The Mathematica code is cross platform compatible with the exception of the external tools which are compiled for each OS. The toolbox provides compiled versions for each OS but their functionality is not guaranteed. The Elastix version used is 4.9 with OpenCL support. Additionally Elastix needs to be compiles with the PCA metrics, all DTI related parameters and all affine related parameters.

Although cross platform compatibility is provided I have only limited options for testing so if any issues arise please let me know.

Demonstrations

The release contains a zip file DemoAndTest.zip in which there is a file demo.nb, a folder DemoData and a folder Testing. To have a global overview of the functionality of the toolbox you can download this folder and run the demo.nb. By default the demo.nb looks for the folders DemoData and Testing in the same folder as the notebook.

QMRITools demonstration

In the first section of the demo notebook the toolbox is loaded and two tests are performed. The first test is to check of all files that are needed to run the toolbox are present. The second test runs after the toolbox is loaded and checks if all the functions and their options that are defined are correct.

enter image description here

Using the toolbox

The toolbox can be loaded by using: <<QMRITools` If you want to monitor the package loading you can use: QMRITools`$Verbose = True; <<QMRITools`

A list of all QMRITools packages is generated by

QMRIToolsPackages[]

A list of all DTITools functions or functions per toolbox is generated by

QMRIToolsFunctions[]
QMRIToolsFunctions["toolboxname"]

To print the documentation of all functions use

QMRIToolsFuncPrint[]
QMRIToolsFuncPrint["toolboxname"]

A list off all functions and their help can be found in All-Functions.nb, which is alos availible as a pdf file.

Functionality

The toolbox contains over 250 Functions and options of processing and analyzing data. A summary of the core functionality is listed below.

QMRITools overview

  • Diffusion Analysis
    • Signal drift correction
    • LLS, WLLS and iWLLS methods
    • REKINDLE outlier detection
    • IVIM fitting (fixed parameters, back-projection and Bayesian fitting)
    • Parameter fitting using histogram analysis
    • Joining and sorting of multiple series of the same volume
    • Joining multiple stacks with slice overlap into one stack
  • Diffusion Gradients optimization
    • Single and multi shell
    • Rotating and correcting Bmatrix
    • Actual b-value estimation by gradient sequence integration
    • Gradient visualization
  • Noise suppression
    • LMMSE noise suppression
    • PCA noise suppression based on ramom matrix theory
    • Anisotropic tensor smoothing using diffusion filter.
  • Importing and Exporting
    • Dicom data (classing and enhanced file format)
    • Nifti data (.nii and .img .hdr, supports .gz files)
    • Compatible with ExplorDTI and Viste for fiber tractography
  • Data visualization
    • 2D 3D and 4D viewer
    • Multiple images: Transparent overlay, difference and, checkboard overlays
    • Legend bars and image labels
    • Saving to pdf, jpg, animated gif and movie
      Plot 3D and 4D datasets
  • Masking
    • Automate and threshold masking
    • Extracting parameters form masks
    • Smoothing masks
    • Smoothing muscle segmentation
  • Motion and distortion correction (Registration using elastix)
    • Rigid, affine, b-spline and cyclic registration
    • nD to nD registration
    • Automated series processing
    • Slice to slice motion correction of 3D and 4D data
  • Dixon Reconstruction
    • B0 phase unwrapping
    • DIXON iDEAL reconstruction with T2start
  • Relaxometry fitting
    • T2 fitting
    • T1rho fitting
    • Tri Exponential T2 fitting
    • EPG based T2 fitting with slice profile
  • Simulation Framework
    • Diffuison tensor simulation and analysis
    • Bloch and EPG simulations
    • Cardiac DTI models (fiber architecture)
  • Cardiac Diffusion analysis
    • Breathing motion correction
    • Corrupted slice rejection
    • Local myocardial coordinate system calculation
    • helix angle and fiber architecture matrix
    • AHA 17 parameter description
    • Transmural parameter description

License

https://opensource.org/licenses/BSD-3-Clause

Note that restrictions imposed by these patents (and possibly others) exist independently of and may be in conflict with the freedoms granted in BSD-3-Clause license, which refers to copyright of the program, not patents for any methods that it implements. Both copyright and patent law must be obeyed to legally use and redistribute this program and it is not the purpose of this license to induce you to infringe any patents or other property right claims or to contest validity of any such claims. If you redistribute or use the program, then this license merely protects you from committing copyright infringement. It does not protect you from committing patent infringement. So, before you do anything with this program, make sure that you have permission to do so not merely in terms of copyright, but also in terms of patent law.

Some code in the NiiTools packages was based on https://github.com/tomdelahaije/nifti-converter

POSTED BY: Martijn Froeling
8 Replies

Wow! That's a very advanced package! thanks for sharing! What kind of algorithm do you use for Phase Unwrapping? I just added this function to the WFR: https://resources.wolframcloud.com/FunctionRepository/resources/PhaseUnwrap

Which is for 1D, but can also be used for 2D (see examples). Is there a better approach in 2D or 3D?

POSTED BY: Sander Huisman

The phase unwrapping i use works in 2D and 3D and is based on:
1. Abdul-Rahman HS, Gdeisat MA, Burton DR, Lalor MJ, Lilley F, Moore CJ: Fast and robust three-dimensional best path phase unwrapping algorithm. Appl Opt 2007; 46:6623. 2. Herráez MA, Burton DR, Lalor MJ, Gdeisat MA: Fast two-dimensional phase-unwrapping algorithm based on sorting by reliability following a noncontinuous path. Appl Opt 2002; 41:7437.

This method has worked nicely for me over the last few years.

I was working on a Fourier based method but was not happy with the results but in theory it should be much faster.

POSTED BY: Martijn Froeling

enter image description here -- you have earned Featured Contributor Badge enter image description here Your exceptional post has been selected for our editorial columns Staff Picks http://wolfr.am/StaffPicks and Publication Materials https://wolfr.am/PubMat and Your Profile is now distinguished by a Featured Contributor Badge and is displayed on the Featured Contributor Board. Thank you!

POSTED BY: Moderation Team

This seems to be absolutely awesome! I wish this (and an advanced version of MM) had been available fifteen years ago when I was still working in MRI! Many thanks for sharing - maybe I can play around a bit somewhen ...

POSTED BY: Henrik Schachner

Just another reminder to post your packages on http://packagedata.net/ :-)

At one time I used the Neurotica package a little bit, in particular for importing NifTI files. https://github.com/noahbenson/Neurotica There some overlap in functionality, so you may be interested in Neurotica.

POSTED BY: Szabolcs Horvát

I looked back at my very very old code, the first lines of code of the toolbox were written 12 years ago in Mathematica 6.0. The demos should give you some examples to play around with.

POSTED BY: Martijn Froeling
Posted 3 years ago

Congratulations on the excellent MRI Toolbox! Is there an option to process a standard mDixon sequence from a Philips 1.5 T scanner with the Ideal reconstruction?

Thanks,

Andre

POSTED BY: andre zulubal

In theory yes, I use data form a 3T Philips system in my research. You just need to export the complex data form the scanner which is needed for the iDEAL reconstruction.

Best Martijn

POSTED BY: Martijn Froeling
Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Reply Preview
Attachments
Remove
or Discard

Group Abstract Group Abstract