reconst

References

Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging With Solid

Angle Consideration.

Descoteaux, M., et al. 2007. Regularized, fast, and robust analytical

Q-ball imaging.

Tristan-Vega, A., et al. 2010. A new methodology for estimation of fiber

populations in white matter of the brain with Funk-Radon transform.

Tristan-Vega, A., et al. 2009. Estimation of fiber orientation probability

density functions in high angular resolution diffusion imaging.

Note about the Transpose: In the literature the matrix representation of these methods is often written as Y = Bx where B is some design matrix and Y and x are column vectors. In our case the input data, a dwi stored as a nifti file for example, is stored as row vectors (ndarrays) of the form (x, y, z, n), where n is the number of diffusion directions. We could transpose and reshape the data to be (n, x*y*z), so that we could directly plug it into the above equation. However, I have chosen to keep the data as is and implement the relevant equations rewritten in the following form: Y.T = x.T B.T, or in python syntax data = np.dot(sh_coef, B.T) where data is Y.T and sh_coef is x.T.

bench

dipy.reconst.bench(label='fast', verbose=1, extra_argv=None)

Run benchmarks for module using nose.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional Identifies the benchmarks to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are: * ‘fast’ - the default - which corresponds to the nosetests -A option of ‘not slow’. ‘full’ - fast (as above) and slow benchmarks as in the ‘no -A’ option to nosetests - this is the same as ‘’. None or ‘’ - run all tests. attribute_identifier - string passed directly to nosetests as ‘-A’. verbose : int, optional Verbosity value for benchmark outputs, in the range 1-10. Default is 1. extra_argv : list, optional List with any extra arguments to pass to nosetests.

Returns:

success : bool Returns True if running the benchmarks works, False if an error occurred.

Notes

Benchmarks are like tests, but have names starting with “bench” instead of “test”, and can be found under the “benchmarks” sub-directory of the module.

Each NumPy module exposes bench in its namespace to run all benchmarks for it.

Examples

>>> success = np.lib.bench() 
Running benchmarks for numpy.lib
...
using 562341 items:
unique:
0.11
unique1d:
0.11
ratio: 1.0
nUnique: 56230 == 56230
...
OK

>>> success 
True

test

dipy.reconst.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None, timer=False)

Run tests for module using nose.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional Identifies the tests to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are: * ‘fast’ - the default - which corresponds to the nosetests -A option of ‘not slow’. ‘full’ - fast (as above) and slow tests as in the ‘no -A’ option to nosetests - this is the same as ‘’. None or ‘’ - run all tests. attribute_identifier - string passed directly to nosetests as ‘-A’. verbose : int, optional Verbosity value for test outputs, in the range 1-10. Default is 1. extra_argv : list, optional List with any extra arguments to pass to nosetests. doctests : bool, optional If True, run doctests in module. Default is False. coverage : bool, optional If True, report coverage of NumPy code. Default is False. (This requires the `coverage module: <http://nedbatchelder.com/code/modules/coverage.html>`_). raise_warnings : None, str or sequence of warnings, optional This specifies which warnings to configure as ‘raise’ instead of being shown once during the test execution. Valid strings are: “develop” : equals (Warning,) “release” : equals (), don’t raise on any warnings. The default is to use the class initialization value. timer : bool or int, optional Timing of individual tests with nose-timer (which needs to be installed). If True, time tests and report on all of them. If an integer (say N), report timing results for N slowest tests.

Returns:

result : object Returns the result of running the tests as a nose.result.TextTestResult object.

Notes

Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:

>>> np.lib.test() 

Examples

>>> result = np.lib.test() 
Running unit tests for numpy.lib
...
Ran 976 tests in 3.933s

OK

>>> result.errors 
[]
>>> result.knownfail 
[]

ReconstFit

class dipy.reconst.base.ReconstFit(model, data)

Bases: object

Abstract class which holds the fit result of ReconstModel

For example that could be holding FA or GFA etc.

__init__(model, data)

Initialize self. See help(type(self)) for accurate signature.

ReconstModel

class dipy.reconst.base.ReconstModel(gtab)

Bases: object

Abstract class for signal reconstruction models

Methods

fit

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters:	gtab : GradientTable class instance

fit(data, mask=None, **kwargs)

