rad-dude/mritoolkit

MRIToolkit [update 24-10-2020]

This is the latest update before the release of v1.1, which will simplify the overall structure and focus on the integration of the MATLAB-based library with other existing pipelines and tools (e.g. FSL). The aim of the new release is also to deploy standalone executables that simplify running common dMRI analyses pipelines.

Since the last update, each method of MRIToolkit stamps its version (from git) and parameters in a sidecar .JSON file for reproducibility!

What is it?

MRIToolkit is a set of command line tools and a MATLAB (R) toolbox/library to process (diffusion) magnetic resonance imaging (MRI) data. Binaries of the command line version will be provided soon!

The idea behind MRIToolkit is to integrate methods I develop with existing state-of-the-art methods for (diffusion) MRI processing.

Where do I find it?

• The MATLAB (R) toolbox is available here on Github!
• The compiled command line tools will be uploaded soon!

Explore the main functionalities:

Quick installation

Please, see this guide

• I have coded most functions to accept Python-like name/value argument couples. To know which arguments to specify, just try the MATLAB help as, for instance, "help EDTI.LoadNifti"
• The file naming convention is to always indicate Niftis as .nii, even when they are actually compressed in .nii.gz. The code takes care of that, but expects only .nii as arguments in function calls!

Getting started

Examples of some functionalities can be found in here

Requirements:

• MRIToolkit relies on a couple of third party dependencies:
  • Elastix:
    • 1. Either compile your own version or grab the executables for your platform here.
    • 2. Copy the file "TemplateMRIToolkitDefineLocalVars.m" to your MATLAB default folder (user/MATLAB or Documents/MATLAB), rename the file as "MRIToolkitDefineLocalVars.m".
    • 3. Edit the script, adjusting the variable MRIToolkit.Elastix.Location as needed.
  • NODDI toolbox: if you would like to try the mFOD method, you will need to add the NODDI toolbox to the MATLAB path.
  • ExploreDTI: While MRIToolkit is entirely self-sufficient (e.g. all needed ExploreDTI functions are bundled and adapted), the visualization of fiber tractograhy and other results will need ExploreDTI. Get it for free from Alexander Leemans.

Notes:

• MRIToolkit is NOT approved for clinical use
• This code is a work in progress. It will be updated without notice to ensure bug-fixes and the inclusion of best available methods

License:

• This software is distributed under the LGPLv3 license (https://opensource.org/licenses/lgpl-3.0.html).

References:

The toolbox is referenced for the first time in Guo et al.. Additionally, please cite the original works corresponding to the steps you use:

• ExploreDTI: Leemans, A., Jeurissen, B., Sijbers, J., & Jones, D. K. (2009). ExploreDTI: a graphical toolbox for processing, analyzing, and visualizing diffusion MR data. 17th Annual Meeting of the International Society for Magnetic Resonance in Medicine, Honolulu, Hawaii, USA, 3537.
• Diffusion MRI pre-processing: (signal drift correction, Gibbs ringing correction, motion and eddy currents correction, B-matrix rotation, EPI correction, MPPCA denoising)
• Diffusion Tensor Imaging (DTI) and Diffusion Kurtosis Imaging (DKI) fit including the MK-curve method;
• Spherical deconvolution using the Constrained Spherical Deconvolution (CSD), Multi-shell CSD, damped Richardson Lucy, the Generalized Richardson Lucy and mFOD;
• Robust deconvolution of multiple water pools (NNLS/L2NNLS/PL2NNLS) as in De Luca et al. 2018

Keywords:

• Magnetic Resonance Imaging (MRI)
• Image segmentation
• T1 quantification, Inversion Recovery
• T2 quantification, spin echo multi echo
• Extended Phase Graphs
• Diffusion MRI (dMRI) - Diffusion Tensor Imaging (DTI) - Diffusion Kurtosis Imaging (DKI)
• dMRI preprocessing - motion correction - eddy currents correction - EPI distortions correction
• Fiber tractography - Constrained Spherical Deconvolution (CSD) - Generalized Richardson Lucy (GRL) - mFOD
• Laplacian fit - Spectral Fit - Robust Deconvolution

Toolbox components

Ready to use:

• 'ExploreDTIInterface': I am pleased to announce that MRIToolkit now contains, distributes and develops many functions originally developed as part of ExploreDTI. They are here available as a consolidated library and are planned to also become command line tools. A big thank to Alexander Leemans and Ben Jeurissen for this!
  
• 'SphericalDeconvolution': Methods used for two novel deconvolution methods we developed, namely the Generalized Richardson Lucy and mFOD. Some of the functions here included have been taken from Hardi Tools of Erick Canales-Rodriguez.
• • 'LesionEditor': a graphical user interface to visualise and edit segmentations of 3D MRI images, originally designed for delineation of multiple-sclerosis lesions on fluid attenuated inversion recovery (FLAIR) images. Requires MATLAB R2018a or newer. Documentation coming soon
• 'NiftiIO_basic': Basic Nifti input/output, including code originally written by Jimmy Shen
• 'DW_basic': Utilities to load / manipulate / save dMRI data
• 'OptimizationMethods': Classes and functions for numeric optimisation methods
• 'Relaxometry': Classes for T1/T2 quantification using inversion-recovery / spin-echo multi-echo data
• 'ThirdParty': Utilities from third parties used in other scripts. Includes EPG code from Brian Hargreaves
• 'ImageRegistrations': Image registration utils based on Elastix
• 'GettingStarted': Small examples showcasing functionalities of MRIToolkit.

Being integrated and coming soon:

• 'Diffusion_basic': Class for (basic) dMRI quantification

• 'DW_IVIMDTDK_I': Diffusion MRI fit utilities - IVIM, DT, DKI - used in De Luca et al. 2017

• 'Dicom_utils': Tools for handling unconventional or buggy DICOMs

• 'MixedCodeUtils': 'Useful general purpose functions

• 'MRIfoundation': Classes for MRI sequences abstraction

• 'EPG_simulator': Classes for EPG simulations

Not yet planned for release (contact me directly if interested):

• 'dfMRI', Diffusion fMRI utilities used in De Luca et al. 2019

Alberto De Luca - First published in 2019