Regularizers

class mumott.optimization.regularizers.Laplacian

Regularizes using the Laplacian of the coefficients. Suitable for orthonormal representations, e.g., spherical harmonics.

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the regularization norm and possibly the gradient based on the provided coefficients. The norm is the 2-norm of the discrete nearest-neighbour Laplacian.

This is in effect a smoothing kernel that enforces continuity between the tensors of neighbouring voxels. The calculation is most suitable for orthonormal representations. If the representation is in spherical harmonics, the norm corresponds to maximimzing the covariance between neighbours.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise, the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for the zonal harmonics (ZH) reconstructions to determine what part of the gradient is being calculated. Default is None. If a flag is passed in ('full', 'angles', 'coefficients'), we assume that the ZH workflow is used and that the last two coefficients are Euler angles, which should not be regularized by this regularizer.

Return type

dict[str, ndarray[Any, dtype[float]]]

Returns

A dictionary with two entries, regularization_norm and gradient.

class mumott.optimization.regularizers.TotalVariation(delta=0.01)

Regularizes using the symmetric total variation, i.e., the root-mean-square difference between nearest neighbours. It is combined with a Huber norm, using the squared differences at small values, in order to improve convergence. Suitable for scalar fields or tensor fields in local representations. Tends to reduce noise.

In two dimensions, the total variation spliced with its squared function like a Huber loss can be written

\[\begin{split}\mathrm{TV}_1(f(x, y)) = \frac{1}{h}\sum_i ((f(x_i, y_i) - f(x_i + h, y_i))^2 + (f(x_i, y_i) - f(x_i - h, y_i))^2 + \\ (f(x_i, y_i) - f(x_i, y_i + h))^2 + (f(x_i, y_i) - f(x_i, y_i - h))^2))^{\frac{1}{2}} - 0.5 \delta\end{split}\]

If \(\mathrm{TV}_1 < 0.5 \delta\) we instead use

\[\begin{split}\mathrm{TV}_2(f(x, y)) = \frac{1}{2 \delta h^2}\sum_i (f(x_i, y_i) - f(x_i + h, y_i))^2 + (f(x_i, y_i) - f(x_i - h, y_i))^2 + \\ (f(x_i, y_i) - f(x_i, y_i + h))^2 + (f(x_i, y_i) - f(x_i, y_i - h))^2\end{split}\]

See also the Wikipedia articles on total variation denoising and Huber loss

Parameters

delta (float) – Below this value, the scaled square of the total variation is used as the norm. This makes the norm differentiable everywhere, and can improve convergence. If :attr`delta` is None, the standard total variation will be used everywhere, and the gradient will be 0 at the singular point where the norm is 0.

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the isotropic total variation, i.e., the symmetric root-mean-square difference between nearest neighbours.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise, the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for the zonal harmonics (ZH) reconstructions to determine what part of the gradient is being calculated. Default is None. If a flag is passed in ('full', 'angles', 'coefficients'), we assume that the ZH workflow is used and that the last two coefficients are Euler angles, which should not be regularized by this regularizer.

Return type

dict[str, ndarray[Any, dtype[float]]]

Returns

A dictionary with two entries, regularization_norm and gradient.

class mumott.optimization.regularizers.L1Norm

Regularizes using the \(L_1\) norm of the coefficient vector, also known as the Manhattan or taxicab norm. Suitable for scalar fields or tensor fields in local representations. Tends to reduce noise.

The \(L_1\) norm of a vector \(x\) is given by \(\sum{\vert x \vert}\).

See also this Wikipedia article.

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the \(L_1\) norm, also called the Manhattan or taxicab norm, of the coefficients. Appropriate for use with scalar fields or tensor fields in local basis sets.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for the zonal harmonics resonstructions to determine what part of the gradient is being calculated. Default is None. If a flag is passed in (‘full’, ‘angles’, ‘coefficients’), we assume that the ZH workflow is used and that the last two coefficients are euler angles, which should not be regularized by this regularizer.

Return type

dict[str, ndarray[Any, dtype[float]]]

Returns

A dictionary with two entries, regularization_norm and gradient.

class mumott.optimization.regularizers.L2Norm