bench_bounding_box

dipy.reconst.benchmarks.bench_bounding_box.bench_bounding_box()

bounding_box

dipy.reconst.benchmarks.bench_bounding_box.bounding_box(vol)

Compute the bounding box of nonzero intensity voxels in the volume.

Parameters:	vol : ndarray Volume to compute bounding box on.
Returns:	npmins : list Array containg minimum index of each dimension npmaxs : list Array containg maximum index of each dimension

measure

dipy.reconst.benchmarks.bench_bounding_box.measure(code_str, times=1, label=None)

Return elapsed time for executing code in the namespace of the caller.

The supplied code string is compiled with the Python builtin compile. The precision of the timing is 10 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters:	code_str : str The code to be timed. times : int, optional The number of times the code is executed. Default is 1. The code is only compiled once. label : str, optional A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).
Returns:	elapsed : float Total elapsed time in seconds for executing code_str times times.

Examples

>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)',
...                            times=times)
>>> print("Time for a single execution : ", etime / times, "s")
Time for a single execution :  0.005 s

ConstrainedSphericalDeconvModel

class dipy.reconst.benchmarks.bench_csd.ConstrainedSphericalDeconvModel(gtab, response, reg_sphere=None, sh_order=8, lambda_=1, tau=0.1)

Bases: dipy.reconst.shm.SphHarmModel

Methods

cache_clear()	Clear the cache.
cache_get(tag, key[, default])	Retrieve a value from the cache.
cache_set(tag, key, value)	Store a value in the cache.
fit(data[, mask])	Fit method for every voxel in data
predict(sh_coeff[, gtab, S0])	Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.
sampling_matrix(sphere)	The matrix needed to sample ODFs from coefficients of the model.

__init__(gtab, response, reg_sphere=None, sh_order=8, lambda_=1, tau=0.1)

Constrained Spherical Deconvolution (CSD) [1].

Spherical deconvolution computes a fiber orientation distribution (FOD), also called fiber ODF (fODF) [2], as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution that is the best object to be used for later deterministic and probabilistic tractography [3].

A sharp fODF is obtained because a single fiber response function is injected as a priori knowledge. The response function is often data-driven and is thus provided as input to the ConstrainedSphericalDeconvModel. It will be used as deconvolution kernel, as described in [1].

Parameters:

gtab : GradientTable response : tuple or AxSymShResponse object A tuple with two elements. The first is the eigen-values as an (3,) ndarray and the second is the signal value for the response function without diffusion weighting. This is to be able to generate a single fiber synthetic signal. The response function will be used as deconvolution kernel ([1]) reg_sphere : Sphere (optional) sphere used to build the regularization B matrix. Default: ‘symmetric362’. sh_order : int (optional) maximal spherical harmonics order. Default: 8 lambda_ : float (optional) weight given to the constrained-positivity regularization part of the deconvolution equation (see [1]). Default: 1 tau : float (optional) threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 % of the mean fODF amplitude (here, 10% by default) (see [1]). Default: 0.1

References

[1]	(1, 2, 3, 4, 5, 6) Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution

[2]	(1, 2) Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions

[3]	(1, 2) C^ot’e, M-A., et al. Medical Image Analysis 2013. Tractometer: Towards validation of tractography pipelines

[4]	Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

fit(data, mask=None)

Fit method for every voxel in data

predict(sh_coeff, gtab=None, S0=1.0)

Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.

Parameters:	sh_coeff : ndarray The spherical harmonic representation of the FOD from which to make the signal prediction. gtab : GradientTable The gradients for which the signal will be predicted. Use the model’s gradient table by default. S0 : ndarray or float The non diffusion-weighted signal value.
Returns:	pred_sig : ndarray The predicted signal.

GradientTable

class dipy.reconst.benchmarks.bench_csd.GradientTable(gradients, big_delta=None, small_delta=None, b0_threshold=50)

Bases: object

Diffusion gradient information

Parameters:	gradients : array_like (N, 3) Diffusion gradients. The direction of each of these vectors corresponds to the b-vector, and the length corresponds to the b-value. b0_threshold : float Gradients with b-value less than or equal to b0_threshold are considered as b0s i.e. without diffusion weighting.

See also

gradient_table

Notes

