skprox.operators._tvl1

Module Contents

Classes

TVL1	Common interface for proximal operators of a function.

Functions

_prox_tvl1(input_img[, l1_ratio, weight, dgap_tol, ...])	Compute the TV-L1 proximal (ie total-variation +l1 denoising) on 3d images.
_gradient_id(img[, l1_ratio])	Compute gradient + id of an image.
_div_id(grad[, l1_ratio])	Compute divergence + id of image gradient + id.

class skprox.operators._tvl1.TVL1(sigma, shape=None, l1_ratio=0.05, dgap_tol=5e-05, x_tol=0.01, max_iter=200, check_gap_frequency=10)

Bases: pyproximal.ProxOperator

Common interface for proximal operators of a function.

This class defines the overarching structure of any proximal operator. It contains two main methods, prox and dualprox which are both implemented by means of the Moreau decomposition assuming explicit knowledge of the other method. For this reason any proximal operators that subclasses the ProxOperator class needs at least one of these two methods to be implemented directly.

Note

End users of PyProx should not use this class directly but simply use operators that are already implemented. This class is meant for developers and it has to be used as the parent class of any new operator developed within PyProx. Find more details regarding implementation of new operators at addingoperator.

Parameters

Oppylops.LinearOperator, optional

Linear operator used by the Proximal operator

hasgradbool, optional

Flag to indicate if the function is differentiable, i.e., has a uniquely defined gradient (True) or not (False).

Notes

The proximal operator of a function f is defined as:

\[prox_{\tau f} (\mathbf{x}) = \argmin_{\mathbf{y}} f(\mathbf{y}) + \frac{1}{2 \tau}||\mathbf{y} - \mathbf{x}||^2_2\]

unmask(x)

mask(x)

prox(x, tau, **kwargs)

Proximal operator applied to a vector

The proximal operator can always be computed given its dual proximal operator using the Moreau decomposition as defined in pyprox.moreau(). For this reason we can easily create a common method for all proximal operators that can be evaluated provided the dual proximal is implemented.

However, direct implementations are generally available. This can be done by simply implementing prox for a specific proximal operator, which will overwrite the general method.

Parameters

xnp.ndarray

Vector

taufloat

Positive scalar weight

__call__(x)

skprox.operators._tvl1._prox_tvl1(input_img, l1_ratio=0.05, weight=50, dgap_tol=5e-05, x_tol=None, max_iter=200, check_gap_frequency=4, fista=True, init=None)

Compute the TV-L1 proximal (ie total-variation +l1 denoising) on 3d images.

Find the argmin res of

1/2 * ||im - res||^2 + weight * TVl1(res),

Parameters

input_imgndarray of floats (2-d or 3-d)

Input data to be denoised. im can be of any numeric type, but it is cast into an ndarray of floats for the computation of the denoised image.

weightfloat, optional

Denoising weight. The greater weight, the more denoising (at the expense of fidelity to input)

dgap_tolfloat, optional

Precision required. The distance to the exact solution is computed by the dual gap of the optimization problem and rescaled by the squared l2 norm of the image (for contrast invariance).

x_tolfloat or None, optional

The maximal relative difference between input and output. If specified, this specifies a stopping criterion on x, rather than the dual gap.

max_iterint, optional

Maximal number of iterations used for the optimization.

val_minNone or float, optional

An optional lower bound constraint on the reconstructed image.

val_maxNone or float, optional

An optional upper bound constraint on the reconstructed image.

verbosebool, optional

If True, print the dual gap of the optimization

fistabool, optional

If True, uses a FISTA loop to perform the optimization. if False, uses an ISTA loop.

callbackcallable

Callable that takes the local variables at each steps. Useful for tracking.

initarray of shape as im

Starting point for the optimization.

check_gap_frequencyint, optional (default 4)

Frequency at which duality gap is checked for convergence.

Returns

outndarray

TV-l1-denoised image.

Notes

The principle of total variation denoising is explained in http://en.wikipedia.org/wiki/Total_variation_denoising

The principle of total variation denoising is to minimize the total variation of the image, which can be roughly described as the integral of the norm of the image gradient. Total variation denoising tends to produce “cartoon-like” images, that is, piecewise-constant images.

This function implements the FISTA (Fast Iterative Shrinkage Thresholding Algorithm) algorithm of Beck et Teboulle, adapted to total variation denoising in “Fast gradient-based algorithms for constrained total variation image denoising and deblurring problems” (2009).

For details on implementing the bound constraints, read the aforementioned Beck and Teboulle paper.

skprox.operators._tvl1._gradient_id(img, l1_ratio=0.5)

Compute gradient + id of an image.

Parameters

imgndarray, shape (nx, ny, nz, …)

N-dimensional image

l1_ratiofloat in the interval [0, 1]; optional (default .5)

Constant that mixes L1 and spatial prior terms in the penalization.

Returns

gradientndarray, shape (4, nx, ny, nz, …).

Spatial gradient of the image: the i-th component along the first axis is the gradient along the i-th axis of the original array img.

Raises

RuntimeError

skprox.operators._tvl1._div_id(grad, l1_ratio=0.5)

Compute divergence + id of image gradient + id.

Parameters

gradndarray, shape (4, nx, ny, nz, …)

where img_shape is the shape of the brain bounding box, and n_axes = len(img_shape).

l1_ratiofloat in the interval [0, 1]; optional (default .5)

Constant that mixes L1 and spatial prior terms in the penalization.

Returns

resndarray, shape (nx, ny, nz, …)

The computed divergence + id operator.

Raises

RuntimeError