Ball-and-Stick Model Fitting in Teem

The crucial part of the C code written for our paper [SWK10] is available in the open source library Teem. This page explains how to build and use it, and provides additional code for a simple command-line tool that can be used to fit the ball-and-stick model to a set of single-shell diffusion weighted images. In case you should run into any problems with the code or instructions, please let me know.

Building Support for Levmar into Teem

Fitting makes use of the Levenberg-Marquard optimization method, which is implemented in the levmar library. Before you proceed to install Teem, please download and build levmar. In order to build it as a shared (rather than static) library on Linux, I am using a small patch that you can simply download and apply in the levmar source directory using

patch < levmar-shared.diff

Afterwards, typing make will start compilation of the levmar library. This patch and the demo program provided below have been tested with version 2.6 of levmar.

The relevant modules in Teem are called tijk (higher-order tensor algebra) and elf (contains the actual fitting). Both are still flagged as “experimental”, so make sure to get the latest version from the SVN and enable experimental libraries when building Teem. In addition to following the guidance provided in our introduction, please make sure that in cmake, Teem_LEVMAR is set to “ON” and the relevant variables LEVMAR_INCLUDE_DIR and LEVMAR_LIBRARY are set to the correct directory and shared library file, respectively.

An Example Program for Ball-and-Stick Fitting

A simple command-line tool that demonstrates how to use the code in Teem to fit the ball-and-stick model to a reference image and a set of single-shell DWIs is available for download.

If you are on Linux and have been able to install levmar and Teem as described above, you should be able to build the demo program by adjusting the TEEMDIR and LEVMARDIR variables in the provided Makefile and typing make. fit-ballstick expects its input in the NRRD file format, with DWI meta-information encoded in key-value pairs. If you are unfamiliar with this format, NA-MIC offers a page with specific advise on how to convert your data.

Setting the Number of Sticks

To keep the example program as simple as possible, it fits a fixed number of stick compartments to all given voxels. Our paper [SWK10] discusses different ways of estimating an appropriate number of sticks based on the data. Teem currently does not provide routines that support any of them, but compared to the actual fitting, they are straightforward to implement. Details on the Bayesian Information Criterion and F-Test can be found in [FOK07]. Our own test is based on thresholding the volume fraction estimates from the discretized ODF. The results reported in our paper perform this test after elfBallStickPredict (which is therefore run repeatedly in most voxels), but before elfBallStickOptimize, so that the costly Levenberg-Marquard step is performed only once per voxel.


[FOK07]R. Freidlin, E. Özarslan, M. Komlosh, L.C. Chang, C. Koay, D. Jones, and P. Basser. Parsimonious model selection for tissue segmentation and classification applications: A study using simulated and experimental DTI data. IEEE Trans. Med. Imaging 26(11):1576-1584, 2007.
[SWK10](1, 2) Thomas Schultz, Carl-Fredrik Westin, and Gordon Kindlmann. Multi-Diffusion-Tensor Fitting via Spherical Deconvolution: A Unifying Framework. MICCAI 2010, Part I. LNCS 6361, pp. 673-680, Springer, 2010.