The GradientTable object is immutable. Do NOT assign attributes. If you have your gradient table in a bval & bvec format, we recommend using the factory function gradient_table

Attributes:

gradients : (N,3) ndarray diffusion gradients bvals : (N,) ndarray The b-value, or magnitude, of each gradient direction. qvals: (N,) ndarray The q-value for each gradient direction. Needs big and small delta. bvecs : (N,3) ndarray The direction, represented as a unit vector, of each gradient. b0s_mask : (N,) ndarray Boolean array indicating which gradients have no diffusion weighting, ie b-value is close to 0. b0_threshold : float Gradients with b-value less than or equal to b0_threshold are considered to not have diffusion weighting.

Methods

b0s_mask
bvals
bvecs
gradient_strength
qvals
tau

__init__(gradients, big_delta=None, small_delta=None, b0_threshold=50)

Constructor for GradientTable class

b0s_mask()

bvals()

bvecs()

gradient_strength()

info

qvals()

tau()

bench_csdeconv

dipy.reconst.benchmarks.bench_csd.bench_csdeconv(center=(50, 40, 40), width=12)

num_grad

dipy.reconst.benchmarks.bench_csd.num_grad(gtab)

read_stanford_labels

dipy.reconst.benchmarks.bench_csd.read_stanford_labels()

Read stanford hardi data and label map

bench_local_maxima

dipy.reconst.benchmarks.bench_peaks.bench_local_maxima()

get_sphere

dipy.reconst.benchmarks.bench_peaks.get_sphere(name='symmetric362')

provide triangulated spheres

Parameters:	name : str which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’
Returns:	sphere : a dipy.core.sphere.Sphere class instance

Examples

>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name') 
Traceback (most recent call last):
    ...
DataError: No sphere called "not a sphere name"

local_maxima

dipy.reconst.benchmarks.bench_peaks.local_maxima()

Local maxima of a function evaluated on a discrete set of points.

If a function is evaluated on some set of points where each pair of neighboring points is an edge in edges, find the local maxima.

Parameters:	odf : array, 1d, dtype=double The function evaluated on a set of discrete points. edges : array (N, 2) The set of neighbor relations between the points. Every edge, ie edges[i, :], is a pair of neighboring points.
Returns:	peak_values : ndarray Value of odf at a maximum point. Peak values is sorted in descending order. peak_indices : ndarray Indices of maximum points. Sorted in the same order as peak_values so odf[peak_indices[i]] == peak_values[i].

See also

dipy.core.sphere

measure

dipy.reconst.benchmarks.bench_peaks.measure(code_str, times=1, label=None)

Return elapsed time for executing code in the namespace of the caller.

The supplied code string is compiled with the Python builtin compile. The precision of the timing is 10 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters:	code_str : str The code to be timed. times : int, optional The number of times the code is executed. Default is 1. The code is only compiled once. label : str, optional A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).
Returns:	elapsed : float Total elapsed time in seconds for executing code_str times times.

Examples

>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)',
...                            times=times)
>>> print("Time for a single execution : ", etime / times, "s")
Time for a single execution :  0.005 s

unique_edges

dipy.reconst.benchmarks.bench_peaks.unique_edges(faces, return_mapping=False)

Extract all unique edges from given triangular faces.

Parameters:	faces : (N, 3) ndarray Vertex indices forming triangular faces. return_mapping : bool If true, a mapping to the edges of each face is returned.
Returns:	edges : (N, 2) ndarray Unique edges. mapping : (N, 3) For each face, [x, y, z], a mapping to it’s edges [a, b, c]. y / / a/  / / /__________ x c z

bench_quick_squash

dipy.reconst.benchmarks.bench_squash.bench_quick_squash()

measure

dipy.reconst.benchmarks.bench_squash.measure(code_str, times=1, label=None)

Return elapsed time for executing code in the namespace of the caller.

The supplied code string is compiled with the Python builtin compile. The precision of the timing is 10 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters:	code_str : str The code to be timed. times : int, optional The number of times the code is executed. Default is 1. The code is only compiled once. label : str, optional A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).
Returns:	elapsed : float Total elapsed time in seconds for executing code_str times times.

Examples

>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)',
...                            times=times)
>>> print("Time for a single execution : ", etime / times, "s")
Time for a single execution :  0.005 s

