Functions

talon.concatenate(operators, axis=0)

Concatenate a sequence of linear operator along axis 0 or 1.

This method defines the object that acts as the concatenation of the linear operators contained in the list/tuple operators along the chosen axis. The syntax is consistent with the one of np.concatenate.

Parameters

• operators – list or tuple of LinearOperator objects to be concatenated in the same axis.

• axis – int direction in which we want to concatenate the LinearOperator or ConcatenatedLinearOperator objects that we want to concatenate. Vertical concatenation is obtained for axis = 0 and horizontal concatenation is obtained for axis = 1 as in np.concatenate. (Default: 0)

Returns

the concatenated linear

operator.

Return type

talon.core.ConcatenatedLinearOperator

talon.diagonalize(mask)

Returns the matrices used to create a linear operator from a mask

This functions transforms a volume mask into the weights and indices components that are necessary to build a linear operator. It is assumed that the all the voxels in the mask will share a common generator. The indexed generator is therefore unique, corresponds to index zero, and is weighted by the value contained in the mask at the specific voxel.

Parameters

mask – np.ndarray with three dimensions that contains the weight to be associated to each voxel. Only voxels with non-zero weight are considered.

Returns

tuple of length 2 containing

• index_sparsediagonal scipy.sparse matrix with a shape of (n, m)

  where n is the number of voxels of the volume and m in the number of voxels of the mask.

• weight_sparsediagonal scipy.sparse matrix with a shape of (n, m)

  containing the value of the mask at each non-zero voxel in the same fashion as index_sparse.

Raises

• TypeError – If the the mask is not a numpy.ndarray.

• ValueError – If the mask does not have three dimensions.

talon.operator(generators, indices_of_generators, weights, operator_type='fast')

Create a LinearOperator object.

This method defines the object that describes the linear operator by means of its fundamental components. These components are a set of generators, a table that encodes the non-zero entries of the operator and indexes the proper generator in each entry and another table that encodes the weight applied to each called generator in the linear operator.

Each block of entries of the linear operator A is given by

\[A[k\cdot i\dots k\cdot(i+1), j] = g_{T_{i,j}} \cdot w_{i,j}\]

where k is the length of the generators, T is the table of indices and w is the table of weights.

Parameters

• generators – np.array where each row is a generator.

• indices_of_generators – COO sparse matrix that tells which generator is called where in the linear operator.

• weights – COO sparse matrix that encodes the weight applied to each generator indexed by indices_of_generators. It has the same dimension as indices_of_generators.

• operator_type (optional) – string Operator type to use. Accepted values are 'fast', 'opencl', and 'reference'. The latter is intended to be used only for testing purposes. (default = fast).

Returns

the wanted linear operator.

Return type

talon.core.LinearOperator

Raises

ValueError – If reference_type is not 'fast' or 'reference'.

talon.regularization(non_negativity=False, regularization_parameter=None, groups=None, weights=None)

Get regularization term for the optimization problem.

By default this method returns an object encoding the regularization term

\[\Omega(x) = 0 .\]

If regularization_parameter, groups and weights are all not None it returns the structured sparsity regularization.

\[\Omega(x) = \lambda \sum_{g\in G} w_g \|x_g\|_2\]

where \(\lambda\) is regularization_parameter, \(w_g\) is the entry of w associated to g, \(x_g\) is the subset of entries of x encoded by the indices of g and G is the list of groups.

If non_negativity is True it adds the non-negativity constraint to the regularization term.

\[\Omega(x) \leftarrow \Omega(x) + \iota_{\ge 0}(x) .\]

Parameters

• non_negativity – boolean (default = False)

• regularization_parameter – float. Must be >= 0 (default = None)

• groups –

  list of lists where each element encodes the indices of the streamlines belonging to a single group. (default = None).

  E.g.: groups = [[0,2,5], [1,3,4,6], [7,8,9]].

• weights – ndarray of the same length as groups. Weight associated to each group. (default = None)

Returns

instance of one between

• talon.optimize.NoRegularization;

• talon.optimize.NonNegativity;

• talon.optimize.StructuredSparsity;

• talon.optimize.NonNegativeStructuredSparsity.

Raises

• ValueError – If weights and groups do not have the same length.

• ValueError – If regularization_parameter < 0 .

talon.solve(linear_operator: talon.core.LinearOperator, data: numpy.ndarray, reg_term: Optional[talon.optimization.RegularizationTerm] = None, cost_reltol: float = 1e-06, x_abstol: float = 1e-06, max_nit: int = 1000, x0: Optional[numpy.ndarray] = None, verbose: str = 'LOW') → scipy.optimize.optimize.OptimizeResult

Fit the solution.

This routine finds the x that solves the problem

\[\min_x 0.5 \|A x - y\|^2 + \Omega(x)\]

where x is the vector of coefficients to be retrieved, A is the linear operator, y is the data vector and \(\Omega\) is defined as in talon.regularization.

