tracking - models.tex

\section{Model the diffusion signal}
The first step in any diffusion MRI analysis, after pre-processing is complete, is to model the diffusion MRI signal. The model that one chooses depends on several factors. As with most modeling applications, the right model will balance several competing priorities including: simplicity of the model, assumptions built into the model, and accuracy of the result. In diffusion MRI, finding the optimal balance largely depends on the characteristics of the data to be modeled and the specifics of the application. For example, when the diffusion data to be modeled includes images acquired with different diffusion weightings, often called multiple q-shell data, a more complex model like Multitissue Constrained Deconvolution or Diffuison Spectrum Imaging can be used. If the data is acquired using a large number of diffusion gradient directions, more than 50, on a single q-shell with moderate to high b-value, then an intermediate model like QBall or Constrained Spherical Deconvolution might be the best choice. For data sets with a low b-value or a relatively few gradient directions, than a more simple model, such as DTI, is most appropriate. 

It's also important to consider the requirements of the application when picking a model. While a given data set might support more complex modeling, if the goal of the project is identify large, well defined white matter tracts in the brain, then the additional complexity and computational cost associated with a more complex model might not be justified. However, if the goal is to model areas of the cerebral white matter with finer structures and axonal crossings, than a simple model like DTI will simply fail to capture the underlying complexity of the biological architecture. The choice of model is often a subtle decision that can only be made empirically. Dipy aims to aid the user in the task of choosing the right models by providing a model API so that users can run the same tracking and analysis methods using different models in order to compare results.

\subsection{Model and Fit Classes}
Models in dipy serve two related functions. First a model can be used to fit diffusion MRI signals and estimate model parameters. Second, some dipy models provide a \verb|predict| method, which allows the model to predict diffusion MRI signals from model parameters. Here is a formal description of the model and fit interfaces in Dipy.

\begin{enumerate}
\item The model class.
\begin{enumerate}
\item Models classes are initialized with any required parameters to create model instances. In this context, a gradient table is considered a parameter and should be passed to the model in the constructor.
\item Models should have a \verb|fit| method. The \verb|fit| method should return a fit object, meaning an instance of a fit class.
\begin{enumerate}
\item The \verb|fit| method should take two parameters: data and mask. Data is an array of diffusion MRI signals and mask is a binary array where True values identify the non-background voxels of the image.
\end{enumerate}
\item The model may have a \verb|predict| method. The predict method should predict diffusion signals from model parameters.
\begin{enumerate}
\item The predict method should take two arguments: model parameters and a gradient table. The gradient table argument should be optional and the gradient table associated with the model should be used, by default.
\end{enumerate}
\end{enumerate}
\end{enumerate}
\begin{enumerate}
    \item The fit class.
    \begin{enumerate}
        \item Each fit object should have a \verb|model| attribute which will generally be the model object used to create the fit object.
        \item The fit class may also have a \verb|predict| method. The predict method of the fit class does not take model parameters as an argument, instead it estimates a signal prediction based on the model parameters associated with the fit instance.
        \item The fit object may have an \verb|odf| method which takes a \verb|Sphere| instance as an argument and returns an the Orientation Distrubtion Function estimated by the model and sampled on the vertices of the \verb|Sphere| instance. The \verb|odf| method is used for peak finding and fiber tracking.
        \item The fit class may have attributes and methods specific to the model type which the fit represents. For example, a DTI fit has the attributes \verb|fa| and \verb|md| which are the fractional anisotropy and mean diffusivity, respectively, of the diffusion tensor.
    \end{enumerate}
\end{enumerate}

All the models in dipy follow this basic interface. Dipy only enforces this interface through "duck typing", meaning the interface is checked at run time on an as needed basis, as opposed to strictly enforced using a mechanism such as inheritance. The result of this design choice is that Dipy does not require all model classes to implement the entire model interface. However, a model class that omits part of the interface may fail if it interacts with dipy functions or methods which require the missing portion of the interface.