ekaden / smt

Microscopic diffusion anisotropy imaging made easy!

SMT

The Spherical Mean Technique (SMT) is a clinically feasible method for microscopic diffusion anisotropy imaging. The purpose is to map microscopic features unconfounded by the effects of fibre crossings and orientation dispersion, which are ubiquitous in the brain. This technique requires only an off-the-shelf diffusion sequence with two (or more) b-shells achievable on any standard MRI scanner, thus facilitating its widespread use in neuroscience research and clinical neurology. So far, SMT comes in two flavours, a microscopic tensor model and a simple multi-compartment model. This software was developed and is maintained by Enrico Kaden from University College London.

Installing

Prebuilt SMT binaries are available for 64-bit Linux and macOS systems:

• Download the latest SMT release.
• Unpack the software archive.
• Set the path variable using export PATH="/path/to/smt/bin:${PATH}" (in bash) or setenv PATH "/path/to/smt/bin:${PATH}" (in csh).

Building

SMT requires the following software (tested under Red Hat Enterprise Linux 6 and Apple macOS Mojave 10.14):

• git (version 1.9 or later)
• cmake (version 2.8 or later)
• GNU C/C++ compiler (version 4.9 or later), Clang C/C++ compiler (version 3.5 or later) or Intel C/C++ compiler (version 16.0 or later)

Clone the SMT repository and checkout the latest release:

git clone https://github.com/ekaden/smt.git
cd smt
git fetch -p
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
cd ..

Build the software:

mkdir smt-build
cd smt-build
cmake ../smt
make

If necessary, the C/C++ compiler can be set explicitly, for example:

cmake ../smt -DCMAKE_C_COMPILER=gcc-4.9 -DCMAKE_CXX_COMPILER=g++-4.9
make

The SMT programs are located in the build directory.

Gaussian noise estimation

This utility software provides a voxelwise estimate of the Gaussian-distributed noise from, for example, a set of zero b-value images.

Usage

gaussianfit [options] <input> <output>
gaussianfit (-h | --help)
gaussianfit --license
gaussianfit --version

• <input> –– Input data set in NIfTI-1 format

• <output> –– Output parameter maps in NIfTI-1 format, including:

  1. Mean parameter (mean)
  2. Standard deviation parameter (std)

If the output name contains a placeholder {} (e.g. output_{}.nii), the parameter maps are written to separate files using the suffices given in parentheses. Otherwise the output parameter maps are stored in a single file.

Options

• --mask <mask> –– Foreground mask [default: none]. Values greater than zero are considered as foreground.

• -h, --help –– Help screen

• --license –– License information

• --version –– Software version

Environment variables

• SMT_DEBUG=<true | positive integer –– Debug information

• SMT_NOCOLOUR=<true | positive integer or SMT_NOCOLOR=<true | positive integer –– Suppress colour output

• SMT_NUM_THREADS=<positive integer> –– Number of threads for parallel processing

• SMT_QUIET=<true | positive integer> –– Verbosity (e.g. progress bar)

Rician noise estimation

This utility software provides a voxelwise estimate of the Rician-distributed noise from, for example, a set of zero b-value images.

Usage

ricianfit [options] <input> <output>
ricianfit (-h | --help)
ricianfit --license
ricianfit --version

• <input> –– Input data set in NIfTI-1 format

• <output> –– Output parameter maps in NIfTI-1 format, including:

  1. Location parameter (loc)
  2. Scale parameter (scale)

If the output name contains a placeholder {} (e.g. output_{}.nii), the parameter maps are written to separate files using the suffices given in parentheses. Otherwise the output parameter maps are stored in a single file.

Options

• --mask <mask> –– Foreground mask [default: none]. Values greater than zero are considered as foreground.

• -h, --help –– Help screen

• --license –– License information

• --version –– Software version

Environment variables

• SMT_DEBUG=<true | positive integer –– Debug information

• SMT_NOCOLOUR=<true | positive integer or SMT_NOCOLOR=<true | positive integer –– Suppress colour output

• SMT_NUM_THREADS=<positive integer> –– Number of threads for parallel processing

• SMT_QUIET=<true | positive integer> –– Verbosity (e.g. progress bar)

Microscopic diffusion tensor

This microscopic model estimates the microscopic fractional anisotropy and other microscopic diffusion coefficients in tissue with complex directional architecture as in the brain.

Usage

fitmicrodt [options] <input> <output>
fitmicrodt (-h | --help)
fitmicrodt --licence
fitmicrodt --version

• <input> –– Input diffusion data set in NIfTI-1 format

• <output> –– Output parameter maps in NIfTI-1 format, including:

  1. Longitudinal microscopic diffusivity (long)
  2. Transverse microscopic diffusivity (trans)
  3. Microscopic fractional anisotropy (fa)
  4. Microscopic fractional anisotropy to the third power (fapow3)
  5. Microscopic mean diffusivity (md)
  6. Zero b-value image (b0)

If the output name contains a placeholder {} (e.g. output_{}.nii), the parameter maps are written to separate files using the suffices given in parentheses. Otherwise the output parameter maps are stored in a single file.

