- Introduction
- Installation
- Demonstrations
- Documentation
- Using the toolbox
- Functionality
- Toolboxes
- License
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 (Froeling et al. 2012), 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. Since then it has grown to include many other features such as cardiac analysis (tagging and T1 mapping), dixon reconstruction, EPG modeling and fitting, j-coupling simulations and more. It currently contains over 350 custom functions (over 20.000 lines of code) complete with documentation and demonstrations.
The toolbox is developed for the Wolfram language and maintained using Wolfram workbench for eclipse and runs in the latest version of Wolfram Mathematica.
When using the toolbox please cite one of the following references:
- Froeling M: QMRTools: a Mathematica toolbox for quantitative MRI analysis. J Open Source Softw 2019; 4:1204. link
- Froeling M, et al.: Reproducibility of diffusion tensor imaging in human forearm muscles at 3.0 T in a clinical setting. Magn Reson Med 2010; 64:1182-1190. link
- Froeling M, et al.: Diffusion-tensor MRI reveals the complex muscle architecture of the human forearm. J Magn Reson Imaging 2012; 36:237-248. link
- Schlaffke et al.: Multi‐center evaluation of stability and reproducibility of quantitative MRI measures in healthy calf muscles; NMR Biomed. 2019;32:e4119 link
The latest release can be found here.
Manual installation:
- Download the
QMRITools.zip. - Extract the
QMRIToolsfolder and place it in the Mathematica UserBaseDirectory > Applications.
FileNameJoin[{$UserBaseDirectory, "Applications"}]
Automatic installation:
- Download the
QMRITools-2.3.3.paclet. - Install the packlet using
PacletInstall.
PackletInstall["xxx\\QMRITools-2.3.3.paclet"]
Some functions of QMRITools call on external executables and software. These executables need to be present in “QMRITools” 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.
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.
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.
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.
All code and documentation is maintained and uploaded to github using Workbench. An online version of the full documentation can be found here.
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.
QMRITools contains the following toolboxes:
- CardiacTools
- CoilTools
- DenoiseTools
- DixonTools
- ElastixTools
- GeneralTools
- GradientTools
- ImportTools
- IVIMTools
- JcouplingTools
- MaskingTools
- NiftiTools
- PhysiologyTools
- PlottingTools
- ProcessingTools
- ReconstructionTools
- RelaxometryTools
- SimulationTools
- SpectroTools
- VisteTools
Under development
- TaggingTools
The toolbox contains over 350 Functions and options of processing and analyzing data. A summary of the core functionality is listed below.
- 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 random 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
- Masking
- Automate and threshold masking
- Extracting parameters form masks
- Smoothing masks
- Smoothing muscle segmentation
- Dixon Reconstruction
- B0 phase unwrapping
- DIXON iDEAL reconstruction with T2star
- Relaxometry fitting
- T2 fitting
- T1rho fitting
- Tri Exponential T2 fitting
- EPG based T2 fitting with slice profile
- Reconstruction Tools
- Basic algorithms for complex coil combination including RSS, Roemer, WSVD.
- Simple Image reconstruction (MS-2D and 3D reconstruction)
- CSI data reconstruction
- reading Philips *.list and *.data files.
- Hamming filtering.
- 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
- Simulation Framework
- Diffuison tensor simulation and analysis
- Bloch and EPG simulations
- Cardiac DTI models (fiber architecture)
- Spectra processing and fitting
- Fitting spectra using a set of basis functions.
- Phase correction and line-width optimization.
- Basic plotting and visualization.
- Automatic 0th and 1st order phase correction using Henkel matrix SVD.
- baseline correction
- CSI data visualization.
- 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
Under Construction
- Tagging analysis
- Getting displacement fields from tagging data (grid and line tagging)
- Strain, trosion and rotation from cardiac data
A collection of tools to analyze cardiac data. The main features are
cardiac shape analysis which allows defining the hard in a local
myocardial coordinate system which allows quantifying and analyzing
data. When the cardiac geometry is known there are functions to analyze
qMRI parameters in the AH17 model (Cerqueira et al. 2002) or perform
transmural sampling of qMRI parameters. Most of the functionality is
demonstrated in the demo.nb.
A collection of tools to evaluate complex multi-coil data. The functions
are specific for analysis of multi-coil magnitude and noise data which
allows quantifying per channel SNR. Furthermore, if complex coil
sensitivity maps are available it allows performing SENSE g-factor maps
simulations.
This toolbox is not demonstrated in the demo.nb.
The toobox provides two algorithms that allow denoising of DWI data. The
first is based on and LMMSE framework (Aja-Fernandez et al. 2008) and
the second is based on a random matrix theory and Principal component
analysis framework (Veraart, Fieremans, and Novikov 2016; Veraart et al.
2016). Furthermore, it provides an anisotropic filter for denoising the
estimated diffusion tensor which provides more reliable fiber
orientation analysis (Lee, Chung, and Alexander 2006). Most of the
functionality is demonstrated in the demo.nb.
An IDEAL based Dixon reconstruction algorithm (Reeder et al. 2005; Yu et
al. 2008). The method provides multi-peak fitting B0 field and T2-
correction. The toolbox also provides a function for unwrapping phase
data in 2D and 3D based on a best path method (Abdul-Rahman et al. 2007;
Herraez et al. 2002). It also contains a function that allows simulating
gradient echo Dixon data. Most of the functionality is demonstrated in
the demo.nb.
A wrapper that calls the Elastix registration framework (Klein et al.
2010; Shamonin 2013). The toolbox determines what registration or
transformations need to be performed, exports the related data to a temp
folder and calls an automatically generated command line script that
performs the registration. After registration is completed the data is
again loaded into Mathematica. Most of the functionality is demonstrated
in the demo.nb.
This toolbox provides core functions used in many other functions and
features. The functions comprise amongst others: data cropping,
mathematical and statistical operators that ignore zero values, and data
rescaling, transformation and padding. Most of the functionality is
demonstrated in the demo.nb.
The main feature is an algorithm that uses static repulsion (Jones,
Horsfield, and Simmons 1999; Froeling et al. 2017) to generate
homogeneously distributed gradient directions for DWI experiments. It
also provides functions to convert bval and bvec files to bmatrix and
vice versa. Most of the functionality is demonstrated in the demo.nb.
Allows importing DCM data or DCM header attributes. These functions are
rarely used since the toolbox mostly uses the NIfTY data format and
provides tools to convert DCM to NIfTI via
dcm2niix. This toolbox is not
demonstrated in the demo.nb.
The toolbox includes functions to perform IVIM fitting of DWI data.
There are two main functions: non linear fitting and Bayesian fitting
(Orton et al. 2014). Some of the functionality is demonstrated in the
demo.nb.
A toolbox that allows simulation of NMR spectra using Hamiltonians based
on methods from FID-A. It allows
simulating large spin systems (Castillo, Patiny, and Wist 2011) and was
mainly implemented to investigate fat spectra in TSE (Stokes et al.
2013). Most of the functionality is demonstrated in the demo.nb.
Tools for masking and homogenization of data. It provides functions for
smoothing cutting and merging masks and functions for the evaluation of
data within masks. Most of the functionality is demonstrated in the
demo.nb.
Import and export of the NIfTI file format. Part of the code is based on
previously implemented
nii-converter. For
converting DICOM data to the NIfTI file format the toolbox uses
dcm2niix. It also
provides some specialized NIfTI import functions for specific
experiments which are probably not generalizable. Most of the
functionality is demonstrated in the demo.nb.
Functions for importing and analyzing Philips physiology logging and
RespirAct trace files. The functions are rarely used and not well
supported. This toolbox is not demonstrated in the demo.nb.
A variety of functions for visualization of various data types. The main
functions are ‘PlotData’ and ‘PlotData3D’ which allow viewing 2D, 3D and
4D data. Most of the functionality is demonstrated in the demo.nb.
A variety of function for raw MRI data reconstruction. The main goal was to create a set of functions that allow for the reconstruction of multi coil 3D CSI data and and low SNR 31P imaging data. For this toolbox there is no demo.
The toolbox comprises a variety of functions that allow data
manipulation and analysis. The main functions allow joining multiple
data sets into one continuous data set (Froeling et al. 2015) or to
split data of two legs into two separate data-sets. Furthermore, it
contains a collection of functions for data evaluation and analysis.
Most of the functionality is demonstrated in the demo.nb.
A collection of tools to fit T2, T2*, T1rho and T1 relaxometry data.
The main function of this toolbox is an extended phase graph (EPG)
(Weigel 2015) method for multi-compartment T2 fitting of multi-echo spin
echo data (Marty et al. 2016). Therefore it provides functions to
simulate and evaluate EPG. Some of the functionality is demonstrated in
the demo.nb.
The main purpose of this toolbox is to simulate DTI based DWI data and
contains some functions to easily perform analysis of the fit results of
the simulated signals (Froeling et al. 2013). Some of the functionality
is demonstrated in the demo.nb.
The main purpose of this toolbox is to process and visualize spectra data
and allows to fit spectra using simulated basis spectra. Some of the functionality
is demonstrated in the demo.nb.
The original toolbox where the project started. The main functions in
this toolbox are to fit and evaluate the diffusion tensor model. Various
fitting methods are implemented (e.g. LLS, NLS, WLLS, and iWLLS). The
default method is an iterative weighted linear least squares approach
(Veraart et al. 2013). The tensor fitting also includes outlier
detections using REKINDLE (Tax et al. 2015) and data preparation
includes drift correction (Vos et al. 2017). Most of the functionality
is demonstrated in the demo.nb.
Import and export functions for tensor data which can be used in the
vIST/e tractography tool. None
of the functionality is demonstrated in the demo.nb.
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
Abdul-Rahman, Hussein S., Munther A. Gdeisat, David R. Burton, Michael J. Lalor, Francis Lilley, and Christopher J. Moore. 2007. “Fast and robust three-dimensional best path phase unwrapping algorithm.” Applied Optics 46 (26): 6623. https://doi.org/10.1364/AO.46.006623.
Aja-Fernandez, Santiago, Marc Niethammer, Marek Kubicki, Martha E. Shenton, and Carl Fredrik Westin. 2008. “Restoration of DWI data using a rician LMMSE estimator.” IEEE Transactions on Medical Imaging 27 (10): 1389–1403. https://doi.org/10.1109/TMI.2008.920609.
Castillo, Andrés M., Luc Patiny, and Julien Wist. 2011. “Fast and accurate algorithm for the simulation of NMR spectra of large spin systems.” Journal of Magnetic Resonance 209 (2). Academic Press: 123–30. https://doi.org/10.1016/j.jmr.2010.12.008.
Cerqueira, Manuel D., Neil J. Weissman, Vasken Dilsizian, Alice K. Jacobs, Sanjiv Kaul, Warren K. Laskey, Dudley J. Pennell, John A. Rumberger, Thomas Ryan, and Mario S. Verani. 2002. “Standardized myocardial sementation and nomenclature for tomographic imaging of the heart: A Statement for Healthcare Professionals from the Cardiac Imaging Committee of the Council on Clinical Cardiology of the American Heart Association.” Circulation 105 (4). Lippincott Williams & Wilkins: 539–42. https://doi.org/10.1161/hc0402.102975.
Froeling, Martijn, Aart J. Nederveen, Dennis F. R. Heijtel, Arno Lataster, Clemens Bos, Klaas Nicolay, Mario Maas, Maarten R. Drost, and Gustav J. Strijkers. 2012. “Diffusion-tensor MRI reveals the complex muscle architecture of the human forearm.” Journal of Magnetic Resonance Imaging 36 (1). Wiley Subscription Services, Inc., A Wiley Company: 237–48. https://doi.org/10.1002/jmri.23608.
Froeling, Martijn, Aart J. Nederveen, Klaas Nicolay, and Gustav J. Strijkers. 2013. “DTI of human skeletal muscle: The effects of diffusion encoding parameters, signal-to-noise ratio and T2 on tensor indices and fiber tracts.” NMR in Biomedicine 26 (11): 1339–52. https://doi.org/10.1002/nbm.2959.
Froeling, Martijn, Jos Oudeman, G. J. Gustav J. Strijkers, Mario Maas, M. R. Maarten R. Drost, Klaas Nicolay, and Aart J. A. J. Nederveen. 2015. “Muscle Changes Detected with Diffusion-Tensor Imaging after Long-Distance Running.” Radiology 274 (2): 548–62. https://doi.org/10.1148/radiol.14140702.
Froeling, Martijn, Chantal M. W. Tax, Sjoerd B. Vos, Peter R. Luijten, and Alexander Leemans. 2017. “MASSIVE brain dataset: Multiple acquisitions for standardization of structural imaging validation and evaluation.” Magnetic Resonance in Medicine 77 (5). Milan: 1797–1809. https://doi.org/10.1002/mrm.26259.
Herraez, Miguel Arevallilo, David R. Burton, Michael J. Lalor, and Munther A. Gdeisat. 2002. “Fast two-dimensional phase-unwrapping algorithm based on sorting by reliability following a noncontinuous path.” Applied Optics 41 (35): 7437. https://doi.org/10.1364/AO.41.007437.
Jones, D. K., M. A. Horsfield, and A. Simmons. 1999. “Optimal strategies for measuring diffusion in anisotropic systems by magnetic resonance imaging.” Magnetic Resonance in Medicine 42 (3). Division of Medical Physics, University of Leicester, Leicester Royal Infirmary, Leicester LE1 5WW, United Kingdom.: 515–25. https://doi.org/10.1002/(SICI)1522-2594(199909)42:3<515::AID-MRM14>3.0.CO;2-Q.
Klein, Stefan, Marius Staring, Keelin Murphy, Max A. Viergever, and Josien P. W. Pluim. 2010. “Elastix: A toolbox for intensity-based medical image registration.” IEEE Transactions on Medical Imaging 29 (1): 196–205. https://doi.org/10.1109/TMI.2009.2035616.
Lee, Jee Eun, M. K. Chung, and A. L. Alexander. 2006. “Evaluation of Anisotropic Filters for Diffusion Tensor Imaging.” In 3rd Ieee International Symposium on Biomedical Imaging, 77–80. IEEE. https://doi.org/10.1109/ISBI.2006.1624856.
Marty, Benjamin, Pierre Yves Baudin, Harmen Reyngoudt, Noura Azzabou, Ericky C. A. Araujo, Pierre G. Carlier, and Paulo L. de Sousa. 2016. “Simultaneous muscle water T2and fat fraction mapping using transverse relaxometry with stimulated echo compensation.” NMR in Biomedicine 29 (4): 431–43. https://doi.org/10.1002/nbm.3459.
Orton, Matthew R., David J. Collins, Dow-Mu Koh, and Martin O. Leach. 2014. “Improved intravoxel incoherent motion analysis of diffusion weighted imaging by data driven Bayesian modeling.” Magnetic Resonance in Medicine 71 (1): 411–20. https://doi.org/10.1002/mrm.24649.
Reeder, Scott B., Angel R. Pineda, Zhifei Wen, Ann Shimakawa, Huanzhou Yu, Jean H. Brittain, Garry E. Gold, Christopher H. Beaulieu, and Norbert T. Pelc. 2005. “Iterative decomposition of water and fat with echo asymmetry and least-squares estimation (IDEAL): Application with fast spin-echo imaging.” Magnetic Resonance in Medicine 54 (3): 636–44. https://doi.org/10.1002/mrm.20624.
Shamonin, Denis. 2013. “Fast parallel image registration on CPU and GPU for diagnostic classification of Alzheimer’s disease.” Frontiers in Neuroinformatics 7 (January): 50. https://doi.org/10.3389/fninf.2013.00050.
Stokes, Ashley M., Yesu Feng, Tanya Mitropoulos, and Warren S. Warren. 2013. “Enhanced refocusing of fat signals using optimized multipulse echo sequences.” Magnetic Resonance in Medicine 69 (4). Wiley-Blackwell: 1044–55. https://doi.org/10.1002/mrm.24340.
Tax, Chantal M.W., Willem M. Otte, Max A. Viergever, Rick M. Dijkhuizen, and Alexander Leemans. 2015. “REKINDLE: Robust Extraction of Kurtosis INDices with Linear Estimation.” Magnetic Resonance in Medicine 73 (2): 794–808. https://doi.org/10.1002/mrm.25165.
Veraart, Jelle, Els Fieremans, and Dmitry S. Novikov. 2016. “Diffusion MRI noise mapping using random matrix theory.” Magnetic Resonance in Medicine 76 (5): 1582–93. https://doi.org/10.1002/mrm.26059.
Veraart, Jelle, Dmitry S. Novikov, Daan Christiaens, Benjamin Ades-aron, Jan Sijbers, and Els Fieremans. 2016. “Denoising of diffusion MRI using random matrix theory.” NeuroImage 142 (November). Elsevier Inc.: 394–406. https://doi.org/10.1016/j.neuroimage.2016.08.016.
Veraart, Jelle, Jan Sijbers, Stefan Sunaert, Alexander Leemans, and Ben Jeurissen. 2013. “Weighted linear least squares estimation of diffusion MRI parameters: Strengths, limitations, and pitfalls.” NeuroImage 81 (November). Elsevier Inc.: 335–46. https://doi.org/10.1016/j.neuroimage.2013.05.028.
Vos, Sjoerd B., Chantal M. W. Tax, Peter R. Luijten, Sebastien Ourselin, Alexander Leemans, and Martijn Froeling. 2017. “The importance of correcting for signal drift in diffusion MRI.” Magnetic Resonance in Medicine 77 (1): 285–99. https://doi.org/10.1002/mrm.26124.
Weigel, Matthias. 2015. “Extended phase graphs: Dephasing, RF pulses, and echoes - pure and simple.” Journal of Magnetic Resonance Imaging 41 (2). Wiley-Blackwell: 266–95. https://doi.org/10.1002/jmri.24619.
Yu, Huanzhou, Ann Shimakawa, Charles A. McKenzie, Ethan Brodsky, Jean H. Brittain, and Scott B. Reeder. 2008. “Multiecho water-fat separation and simultaneous R*2 estimation with multifrequency fat spectrum modeling.” Magnetic Resonance in Medicine 60 (5): 1122–34. https://doi.org/10.1002/mrm.21737.