Classes¶
Linear Operator¶
-
class
talon.core.
AbstractLinearOperator
(*args, **kwargs)[source]¶ Abstract class for all linear operators
This abstract class defines the interface that all linear operators in talon must implement.
-
property
T
¶ Returns the transpose of the linear operator.
-
convert_x
(x)[source]¶ Converts x so that it can be used on the right of a dot product.
This method converts x so that it has the right dimensions and type to be used as a right operand of a dot product with a linear operator. That is, it asserts that A @ x will work. Raises exceptions if the input cannot be converted to the correct format.
- Parameters
x – The vector to test.
- Returns
A numpy array that can be used in the dot product.
- Return type
x
- Raises
TypeError – If x is not a numpy array.
ValueError – If the length of x does not match the number of columns of the linear operator.
-
abstract property
data_mask
¶ Returns the mask to apply to the data to keep only the entries covered by the linear operator.
-
property
dtype
¶ Returns the data type of the linear operator
-
abstract property
shape
¶ Returns the shape of the matrix.
-
abstract property
todense
¶ Returns a dense matrix representation of the linear operator.
-
abstract property
transpose
¶ Returns the transpose of the linear operator.
-
property
CPU¶
-
class
talon.core.
LinearOperator
(*args, **kwargs)[source]¶ -
__init__
(generators, indices_of_generators, weights)[source]¶ Linear operator that maps tractography to signal space. The linear operator can be used to compute products with a vector.
- 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.
- Raises
TypeError – If generators is not a numpy ndarray of float.
TypeError – If indices_of_generators is not a COO scipy matrix.
TypeError – If weights is not a COO scipy matrix of float64.
ValueError – If weights does not have the same dimension as indices_of_generators.
-
property
columns
¶ Returns the indices of the nonzero columns.
- Type
int
-
property
data_mask
¶ Returns the mask to apply to the data to keep only the entries covered by the linear operator.
-
property
generator_length
¶ length of each generator (constant across generators).
- Type
int
-
property
generators
¶ Returns the generators of the linear operator.
- Type
np.ndarray
-
property
indices
¶ Returns the generator indices.
- Type
np.ndarray
-
property
nb_atoms
¶ Number of atoms (columns) in the linear operator.
- Type
int
-
property
nb_data
¶ Number of data points.
- Type
int
-
property
nb_generators
¶ Number of generators.
- Type
int
-
property
rows
¶ Returns the indices of the nonzero rows.
- Type
int
-
property
shape
¶ Shape of the linear operator.
The shape is given by the number of rows and columns of the linear operator. The number of rows is equal to the number of data points times the length of the generators. The number of columns is equal to the number of atoms.
- Type
tuple of int
-
todense
()[source]¶ Return the dense matrix associated to the linear operator.
Note
The output of this method can be very memory heavy to store. Use at your own risk.
- Returns
full matrix representing the linear operator.
- Return type
ndarray
-
property
transpose
¶ the transpose of the linear operator.
- Type
_TransposedLinearOperator
-
property
weights
¶ The weights of the nonzero elements
- Type
np.ndarray
-
-
class
talon.fast.
LinearOperator
(*args, **kwargs)[source]¶ -
__init__
(generators, indices_of_generators, weights)[source]¶ A LinearOperator that computes products quickly.
The FastLinearOperator class implements a linear operator optimized to compute matrix-vector products quickly. It is single threaded and written in pure Python, which makes it a good default choice for linear operators.
- 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.
- Raises
TypeError – If generators is not a numpy ndarray of float64.
TypeError – If indices_of_generators is not a COO scipy matrix.
TypeError – If weights is not a COO scipy matrix of float64.
ValueError – if weights does not have the same dimension as indices_of_generators.
ValueError – if weights and indices_of_generators don’t have the same sparsity pattern.
-
property
transpose
¶ Returns the transpose of the linear operator.
-
-
class
talon.core.
ConcatenatedLinearOperator
(*args, **kwargs)[source]¶ -
__init__
(operators, axis)[source]¶ Concatenated LinearOperator object
The ConcatenatedLinearOperator class implements the vertical or horizontal concatenation of LinearOperator objects.
- 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)
- Raises
TypeError – If any element of operator is not an instance of LinearOperator or ConcatenatedLinearOperator.
TypeError – If operators is not a list or a tuple.
ValueError – If axis is not 0 or 1.
ValueError – If operators is an empty list or tuple.
ValueError – If the operators do not have compatible dimensions.
-
property
axis
¶ axis in which the concatenation was performed.
- Type
int
-
property
data_mask
¶ Returns the mask to apply to the data to keep only the entries covered by the linear operator.
-
property
operators
¶ list of concatenated operators.
- Type
list
-
property
shape
¶ Shape of the concatenated linear operator.
- Type
tuple of int
-
todense
()[source]¶ Return the dense matrix associated to the linear operator.
Note
The output of this method can be very memory heavy to store. Use at your own risk.
- Returns
full matrix representing the linear operator.
- Return type
ndarray
-
property
transpose
¶ transpose of the linear operator.
- Type
TransposedConcatenatedLinearOperator
-
GPU¶
-
class
talon.opencl.
LinearOperator
(*args, **kwargs)[source]¶ -
__init__
(generators, indices_of_generators, weights, chunk_size=100000000)[source]¶ Linear operator implemented with OpenCL
A linear operator that has a sparse vector structure. The product between this operator and a vector is implemented using OpenCL.
- 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.
chunk_size – The product is computed by splitting the linear operator into chunks. This parameter determines the approximate chunk size. Reducing this value reduces the amount of memory required on the device.
- Raises
TypeError – If generators is not a numpy array of float.
TypeError – If indices_of_generators is not a COO scipy matrix.
TypeError – If weights is not a COO scipy matrix of float64.
ValueError – If weights does not have the same dimension as indices_of_generators.
ValueError – If weights and indices_of_generators don’t have the same sparsity pattern.
-
property
dtype
¶ Returns the data type of the linear operator
-
todense
() → numpy.ndarray[source]¶ Return the dense matrix associated with the linear operator.
Note
The output of this method can be very memory heavy to store. Use at your own risk.
- Returns
Full matrix representing the linear operator.
-
property
transpose
¶ transpose of the linear operator.
- Type
TransposedFastLinearOperator
-
Regularization Term¶
-
class
talon.optimization.
RegularizationTerm
(regularization_parameter: float)[source]¶ -
__init__
(regularization_parameter: float)[source]¶ Abstract base class for all regularization terms
The optimization problem solved by talon is
\[\min_x 0.5 \|A x - y\|^2 + \Omega(x)\]where \(\Omega\) is a regularization term. This class is the base for all concrete implementations of this term.
- Parameters
regularization_parameter – float The scaling factor of the regularization term. Must be a float greater or equal to zero.
- Raises
TypeError – If the regularization parameter is not a float and cannot be converted to a float.
ValueError – If the regularization parameter is negative.
-
property
groups
¶ Get the group structure associated to the regularization term.
- Returns: list
List of lists of streamline indices.
-
property
non_negativity
¶ Get the activation of the non-negativity constraint.
- Returns: bool
True if the non-negativity constraint is employed, False otherwise.
-
property
regularization_parameter
¶ Get the regularization parameter.
- Returns: float
The value of the regularization parameter.
-
property
weights
¶ Get the weight associated to each group.
- Returns: np.ndarray
1-dimensional numpy array with one weight per group.
-
-
class
talon.optimization.
StructuredSparsity
(regularization_parameter: float, groups: list, weights: numpy.ndarray)[source]¶ -
__init__
(regularization_parameter: float, groups: list, weights: numpy.ndarray)[source]¶ Instantiates the structured sparsity regularization term.
\[\Omega(x) = \lambda \cdot \sum_{g\in G}w_g\cdot \|x_g\|_2\]- Parameters
regularization_parameter – float Value of the regularization parameter.
groups – list List of lists of streamline indices.
weights – np.ndarray 1-dimensional numpy array with one weight per group.
-
-
class
talon.optimization.
NonNegativeStructuredSparsity
(regularization_parameter, groups, weights)[source]¶ -
__init__
(regularization_parameter, groups, weights)[source]¶ Instantiates the non-negative structured sparsity regularization term.
\[\Omega(x) = \iota_{\ge 0}(x) + \lambda \cdot \sum_{g\in G}w_g\cdot \|x_g\|_2\]- Parameters
regularization_parameter – float Value of the regularization parameter.
groups – list List of lists of streamline indices.
weights – np.ndarray 1-dimensional numpy array with one weight per group.
-