Parameters

• linear_operator – linear operator endowed with the @ operation.

• data – ndarray of data to be fit. First dimension must be compatible with the second of linear_operator.

• reg_term – regularization term defined by talon.regularization. (default: \(\Omega(x) = 0.0\))

• cost_reltol – float relative tolerance on the cost (default = 1e-6).

• x_abstol – float mean abs tolerance on the variable (default = 1e-6).

• max_nit – int maximum number of iterations (default = 1000).

• x0 – ndarray starting value for the optimization. The length must be the equal to the second dimension of linear_operator. (default=zeros)

• verbose – {‘NONE’, ‘LOW’, ‘HIGH’, ‘ALL’} The log level : 'NONE' for no log, 'LOW' for resume at convergence, 'HIGH' for info at all solving steps, 'ALL' for all possible outputs, including at each steps of the proximal operators computation (default=’LOW’).

Returns

dictionary with the following fields

• x : estimated minimizer of the cost function.

• status : attribute of talon.optimization.ExitStatus enumeration.

• message : string that explains the reason for termination.

• fun : evaluation of each term at the minimizer.

• nit : number of performed iterations.

• reg_param: value of the regularization parameter.

Return type

scipy.optimize.OptimizeResult

talon.voxelize(streamlines, vertices, image_shape, step=0.04)

Transform a tractogram into the matrices that are necessary to build a linear operator.

Parameters

• streamlines – list of streamlines in voxel space. The coordinates of each voxel are assumed to point at the center of the voxel itself.

• vertices – Nx3 np.array, vertices of an unit sphere in which we sample the streamlines direction.

• image_shape – tuple, final shape of the mask image.

• step – double, streamlines interpolation step.

Returns

tuple of length 2 containing

• index_sparse(voxel x streamlines) scipy.sparse matrix containing

  for each voxel and fiber the index of the vertices that it is closest to the streamline direction in that voxel.

• length_sparse(voxel x streamlines) scipy.sparse matrix containing

  for each voxel and fiber the length of the streamline in that voxel.

Raises

ValueError – If the streamlines are not in voxel space.

talon.zeros(shape: Tuple[int, int], dtype: type = <class 'numpy.float64'>) → talon.core.LinearOperator

Create a zero filled linear operator

Returns a zero filled talon linear operator. Useful in combination with talon.concatenate.

Parameters

• shape – The shape of the linear operator.

• dtype (optional) – The datatype of the linear operator.

Returns

A talon linear operator filled with zeros.

talon.utils.check_pattern_iw(indices_of_generators: scipy.sparse.coo.coo_matrix, weights: scipy.sparse.coo.coo_matrix) → None

Check if the sparsity pattern of the indices and the weights are the same.

This function performs a complete check on the sparsity pattern of the indices_of_generators and the weights matrices. If the two matrices have a different number of non-empty entries or the non-empty entries are in different locations, it raises an error.

If the two matrices came out of talon.voxelization, this check is not necessary.

Note

This function is very expensive in terms of memory and time.

Parameters

• indices_of_generators – sp.coo_matrix of the indices.

• weights – sp.coo_matrix of the weights.

Raises

ValueError – If weights and indices_of_generators don’t have the same sparsity pattern.

talon.utils.concatenate_giw(giws: Iterable, axis: int = 0) → tuple

Concatenates generators, indices, and weights along an existing axis

The indices and weights are concatenated along the supplied axis and the generators along axis 1. The generators must have the same number of columns. The indices and weights must have the same shape, except in the dimension corresponding to axis.

Parameters

• giws – An iterable of (generator, indices, weights) to concatenate e.g. [(g1, i1, w1), (g2, i2, w2)].

• axis – The axis along which the indices and weights will be joined. Default is 0.

Returns

The concatenated generators, indices, and weights.

talon.utils.directions(number_of_points: int = 180) → numpy.ndarray

Get a list of 3D vectors representing the directions of the fibonacci covering of a hemisphere of radius 1 computed with the golden spiral method. The \(z\) coordinate of the points is always strictly positive.

Parameters

number_of_points – number of points of the wanted covering (default=180)

Returns

number_of_points x 3 array with the cartesian coordinates

of a point of the covering in each row.

Return type

ndarray

Raises

ValueError – if number_of_points <= 0 .

References

https://stackoverflow.com/questions/9600801/evenly-distributing-n-points-on-a-sphere/44164075#44164075

talon.utils.mask_data(data: numpy.ndarray, linear_operator: talon.core.LinearOperator) → numpy.ndarray

Mask the data using the mask that covers only the entries that are affected by the linear operator. This prevents numerical errors in the solution of the optimization problem.

Parameters

• data – np.ndarray one dimensional array that contains the data to mask.

• linear_operator – LinearOperator object that contains the self.data_mask attribute to be used as a mask.

Returns

np.ndarray with the same dimension as data where the entries corresponding to the False entries of the mask have been set to zero.