ndindex

dipy.reconst.benchmarks.bench_squash.ndindex(shape)

An N-dimensional iterator object to index arrays.

Given the shape of an array, an ndindex instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned; the last dimension is iterated over first.

Parameters:	shape : tuple of ints The dimensions of the array.

Examples

>>> from dipy.core.ndindex import ndindex
>>> shape = (3, 2, 1)
>>> for index in ndindex(shape):
...     print(index)
(0, 0, 0)
(0, 1, 0)
(1, 0, 0)
(1, 1, 0)
(2, 0, 0)
(2, 1, 0)

old_squash

dipy.reconst.benchmarks.bench_squash.old_squash(arr, mask=None, fill=0)

Try and make a standard array from an object array

This function takes an object array and attempts to convert it to a more useful dtype. If array can be converted to a better dtype, Nones are replaced by fill. To make the behaviour of this function more clear, here are the most common cases:

1. arr is an array of scalars of type T. Returns an array like arr.astype(T)
2. arr is an array of arrays. All items in arr have the same shape S. Returns an array with shape arr.shape + S.
3. arr is an array of arrays of different shapes. Returns arr.
4. Items in arr are not ndarrys or scalars. Returns arr.

Parameters:	arr : array, dtype=object The array to be converted. mask : array, dtype=bool, optional Where arr has Nones. fill : number, optional Nones are replaced by fill.
Returns:	result : array

Examples

>>> arr = np.empty(3, dtype=object)
>>> arr.fill(2)
>>> old_squash(arr)
array([2, 2, 2])
>>> arr[0] = None
>>> old_squash(arr)
array([0, 2, 2])
>>> arr.fill(np.ones(2))
>>> r = old_squash(arr)
>>> r.shape == (3, 2)
True
>>> r.dtype
dtype('float64')

quick_squash

dipy.reconst.benchmarks.bench_squash.quick_squash()

Try and make a standard array from an object array

This function takes an object array and attempts to convert it to a more useful dtype. If array can be converted to a better dtype, Nones are replaced by fill. To make the behaviour of this function more clear, here are the most common cases:

1. obj_arr is an array of scalars of type T. Returns an array like obj_arr.astype(T)
2. obj_arr is an array of arrays. All items in obj_arr have the same shape S. Returns an array with shape obj_arr.shape + S
3. obj_arr is an array of arrays of different shapes. Returns obj_arr.
4. Items in obj_arr are not ndarrays or scalars. Returns obj_arr.

Parameters:	obj_arr : array, dtype=object The array to be converted. mask : array, dtype=bool, optional mask is nonzero where obj_arr has Nones. fill : number, optional Nones are replaced by fill.
Returns:	result : array

Examples

>>> arr = np.empty(3, dtype=object)
>>> arr.fill(2)
>>> quick_squash(arr)
array([2, 2, 2])
>>> arr[0] = None
>>> quick_squash(arr)
array([0, 2, 2])
>>> arr.fill(np.ones(2))
>>> r = quick_squash(arr)
>>> r.shape
(3, 2)
>>> r.dtype
dtype('float64')

reduce

dipy.reconst.benchmarks.bench_squash.reduce(function, sequence[, initial]) → value

Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty.

bench_vec_val_vect

dipy.reconst.benchmarks.bench_vec_val_sum.bench_vec_val_vect()

measure

dipy.reconst.benchmarks.bench_vec_val_sum.measure(code_str, times=1, label=None)

Return elapsed time for executing code in the namespace of the caller.

The supplied code string is compiled with the Python builtin compile. The precision of the timing is 10 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters:	code_str : str The code to be timed. times : int, optional The number of times the code is executed. Default is 1. The code is only compiled once. label : str, optional A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).
Returns:	elapsed : float Total elapsed time in seconds for executing code_str times times.

Examples

>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)',
...                            times=times)
>>> print("Time for a single execution : ", etime / times, "s")
Time for a single execution :  0.005 s

randn

dipy.reconst.benchmarks.bench_vec_val_sum.randn(d0, d1, ..., dn)

Return a sample (or samples) from the “standard normal” distribution.