Regularizes using the \(L_2\) norm of the coefficient vector, also known as the Euclidean norm. Suitable for most representations, including non-local ones. Tends to reduce large values, and often leads to fast convergence.

The \(L_2\) norm of a vector \(x\) is given by \(\sum{\vert x \vert^2}\).

See also the Wikipedia article on the Euclidean norm

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the \(L_2\) norm, of the coefficient vector. Appropriate for use with scalar coefficients or local basis sets.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise, the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for the zonal harmonics (ZH) reconstructions to determine what part of the gradient is being calculated. Default is None. If a flag is passed in ('full', 'angles', 'coefficients'), we assume that the ZH workflow is used and that the last two coefficients are Euler angles, which should not be regularized by this regularizer.

Return type

dict[str, ndarray[Any, dtype[float]]]

Returns

A dictionary with two entries, regularization_norm and gradient.

class mumott.optimization.regularizers.HuberNorm(delta=1.0)

Regularizes using the Huber norm of the coefficient, which splices the :math`L_1` and \(L_2\) norms. Suitable for scalar fields or tensor fields in local representations. Tends to reduce noise while converging more easily than the \(L_1\) loss function.

The Huber norm of a vector \(x\) is given by \(R(\vec{x}) = \sum_i L(x_i)\), where \(L(x_i)\) is given by

\[\begin{split}L(x_i) = \begin{Bmatrix}\vert x_i \vert - 0.5 \delta & \quad \text{if } \vert x_i \vert > \delta \\ \dfrac{x^2}{2 \delta} & \quad \text{if } \vert x_i \vert \leq \delta\end{Bmatrix}\end{split}\]

See also the Wikipedia article on the Huber loss.

Parameters

delta (float) – The threshold value for the Huber norm. Must be greater than 0. Default value is 1., but the appropriate value is data-dependent.

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the Huber loss of the coefficients. Appropriate for use with scalar fields or tensor fields in local representations.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise, the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for the zonal harmonics resonstructions to determine what part of the gradient is being calculated. Default is None. If a flag is passed in (‘full’, ‘angles’, ‘coefficients’), we assume that the ZH workflow is used and that the last two coefficients are euler angles, which should not be regularized by this regularizer.

Return type

dict[str, ndarray[Any, dtype[float]]]

Returns

A dictionary with two entries, regularization_norm and gradient.

class mumott.optimization.regularizers.GroupLasso(regularization_parameter=1, step_size_parameter=None)

Group lasso regularizer, where the coefficients are grouped by voxel. This approach is well suited for handling voxels with zero scattering and for suppressing missing wedge artifacts. Note that this type of regularization (\(L_1\)) has convergence issues when using gradient-based optimizers due to the divergence of the derivative of the \(L_1\)-norm at zero. This is why one commonly uses proximal operators for optimization.

\[L(\mathrm{c}) = \sum_{xyz} \sqrt(\sum_{i}c_{xyzi}^2)\]

Parameters

• regularization_parameter (float) – Regularization weight used to define the proximal operator. Can be left as 1 (default) for the normal mumott workflow.

• step_size_parameter (float) – Step-size parameter used to define the proximal operator.

get_regularization_norm(coefficients, get_gradient=False, gradient_part=None)

Retrieves the group lasso regularization weight of the coefficients.

Parameters

• coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

• get_gradient (bool) – If True, returns a 'gradient' of the same shape as coefficients. Otherwise, the entry 'gradient' will be None. Defaults to False.

• gradient_part (Optional[str]) – Used for reconstructions with zonal harmonics (ZHs) to determine what part of the gradient is being calculated. Default is None. If one of the flag in ('full', 'angles', 'coefficients') is passed, we assume that the ZH workflow is used and that the last two coefficients are Euler angles, which should not be regularized by this regularizer.

Return type

float

Returns

A dictionary with two entries, regularization_norm and gradient.

proximal_operator(coefficients)

Proximal operator of the group lasso regularizer.

Parameters

coefficients (ndarray[Any, dtype[float]]) – An np.ndarray of values, with shape (X, Y, Z, W), where the last channel contains, e.g., tensor components.

Returns

Input coefficients vector after the application of the proximal operator.

Return type

stepped_coefficient