API Documentation

svt.SVT	Singular value thresholding for denoising image sequences.
svt.mixed_noise_model	Add Poisson-Gaussian noise to the data X.
hspy.HSPYSVT	HyperSpy wrapper for SVT.

class pguresvt.svt.SVT(trajectory_length=15, patch_size=4, patch_overlap=1, motion_estimation=True, motion_window=7, motion_filter=5, optimize_pgure=True, lambda1=None, exponential_weighting=True, noise_method=4, noise_alpha=None, noise_mu=None, noise_sigma=None, tol=1e-07, max_iter=500, n_jobs=None, random_seed=None)

Bases: object

Singular value thresholding for denoising image sequences.

PGURE-SVT is an algorithm designed to denoise image sequences acquired in microscopy. It exploits the correlations between consecutive frames to form low-rank matrices, which are then recovered using a technique known as nuclear norm minimization. An unbiased risk estimator for mixed Poisson-Gaussian noise is used to automate the selection of the regularization parameter, while robust noise and motion estimation maintain broad applicability to many different types of microscopy.

For more information, see T. Furnival, R. K. Leary and P. A. Midgley, “Denoising time-resolved microscopy sequences with singular value thresholding”, Ultramicroscopy, vol. 178, pp. 112–124, 2017. DOI: 10.1016/j.ultramic.2016.05.005.

Parameters

• trajectory_length (int, default=15) – Length in frames of the block to form a Casorati matrix. Must be odd.

• patch_size (int, default=4) – The dimensions of the patch in pixels to form a Casorati matrix.

• patch_overlap (int, default=1) – The dimensions of the patch in pixels to form a Casorati matrix.

• motion_window (int, default=7) – Size of neighbourhood in pixels for ARPS motion estimation search. Must be odd.

• motion_filter (int or None, default=5) – Size of median filter in pixels used to improve motion estimation search. If None, no median filtering is performed.

• optimize_pgure (bool, default=True) – Whether to optimize PGURE or just denoise according to given threshold, lambda1.

• lambda1 (float or None, default=None) –

  If optimize_pgure=False:

  Singular value threshold value to use for the entire image sequence. Must be a positive float.

  If optimize_pgure=True:

  Used as the initial guess for the optimization of the singular value threshold. If None, a heuristic is used for the guess instead.

• exponential_weighting (bool, default=True) –

  If True:

  Applies exponential weighting to the singular values of the Casorati matrix, such that smaller singular values are thresholded more than larger values.

  If False:

  Applies a constant threshold to all singular values.

• noise_method (int, default=4) – Method for estimating Poisson-Gaussian noise parameters. Currently undocumented.

• noise_alpha (float or None, default=None) – Level of noise gain. If None, then parameter is estimated online. Ignored if optimize_pgure=False.

• noise_mu (float or None, default=None) – Level of noise offset. If None, then parameter is estimated online. Ignored if optimize_pgure=False.

• noise_sigma (float or None, default=None) – Level of Gaussian noise. If None, then parameter is estimated online. Ignored if optimize_pgure=False.

• tol (float, default=1e-7) – Stopping tolerance of PGURE optimization algorithm. Ignored if optimize_pgure=False.

• max_iter (int, default=500) – Maximum iterations of PGURE optimization algorithm. Ignored if optimize_pgure=False.

• n_jobs (int or None, default=None) – The number of threads to use. A value of None means using all threads dependent on the available hardware.

• random_seed (int or None, default=None) – Random seed used when optimizing PGURE. Ignored if optimize_pgure=False.

Y_

The denoised image sequence.

Type

np.ndarray, shape (nx, ny, nt)

lambda1s_

The singular value threshold applied to each frame. If optimize_pgure=True, these are the optimized values.

Type

np.ndarray, shape (nt,)

noise_alphas_

Level of noise gain for each frame.

Type

np.ndarray, shape (nt,)

noise_mus_

Level of noise offset for each frame.

Type

np.ndarray, shape (nt,)

noise_sigmas_

Level of Gaussian noise for each frame.

Type

np.ndarray, shape (nt,)

denoise(X)

Denoise the data X.

Parameters

X (np.ndarray, shape (nx, ny, nt)) – The image sequence to be denoised.

Returns

self – Returns the instance itself.

Return type

object

pguresvt.svt.mixed_noise_model(X, alpha=1.0, mu=0.0, sigma=0.0, random_state=None)

Add Poisson-Gaussian noise to the data X.

Noise is generated according to the following mixed noise model:

\[\begin{split}\mathbf{Y}=\alpha\mathbf{Z}+\mathbf{E}\;\textrm{ with }\; \begin{cases} \mathbf{Z}\thicksim\mathcal{P}\left(\frac{\mathbf{X}^{0}}{\alpha}\right)\\ \mathbf{E}\thicksim\mathcal{N}\left(\mu,\sigma^{2}\right) \end{cases}\end{split}\]

where alpha is the detector gain, mu is the detector offset, and sigma is the (Gaussian) detector noise.

Parameters

• X (np.ndarray) – The data to be corrupted.

• alpha (float, default=1.0) – Level of noise gain. Should be in range [0, 1].

• mu (float, default=0.0) – Level of noise offset.

• sigma (float, default=0.0) – Level of Gaussian noise. Should be >= 0.0.

• random_state (None or int or RandomState instance, default=None) – Random seed used to generate the noise.

Returns

Y – The corrupted data, with the same shape as X.

Return type

np.ndarray

class pguresvt.hspy.HSPYSVT(*args, **kwargs)

Bases: pguresvt.svt.SVT

HyperSpy wrapper for SVT.

Allows arbitrary HyperSpy signals to be passed for SVT denoising.

denoise(signal)

Denoises an arbitrary HyperSpy signal.

Parameters

signal (hyperspy.signals.BaseSignal) – The HyperSpy signal to denoise; can be of arbitrary type/shape.

Returns

Denoised data as a signal.

Return type

hyperspy.signals.BaseSignal