If positive, int_like or int-convertible arguments are provided, randn generates an array of shape (d0, d1, ..., dn), filled with random floats sampled from a univariate “normal” (Gaussian) distribution of mean 0 and variance 1 (if any of the \(d_i\) are floats, they are first converted to integers by truncation). A single float randomly sampled from the distribution is returned if no argument is provided.

This is a convenience function. If you want an interface that takes a tuple as the first argument, use numpy.random.standard_normal instead.

Parameters:	d0, d1, …, dn : int, optional The dimensions of the returned array, should be all positive. If no argument is given a single Python float is returned.
Returns:	Z : ndarray or float A (d0, d1, ..., dn)-shaped array of floating-point samples from the standard normal distribution, or a single such float if no parameters were supplied.

See also

standard_normal

Similar, but takes a tuple as its argument.

Notes

For random samples from \(N(\mu, \sigma^2)\), use:

sigma * np.random.randn(...) + mu

Examples

>>> np.random.randn()
2.1923875335537315 #random

Two-by-four array of samples from N(3, 6.25):

>>> 2.5 * np.random.randn(2, 4) + 3
array([[-4.49401501,  4.00950034, -1.81814867,  7.29718677],  #random
       [ 0.39924804,  4.68456316,  4.99394529,  4.84057254]]) #random

vec_val_vect

dipy.reconst.benchmarks.bench_vec_val_sum.vec_val_vect()

Vectorize vecs.diag(vals).`vecs`.T for last 2 dimensions of vecs

Parameters:	vecs : shape (…, M, N) array containing tensor in last two dimensions; M, N usually equal to (3, 3) vals : shape (…, N) array diagonal values carried in last dimension, ... shape above must match that for vecs
Returns:	res : shape (…, M, M) array For all the dimensions ellided by ..., loops to get (M, N) vec matrix, and (N,) vals vector, and calculates vec.dot(np.diag(val).dot(vec.T).
Raises:	ValueError : non-matching ... dimensions of vecs, vals ValueError : non-matching N dimensions of vecs, vals

Examples

Make a 3D array where the first dimension is only 1

>>> vecs = np.arange(9).reshape((1, 3, 3))
>>> vals = np.arange(3).reshape((1, 3))
>>> vec_val_vect(vecs, vals)
array([[[   9.,   24.,   39.],
        [  24.,   66.,  108.],
        [  39.,  108.,  177.]]])

That’s the same as the 2D case (apart from the float casting):

>>> vecs = np.arange(9).reshape((3, 3))
>>> vals = np.arange(3)
>>> np.dot(vecs, np.dot(np.diag(vals), vecs.T))
array([[  9,  24,  39],
       [ 24,  66, 108],
       [ 39, 108, 177]])

with_einsum

dipy.reconst.benchmarks.bench_vec_val_sum.with_einsum(f)

Cache

class dipy.reconst.cache.Cache

Bases: object

Cache values based on a key object (such as a sphere or gradient table).

Notes

This class is meant to be used as a mix-in:

class MyModel(Model, Cache):
    pass

class MyModelFit(Fit):
    pass

Inside a method on the fit, typical usage would be:

def odf(sphere):
    M = self.model.cache_get('odf_basis_matrix', key=sphere)

    if M is None:
        M = self._compute_basis_matrix(sphere)
        self.model.cache_set('odf_basis_matrix', key=sphere, value=M)

Methods

cache_clear()	Clear the cache.
cache_get(tag, key[, default])	Retrieve a value from the cache.
cache_set(tag, key, value)	Store a value in the cache.

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

cache_clear()

Clear the cache.

cache_get(tag, key, default=None)

Retrieve a value from the cache.

Parameters:	tag : str Description of the cached value. key : object Key object used to look up the cached value. default : object Value to be returned if no cached entry is found.
Returns:	v : object Value from the cache associated with (tag, key). Returns default if no cached entry is found.

cache_set(tag, key, value)

Store a value in the cache.

Parameters:	tag : str Description of the cached value. key : object Key object used to look up the cached value. value : object Value stored in the cache for each unique combination of (tag, key).

Examples

>>> def compute_expensive_matrix(parameters):
...     # Imagine the following computation is very expensive
...     return (p**2 for p in parameters)

>>> c = Cache()

>>> parameters = (1, 2, 3)
>>> X1 = compute_expensive_matrix(parameters)

>>> c.cache_set('expensive_matrix', parameters, X1)
>>> X2 = c.cache_get('expensive_matrix', parameters)

>>> X1 is X2
True

auto_attr

dipy.reconst.cache.auto_attr(func)

Decorator to create OneTimeProperty attributes.

Parameters:	func : method The method that will be called the first time to compute a value. Afterwards, the method’s name will be a standard attribute holding the value of this computation.

Examples

>>> class MagicProp(object):
...     @auto_attr
...     def a(self):
...         return 99
...
>>> x = MagicProp()
>>> 'a' in x.__dict__
False
>>> x.a
99
>>> 'a' in x.__dict__
True

range

class dipy.reconst.cross_validation.range(stop) → range object

Bases: object

range(start, stop[, step]) -> range object

Return an object that produces a sequence of integers from start (inclusive) to stop (exclusive) by step. range(i, j) produces i, i+1, i+2, …, j-1. start defaults to 0, and stop is omitted! range(4) produces 0, 1, 2, 3. These are exactly the valid indices for a list of 4 elements. When step is given, it specifies the increment (or decrement).

Attributes:	start step stop

Methods

count(value)
index(value, [start, [stop]])	Raise ValueError if the value is not present.

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

count(value) → integer -- return number of occurrences of value

index(value[, start[, stop]]) → integer -- return index of value.

Raise ValueError if the value is not present.

start

step

stop

coeff_of_determination

dipy.reconst.cross_validation.coeff_of_determination(data, model, axis=-1)

Calculate the coefficient of determination for a model prediction, relative to data.

Parameters:	data : ndarray The data model : ndarray The predictions of a model for this data. Same shape as the data. axis: int, optional The axis along which different samples are laid out (default: -1).
Returns:	COD : ndarray The coefficient of determination. This has shape data.shape[:-1]

rac{SSE}{SSD})

