.. Ball-and-stick fitting in Teem
.. highlight:: c
.. _Teem: http://teem.sf.net/
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
.. code-block:: sh
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.
References
----------
.. [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] 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.