Options

• --bvals <bvals> –– Diffusion weighting factors (s/mm²), given in FSL format

• --bvecs <bvecs> –– Diffusion gradient directions, given in FSL format

• --grads <grads> –– Diffusion gradients (s/mm²), given in MRtrix format

• --graddev <graddev> –– Diffusion gradient deviation [default: none], provided as NIfTI-1 tensor volume

• --mask <mask> –– Foreground mask [default: none]. Values greater than zero are considered as foreground.

• --rician <rician> –– Rician noise [default: none]. SMT assumes Gaussian noise by default. Alternatively, a Rician noise model may be chosen, in which case the signal measurements are adjusted to reduce the Rician-noise induced bias. The noise level can be specified either globally using a scalar value or voxel by voxel using a NIfTI-1 image volume.

• --maxdiff <maxdiff> –– Maximum diffusivity (mm²/s) [default: 3.05e-3]. Typically the self/free-diffusion coefficient for a certain temperature is chosen.

• --b0 –– Model-based estimation of the zero b-value signal. By default, the zero b-value signal is estimated as the mean over the measurements with zero b-value. If this option is set, the zero b-value signal is fitted using the microscopic diffusion model. This is also the default behaviour when measurements with zero b-value are not provided.

• -h, --help –– Help screen

• --license –– License information

• --version –– Software version

Environment variables

• SMT_DEBUG=<true | positive integer –– Debug information

• SMT_NOCOLOUR=<true | positive integer or SMT_NOCOLOR=<true | positive integer –– Suppress colour output

• SMT_NUM_THREADS=<positive integer> –– Number of threads for parallel processing

• SMT_QUIET=<true | positive integer> –– Verbosity (e.g. progress bar)

Multi-compartment microscopic diffusion

This model provides estimates of microscopic features specific to the intra- and extra-neurite compartments unconfounded by the effects of the potentially complex fibre orientation distribution.

Usage

fitmcmicro [options] <input> <output>
fitmcmicro (-h | --help)
fitmcmicro --licence
fitmcmicro --version

• <input> –– Input diffusion data set in NIfTI-1 format

• <output> –– Output parameter maps in NIfTI-1 format, including:

  1. Intra-neurite volume fraction (intra)
  2. Intrinsic diffusivity (diff)
  3. Extra-neurite transverse microscopic diffusivity (extratrans)
  4. Extra-neurite microscopic mean diffusivity (extramd)
  5. Zero b-value image (b0)

If the output name contains a placeholder {} (e.g. output_{}.nii), the parameter maps are written to separate files using the suffices given in parentheses. Otherwise the output parameter maps are stored in a single file.

Options

• --bvals <bvals> –– Diffusion weighting factors (s/mm²), given in FSL format

• --bvecs <bvecs> –– Diffusion gradient directions, given in FSL format

• --grads <grads> –– Diffusion gradients (s/mm²), given in MRtrix format

• --graddev <graddev> –– Diffusion gradient deviation [default: none], provided as NIfTI-1 tensor volume

• --mask <mask> –– Foreground mask [default: none]. Values greater than zero are considered as foreground.

• --rician <rician> –– Rician noise [default: none]. SMT assumes Gaussian noise by default. Alternatively, a Rician noise model may be chosen, in which case the signal measurements are adjusted to reduce the Rician-noise induced bias. The noise level can be specified either globally using a scalar value or voxel by voxel using a NIfTI-1 image volume.

• --maxdiff <maxdiff> –– Maximum diffusivity (mm²/s) [default: 3.05e-3]. Typically the self/free-diffusion coefficient for a certain temperature is chosen.

• --b0 –– Model-based estimation of the zero b-value signal. By default, the zero b-value signal is estimated as the mean over the measurements with zero b-value. If this option is set, the zero b-value signal is fitted using the microscopic diffusion model. This is also the default behaviour when measurements with zero b-value are not provided.

• -h, --help –– Help screen

• --license –– License information

• --version –– Software version

Environment variables

• SMT_DEBUG=<true | positive integer –– Debug information

• SMT_NOCOLOUR=<true | positive integer or SMT_NOCOLOR=<true | positive integer –– Suppress colour output

• SMT_NUM_THREADS=<positive integer> –– Number of threads for parallel processing

• SMT_QUIET=<true | positive integer> –– Verbosity (e.g. progress bar)

Citation

If you use this software, please cite:

• General Spherical Mean Technique (SMT)

Kaden E, Kruggel F, and Alexander DC: Quantitative Mapping of the Per-Axon Diffusion Coefficients in Brain White Matter. Magnetic Resonance in Medicine, vol. 75, pp. 1752–1763, 2016. DOI: 10.1002/mrm.25734

• Microscopic diffusion tensor model

Kaden E, Kruggel F, and Alexander DC: Quantitative Mapping of the Per-Axon Diffusion Coefficients in Brain White Matter. Magnetic Resonance in Medicine, vol. 75, pp. 1752–1763, 2016. DOI: 10.1002/mrm.25734