where SSE is the sum of the squared error between the model and the data (sum of the squared residuals) and SSD is the sum of the squares of the deviations of the data from the mean of the data (variance * N).

kfold_xval

dipy.reconst.cross_validation.kfold_xval(model, data, folds, *model_args, **model_kwargs)

Perform k-fold cross-validation to generate out-of-sample predictions for each measurement.

Parameters:

model : Model class instance The type of the model to use for prediction. The corresponding Fit object must have a predict function implementd One of the following: reconst.dti.TensorModel or reconst.csdeconv.ConstrainedSphericalDeconvModel. data : ndarray Diffusion MRI data acquired with the GradientTable of the model. Shape will typically be (x, y, z, b) where xyz are spatial dimensions and b is the number of bvals/bvecs in the GradientTable. folds : int The number of divisions to apply to the data model_args : list Additional arguments to the model initialization model_kwargs : dict Additional key-word arguments to the model initialization. If contains the kwarg mask, this will be used as a key-word argument to the fit method of the model object, rather than being used in the initialization of the model object

Notes

This function assumes that a prediction API is implemented in the Model class for which prediction is conducted. That is, the Fit object that gets generated upon fitting the model needs to have a predict method, which receives a GradientTable class instance as input and produces a predicted signal as output.

It also assumes that the model object has bval and bvec attributes holding b-values and corresponding unit vectors.

References

[1]	Rokem, A., Chan, K.L. Yeatman, J.D., Pestilli, F., Mezer, A., Wandell, B.A., 2014. Evaluating the accuracy of diffusion models at multiple b-values with cross-validation. ISMRM 2014.

AxSymShResponse

class dipy.reconst.csdeconv.AxSymShResponse(S0, dwi_response, bvalue=None)

Bases: object

A simple wrapper for response functions represented using only axially symmetric, even spherical harmonic functions (ie, m == 0 and n even).

Methods

basis(sphere)	A basis that maps the response coefficients onto a sphere.
on_sphere(sphere)	Evaluates the response function on sphere.

__init__(S0, dwi_response, bvalue=None)

Initialize self. See help(type(self)) for accurate signature.

basis(sphere)

A basis that maps the response coefficients onto a sphere.

on_sphere(sphere)

Evaluates the response function on sphere.

ConstrainedSDTModel

class dipy.reconst.csdeconv.ConstrainedSDTModel(gtab, ratio, reg_sphere=None, sh_order=8, lambda_=1.0, tau=0.1)

