section_Dipy_Utilities_for_Models__.tex

\section{Dipy Utilities for Models}

\subsection{Gradient Table}
Dipy provides some tools for making the implementation of new models easier. The first of these tools is the \verb|GradientTable| class. A gradient table object can be initialized from gradient table files, for example \verb|bvec| and \verb|bval| files commonly used in diffusion imaging, or simply an array of gradients by using the \verb|gradient_table| factory function in \verb|dipy.core.gradients|. A gradient table object allows a user to easily access different representations of gradient information. For example, the \verb|bvals| attribute of the gradient table object exposes the diffusion weighting, commonly known as the b-value, of each gradient. Similarly, the \verb|bvecs| attribute exposes the direction of each gradient as a unit vector and the \verb|gradients| attribute exposes the total gradient vector.

\subsection{Spheres and Hemispheres}
Dipy uses the \verb|Sphere| and \verb|HemiSphere| classes as discrete representations of the unit sphere. The \verb|HemiShere| class is a subclass of the \verb|Sphere| class, provides the same interface, and can be used anywhere Dipy requires a \verb|Sphere| instance.  Both \verb|Sphere| and \verb|HemiSphere| objects consist primarily of a set of dispersed points, or vertices, on the unit sphere. The \verb|Sphere| class also provides \verb|faces| and \verb|edges| attributes which provide neighbor information about the vertices of the sphere. Each face of the \verb|Sphere| is triplet of integers between 0 and N - 1, where N is the number of points of the \verb|Sphere|. The faces, taken together, make up a mesh surface which approximates a sphere. Each edge of a \verb|Sphere| is a pair of integers between 0 and N - 1 and represents two neighbor points. Each point has a neighbor relationship with the closest points to itself. This neighbor relationship is important for peak finding and fiber tracking applications.

Though the \verb|Sphere| and \verb|HemiSphere| classes are similar, there is one key difference. The \verb|HemiSphere| class incorporates an understanding of antipodal symmetry into its definition of distance between points. On the surface of the sphere, we can define a distance function between two points, $\vec{v_1}$ and $\vec{v_2}$ as $d(\vec{v_1}, \vec{v_2}) = cos^{-1}(\vec{v_1} \cdot \vec{v_2})$. This is the intuitive definition of distance that is familiar to most people. Under this definition, the points $\vec{v}$ and $-\vec{v}$ are separated by a distance of $\pi$, the furthest possible distance between two points on a unit sphere. In the context of diffusion imaging, we want to be able to represent antipodally symmetric distance function where the points $v$ and $-v$ are in effect the same point. To represent this symmetry, we can define a new distance function on the sphere, $d(\vec{v_1}, \vec{v_2}) = cos^{-1}(|\vec{v_1} \cdot \vec{v_2}|)$. By using this new distance function, the \verb|HemiSphere| class is able to effectively represent an antipodally symmetric sphere with half as many points, without loosing important neighbor relations. While it is redundant to use a full \verb|Sphere| to represent an antipodally symmetric spherical surface, sometimes a full \verb|Sphere| object can still be useful, for example for visualizing spherical functions without discontinuities. The \verb|HemiSphere| class provides a \verb|mirror| method to duplicate and project the vertices of a \verb|HemiSphere| onto a full sphere. Figures \ref{fig:hemiSphere} and \ref{fig:fullSphere} show a 3d rendering of a \verb|HemiSphere| and its mirror respectively.

Dipy provides a \verb|default_sphere| object, which is an instance of \verb|HemiSphere|, in \verb|dipy.data|. The \verb|default_sphere| consists of 362 vertices dispersed on a unit hemisphere. We've found that this number of points provides a good balance between coverage and computational performance.