NODDI Matlab Toolbox

What's New?

27th of October 2017: Version 1.0 of the NODDI toolbox released which fixed the issue that slows the fitting on the more recent Matlab versions.

27th of October 2017: Check out the recent paper on validating NODDI with histological analysis, which was highlighted in a Nature Review article.

11th of August 2017: A new tutorial on how to explore DWI data (see below)

Introduction

This tutorial describes the fitting of NODDI data using Matlab. It assumes that you have a basic understanding of the technique itself as well as diffusion MRI. If you need to learn about NODDI, please refer to our NeuroImage paper or the video of the ISMRM 2012 presentation. The tutorial includes the link to the NODDI matlab toolbox, an example NODDI data set, and a step-by-step instruction on how to use the toolbox to analyze the example data set.

Applications of NODDI

For a list of recent applications of the NODDI technique, please visit the NODDI toolbox page on NITRC, which we use to host the software and example dataset downloads (see below).

Software requirements (Updated in October 2017)

The toolbox requires

From the version 0.9 onward, the parallel computing Matlab toolbox will no longer be required but is recommended. See the instructions below for detail.

Download the toolbox

Click here to download the latest (October 2017) release: version 1.0. Please refer to the release notes for the detailed changes.

Download the example data set

The data set is available for download as a compressed zip archive.

The archive contains

  • one 4-D diffusion-weighted MRI (DWI) volume: NODDI_DWI.hdr/img
  • the corresponding brain region binary mask: brain_mask.hdr/img
  • one region-of-interest (ROI) binary mask: roi_mask.hdr/img
  • the corresponding NODDI protocol in FSL's bval/bvec format: NODDI_protocol.bval/bvec
  • the expected outputs in the subdirectory output (see below for the detail)

Acknowledgement: The example data set is generously provided by Dr. Gavin Winston from the UK Epilepsy Society MRI Unit at Chalfont. The MRI scanner at the unit is funded by the Big Lottery Fund, Wolfson Trust and the Epilepsy Society. The collection of this data was undertaken at UCLH/UCL who received a proportion of funding from the Department of Health's NIHR Biomedical Research Centres funding scheme.

Read the tutorial on how to explore DWI data (NEW)

I have written this tutorial after finding myself helping many users who have treated DWI data as a black box and never ventured to explore the data. Not doing so often prevents one to realise early on that there might be something wrong with the raw data, which could be either easily resolved issues concerning data formatting or organisation or more serious issues concerning the quality of the data.

This tutorial will help anyone develop a good understanding of how to look at DWI data and, in doing so, understand how the data should look like which will help identify issues with one's own data. It can be downloaded by clicking here.

Join NODDI google group

The NODDI google group keeps you up-to-date with the release of new versions with bug fixes and performance enhancement. It also provides a forum for you to send us your feedback and questions. So, please take a moment now to join the group by visiting http://groups.google.com/group/noddi.

Note that the forum is moderated: When you post a message for the first time, it will not appear automatically until we have a chance to verify that the message is not spam. So don't be alarmed if your message does not appear right away. The verification usually takes less than a day.

Step-by-step getting started tutorial

  • Include niftimatlib and NODDI toolbox in the matlab search path:
Assuming that you have unpacked the NODDI toolbox in the directory /usr/local/NODDI_tool, then run
addpath(genpath('/usr/local/NODDI_tool'))
For niftimatlib, follow its instructions to do the same.
  • Convert the raw DWI volume into the required format with the function CreateROI:
Assuming that you have unpacked the NODDI example data set in the directory /usr/local/NODDI_example_dataset, then to convert NODDI_DWI.hdr/img, first change your current directory to /usr/local/NODDI_example_dataset
cd /usr/local/NODDI_example_dataset
then run
CreateROI('NODDI_DWI.hdr', 'roi_mask.hdr', 'NODDI_roi.mat');
The second argument specifies the ROI mask which defines the foreground voxels for model fitting. In practice, the mask should generally be inclusive of the entire brain. For the purpose of this tutorial, we will start with a region consisting of just a single axial slice. The third argument specifies the name of the mat file for outputting the resulting data formatted for subsequent analysis. The NODDI model fitting involves non-linear optimization and hence is computational intensive. For efficiency, always create a good brain mask that excludes voxels that do not need to be fitted.
NOTE: The 4-D DWI volumes and the 3-D ROI mask volume can be in the NIfTI or Analyze formats. But the files should NOT be gizipped, i.e., with gz as a suffix (e.g. nii.gz or img.gz)
  • Convert the FSL bval/bvec files into the required format with the function FSL2Protocol:
protocol = FSL2Protocol('NODDI_protocol.bval', 'NODDI_protocol.bvec');

For Camino users, the Scheme file can be converted into the required format with the function SchemeToProtocol:

protocol = SchemeToProtocol('NODDI_protocol.scheme');
  • Create the NODDI model structure with the function MakeModel:
noddi = MakeModel('WatsonSHStickTortIsoV_B0');
'WatsonSHStickTortIsoV_B0' is the internal name for the NODDI model. The structure noddi holds the details of the NODDI model relevant for the subsequent fitting. For most users, the default setting should suffice.
  • Run the NODDI fitting with the function batch_fitting, if you have the parallel computing toolbox, or batch_fitting_single, if you do not:
batch_fitting('NODDI_roi.mat', protocol, noddi, 'FittedParams.mat', 8);
The first three arguments to the function are explained in the previous steps. The fourth argument specifies the mat file name to store the estimated NODDI parameters. The final argument sets the number of computing cores to use for running the fitting in parallel. This argument is optional. If not specified, the function will let Matlab choose the default setting. On a 8-core machine, the fitting should finish in around 15 minutes.
The usage for batch_fitting_single is similar (NEW):
batch_fitting_single('NODDI_roi.mat', protocol, noddi, 'FittedParams.mat');
  • Convert the estimated NODDI parameters into volumetric parameter maps (Updated in May 2013):
SaveParamsAsNIfTI('FittedParams.mat', 'NODDI_roi.mat', 'brain_mask.hdr', 'example')
This function converts the fitted parameters (1st argument) into NIfTI formatted volumes with the same spatial dimension as the original image, specified by the brain mask (3rd argument). The function also requires as input the roi file (2nd argument). In addition, you also need to specify a prefix to the output volumes with the final argument. (Prior to Version 0.9, you also need to input the model, which is now stored alongside the fitted parameter file.)
  • Verify the output:

At this point, you should find the following output volumes:

  • Neurite density (or intra-cellular volume fraction): example_ficvf.nii
  • Orientation dispersion index (ODI): example_odi.nii
  • CSF volume fraction: example_fiso.nii
  • Fibre orientation: example_fibredirs_{x,y,z}vec.nii
  • Fitting objective function values: example_fmin.nii
  • Concentration parameter of Watson distribution used to compute ODI: example_kappa.nii
  • Error code: example_error_code.nii (NEW) Nonzero values indicate fitting errors.
Compare with the expected output in the output subdirectory. (The content in the output directory will reflect the results from the pre-0.9 versions. So don't be alarmed if you do not see the error code volume.)
If everything has worked as expected, you can repeat the tutorial with the ROI mask for the entire brain. Be warned that this will take a while. On a 8-core workstation, this may take overnight.

Questions or Comments

I hope you get to this point having successfully reproduced the step-by-step tutorial and are now ready to apply NODDI in your own studies. But if you do run into difficulties or have comments or suggestions, please don't hesitate to post them to the NODDI google group.

Back to previous page