Bases: dipy.reconst.shm.SphHarmModel

Methods

cache_clear()	Clear the cache.
cache_get(tag, key[, default])	Retrieve a value from the cache.
cache_set(tag, key, value)	Store a value in the cache.
fit(data[, mask])	Fit method for every voxel in data
sampling_matrix(sphere)	The matrix needed to sample ODFs from coefficients of the model.

__init__(gtab, ratio, reg_sphere=None, sh_order=8, lambda_=1.0, tau=0.1)

Spherical Deconvolution Transform (SDT) [1].

The SDT computes a fiber orientation distribution (FOD) as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution. The Constrained SDTModel is similar to the Constrained CSDModel but mathematically it deconvolves the q-ball ODF as oppposed to the HARDI signal (see [1] for a comparison and a through discussion).

A sharp fODF is obtained because a single fiber response function is injected as a priori knowledge. In the SDTModel, this response is a single fiber q-ball ODF as opposed to a single fiber signal function for the CSDModel. The response function will be used as deconvolution kernel.

Parameters:

gtab : GradientTable ratio : float ratio of the smallest vs the largest eigenvalue of the single prolate tensor response function reg_sphere : Sphere sphere used to build the regularization B matrix sh_order : int maximal spherical harmonics order lambda_ : float weight given to the constrained-positivity regularization part of the deconvolution equation tau : float threshold (tau *mean(fODF)) controlling the amplitude below which the corresponding fODF is assumed to be zero.

References

[1]	(1, 2, 3) Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions.

fit(data, mask=None)

Fit method for every voxel in data

ConstrainedSphericalDeconvModel

class dipy.reconst.csdeconv.ConstrainedSphericalDeconvModel(gtab, response, reg_sphere=None, sh_order=8, lambda_=1, tau=0.1)

Bases: dipy.reconst.shm.SphHarmModel

Methods

cache_clear()	Clear the cache.
cache_get(tag, key[, default])	Retrieve a value from the cache.
cache_set(tag, key, value)	Store a value in the cache.
fit(data[, mask])	Fit method for every voxel in data
predict(sh_coeff[, gtab, S0])	Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.
sampling_matrix(sphere)	The matrix needed to sample ODFs from coefficients of the model.

__init__(gtab, response, reg_sphere=None, sh_order=8, lambda_=1, tau=0.1)

Constrained Spherical Deconvolution (CSD) [1].

Spherical deconvolution computes a fiber orientation distribution (FOD), also called fiber ODF (fODF) [2], as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution that is the best object to be used for later deterministic and probabilistic tractography [3].

A sharp fODF is obtained because a single fiber response function is injected as a priori knowledge. The response function is often data-driven and is thus provided as input to the ConstrainedSphericalDeconvModel. It will be used as deconvolution kernel, as described in [1].

Parameters:

gtab : GradientTable response : tuple or AxSymShResponse object A tuple with two elements. The first is the eigen-values as an (3,) ndarray and the second is the signal value for the response function without diffusion weighting. This is to be able to generate a single fiber synthetic signal. The response function will be used as deconvolution kernel ([1]) reg_sphere : Sphere (optional) sphere used to build the regularization B matrix. Default: ‘symmetric362’. sh_order : int (optional) maximal spherical harmonics order. Default: 8 lambda_ : float (optional) weight given to the constrained-positivity regularization part of the deconvolution equation (see [1]). Default: 1 tau : float (optional) threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 % of the mean fODF amplitude (here, 10% by default) (see [1]). Default: 0.1

References

[1]	(1, 2, 3, 4, 5, 6) Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution

[2]	(1, 2) Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions

[3]	(1, 2) C^ot’e, M-A., et al. Medical Image Analysis 2013. Tractometer: Towards validation of tractography pipelines

[4]	Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

fit(data, mask=None)

Fit method for every voxel in data

predict(sh_coeff, gtab=None, S0=1.0)

Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.

Parameters:	sh_coeff : ndarray The spherical harmonic representation of the FOD from which to make the signal prediction. gtab : GradientTable The gradients for which the signal will be predicted. Use the model’s gradient table by default. S0 : ndarray or float The non diffusion-weighted signal value.
Returns:	pred_sig : ndarray The predicted signal.