• Multi-compartment microscopic diffusion model

Kaden E, Kelm ND, Carson RP, Does MD, and Alexander DC: Multi-compartment microscopic diffusion imaging. NeuroImage, vol. 139, pp. 346–359, 2016. DOI: 10.1016/j.neuroimage.2016.06.002

Supplementary material

• ISMRM 2016 slides
• OHBM 2016 poster

License

SMT is released under the BSD Two-Clause License. This software is based on or incorporates materials from third-party projects.

smt's Issues

mcmicro_INVF maps with "holes"

Dear SMT team,

I have multi-band, multi-shell DWI data (MB factor3; b1000 25/6; b2000 45/6;b2800 63/6)
Data merged using mrtrix command 'mrcat'
merged data were then preprocessed for: eddy, topup (with blip up/down, 2x phase reversal b0), bias field correction)

Ran fitmcmicro --bvals merged_dc_bc.bvals --bvecs merged_dc_bc.bvecs --mask merged_dc_mask.nii merged_dc_bc.nii mcmicro.nii

When inspected the 1st volume of the mcmicro map (INVF), I note there are multiple 'holes' in the map--mostly in the GM, also some in WM. (See attached screen shot)

Any idea what could have cause this and ways to fix this problem?

many thanks

Does SMT available for MATLAB users also?

Dear Enrico!

Might I be asking out of the box, Does SMT available in Matlab also?

I am not used to with C++ anymore. It will be very helpful in Matlab. I am developing Conductivity tensor imaging method. For which I need volume fraction and Intra & Extra Diffusivity. SMT has that advantage over noddi.

Please let me know if it's available.

Will be very thankful of yours

Best regards,
Nitish

micro FA and INVF (ex-vivo)

Hi,

Firstly, thank you for your sharing your great work and code!

I would like to know your thoughts on SMT for ex-vivo imaging.
I was able to get fine SMT images in our in-vivo human data; however, something appeared to go wrong with our SMT analysis on ex-vivo mouse data.

Although I got a (apparently) normal micro-MD image (and a normal ICVF image from NODDI using MATLAB), almost all the value in the parenchyma, especially gray matter, was zero in SMT INVF and micro-FA images.

(maxdiff = 1.88e-3; values are displayed in the range [0,1] except MD)

Any help would be hugely appreciated.

Daisuke

--rician flag input

Hello,

Why do fitmicrodt and fitmcmicro expect a nifti image with a single volume to be passed in with the --rician flag? I've been wondering about this because the Rice distribution has two parameters. The ricedebias function's second parameter's name, sigma, suggests that I can pass in the scale output from ricianfit. Is this correct?

If this is the case, why do we only pass in the scale parameter? Is the loc parameter estimated again by fitmicrodt and fitmicromc?

Thank you

Unable to read big image files

Hi, SMT team:

First of all, I want to thank you for sharing your great work with the community.

I've found a problem when trying to use the software with compressed Human Connectome Project images. The issue seems to be that gzread returns an int with the number of bytes read. In the case of HCP images, the number of bytes read is ~4GB, which is greater than the max of a 32-bit signed int. With the uncompressed images, the software runs perfectly. Maybe a fix could be reading the volume in chunks.

Also, I had an error while compiling the current master branch. It seems CMakeLists.txt is missing some info to link the pthread library. I've fixed this in my machine adding the following lines to the CMakeLists.txt:

target_link_libraries (gaussianfit ${CMAKE_THREAD_LIBS_INIT})
target_link_libraries (ricianfit ${CMAKE_THREAD_LIBS_INIT})
target_link_libraries (fitmicrodt ${CMAKE_THREAD_LIBS_INIT})
target_link_libraries (fitmcmicro ${CMAKE_THREAD_LIBS_INIT})

I hope that helps.
Alberto

Gradient directions not normalised message

Hi,

Thank you for the great work on SMT. We are trying to run the analysis fitmcmicro/fitmicrodt on our dataset, but getting following message when using FSL format bvecs.

test.bvec has diffusion gradient directions which are not normalised.

Also tried to normalize the vectors to make sure they are unit length and tested, still getting this message. Can you please assist if you have a sample data for bvecs or grads file.

Thanks,
Prasanna

error message "has diffusion gradient directions which are not normalised"

HI SMT users,

My bvecs has 280 normalized vectors plus 19 non-DWI (b0) vectors, but fitmcmicro seems not happy with this format. It is not normalized because b0 vectors all have zero values, although other all unit vectors. Are b0 vectors not allowed in the --bvecs table? I believe HCP data also have a bunch of b0 volumes.

Here is the command i ran,

fitmcmicro --bvals data_DIFFPREP_t2acpc_proc_DRBUDDI_up_final_no7b0.bvals --bvecs data_DIFFPREP_t2acpc_proc_DRBUDDI_up_final_no7b0_invY_deci5.bvecs --mask structural_mask.nii.gz data_DIFFPREP_t2acpc_proc_DRBUDDI_up_final_no7b0.nii smt_mcmicro