PYME.Deconv.dec module

class PYME.Deconv.dec.ClassicMappingFFTW

Bases: DeconvMappingBase

Classical deconvolution with a stationary PSF using FFTW for convolutions

Afunc(f)

Forward transform - convolve with the PSF

Ahfunc(f)

Conjugate transform - convolve with conj. PSF

Lfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

Lhfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

prep()

Allocate memory and compute FFTW plans etc (this is separate from psf_calc as an aid to distributing Deconvolution objects for parallel processing - psf_calc gets called before Deconv objects are passed, prep gets called when the deconvolution is run.

psf_calc(psf, data_size)

Precalculate the OTF etc…

class PYME.Deconv.dec.ClassicMappingNP

Bases: DeconvMappingBase

Classical deconvolution with a stationary PSF - uses numpy FTTs rather than FFTW

Afunc(f)

Forward transform - convolve with the PSF

Ahfunc(f)

Conjugate transform - convolve with conj. PSF

Lfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

Lhfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

psf_calc(psf, data_size)

Precalculate the OTF etc…

class PYME.Deconv.dec.DeconvMappingBase

Bases: object

Base class for different types of deconvolution. Ultimate deconvolution classes will inherit from both this and a a method class (e.g. ICTM Deconvolution)

Provides implementations of the following:

AFunc - the forward mapping (computes Af) AHFunc - conjugate transpose of forward mapping (computes ar{A}^T f) LFunc - the likelihood function LHFunc - conj. transpose of likelihood function

Also, defines:

psf_calc - does any pre-computation to get the PSF into a usable form prep - allocate memory / setup FFTW plans etc …

Afunc(f)

The forward mapping

Ahfunc(f)

The conjugate transpose of the forward mapping

Lfunc(f)

The likelihood function (ICTM deconvolution only)

Lhfunc(f)

The gonjugate transpose of likelihood function (ICTM deconvolution only)

prep()

Allocate memory and compute FFTW plans etc (this is separate from psf_calc as an aid to distributing Deconvolution objects for parallel processing - psf_calc gets called before Deconv objects are passed, prep gets called when the deconvolution is run.

psf_calc(psf, data_size)

do any pre-computation on the PSF. e.g. resizing to match the data shape and/or pre-calculating and storing the OTF

class PYME.Deconv.dec.ICTMDeconvolution

Bases: object

Base deconvolution class, implementing a variant of the ICTM algorithm. ie. find f such that:

||Af-d||^2 + lamb^2||L(f - fdef)||^2

is minimised

Note that this is nominally for Gaussian distributed noise, although can be adapted by adding a weighting to the misfit term.

Derived classed should additionally define the following methods: AFunc - the forward mapping (computes Af) AHFunc - conjugate transpose of forward mapping (computes ar{A}^T f) LFunc - the likelihood function LHFunc - conj. transpose of likelihood function

see dec_conv for an implementation of conventional image deconvolution with a measured, spatially invariant PSF

deconv(data, lamb, num_iters=10, weights=1, alpha=None, bg=0, pos=True)

This is what you actually call to do the deconvolution. parameters are:

data - the raw data lamb - the regularisation parameter num_iters - number of iterations (note that the convergence is fast when

compared to many algorithms - e.g Richardson-Lucy - and the default of 10 will usually already give a reasonable result)

weights - a weighting on the residuals to deweight missing data and/or adjust the

noise behaviour

alpha - PSF phase - hacked in for variable phase 4Pi deconvolution, should

really be refactored out into the dec_4pi classes.

bg - Dummy variable pos - Flag to turn positivity constraints on/off

deconvp(args)

convenience function for deconvolving in parallel using processing.Pool.map

sim_pic(data, alpha)

Do the forward transform to simulate a picture. Currently with 4Pi cruft.

startGuess(data)

starting guess for deconvolution - can be overridden in derived classes but the data itself is usually a pretty good guess.

subsearch(f0, res, fdef, Afunc, Lfunc, lam, S)

minimise in subspace - this is the bit which gets called on each iteration to work out what the next step is going to be. See Inverse Problems text for details.

class PYME.Deconv.dec.SpatialConvolutionMapping

Bases: DeconvMappingBase

Classical deconvolution using non-fft convolution - pot. faster for v. small psfs. Note that PSF must be symetric

Afunc(f)

Forward transform - convolve with the PSF

Ahfunc(f)

Conjugate transform - convolve with conj. PSF

Lfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

Lhfunc(f)

convolve with an approximate 2nd derivative likelihood operator in 3D. i.e. [[[0,0,0][0,1,0][0,0,0]],[[0,1,0][1,-6,1][0,1,0]],[[0,0,0][0,1,0][0,0,0]]]

psf_calc(psf, data_size)

do any pre-computation on the PSF. e.g. resizing to match the data shape and/or pre-calculating and storing the OTF

class PYME.Deconv.dec.dec_4pi

Bases: ICTMDeconvolution

Variable phase 4Pi deconvolution, as descibed in Baddeley et al, Applied Optics 2006.

NOTE: this is a translation of Matlab code, without extensive testing, and without maintenance in over 10 years. I’m not sure it is 100% correct or working. Use at your own risk.

Usage:

dec = dec_4pi() dec.psf_calc(psf, kz, data_size=data.shape) result = dec.deconv(data, lamb, num_iters, weights, alpha)

where:

psf - the corresponding confocal/widefield PSF without 4Pi axial modulation. Must be the same size (shape) as the data. kz - the axial wavenumber of the 4Pi illumination in voxels. This should be the wavelength/(refractive index * axial step size) data - the raw data lamb - the ICTM regularisation parameter. See ICTMDeconvolution for details. Around 0.1 is a good starting point,

vary on a log scale - i.e. 10^-1, 10^-2 etc …

num_iters - number of iterations. 20 is a reasonably good starting point. weights - a weighting on the residuals to deweight missing data and/or adjust the noise behavior (see ICTMDeconvolution).

Using the default of 1.0 is usually fine.

alpha - the phase of the 4Pi illumination. This is the magic parameter, specific to variable phase deconvolution. It should

be an array of the same dimensions as the data, containing a pixel-wise map of phase values in radians. In the original paper, these were calculated by fitting axial PSF profiles to areas in the data where there was a high chance that the underlying object was sparse (e.g. a bead or a piece of membrane parallel to the coverslip), and interpolating these to the entire 3D volume. The code to do this was written in Matlab and might be lost to time. Without fitting profiles and interpolating, you can sometimes get reasonable results by eye-balling the phase and assuming a linear variation with z, although this is not recommended for anything but exploratory use.

NOTE: Vicidomini et al, Optics Letters, 2009 describe an extension of the concept which uses a joint estimation of both the phase and the underlying object, avoiding the need to supply alpha. In principle this should be preferable, but I have no first-hand experience of how reliable it is. Keeping phase estimation separate from deconvolution might have it’s advantages in some special cases (I could imagine, e.g., that a double membrane at roughly the peak-sidelobe distance could be problematic for the joint estimation approach).

NOTE: Some of the 4PI specific logic (specifically the pre-calculation of the phase exponentials self.e1 and self.e2) lives in the base ICTMDeconvolution class. This is a historic artifact (all the deconvolution code was originally written for the 4Pi project and has since been generalised). This, along with setting alpha, should be refactored into this class.

NOTE: This should really be refactored as a on top of DeconvMappingBase to enable use with Richardson-Lucy deconvolution as well as ICTM, which should be preferable for a microscope noise model.

Afunc(f)

Ahfunc(f)

Lfunc(f)

Lhfunc(f)

psf_calc(psf, kz, data_size)

Pre calculate OTFs etc …

class PYME.Deconv.dec.dec_4pi_c

Bases: dec_4pi

Afunc(f)

Ahfunc(f)

Lfunc(f)

Lhfunc(f)

cleanup()

prepare()

class PYME.Deconv.dec.dec_bead(*args, **kwargs)

Bases: ICTMDeconvolution, SpatialConvolutionMapping

class PYME.Deconv.dec.dec_conv(*args, **kwargs)

Bases: ICTMDeconvolution, ClassicMappingFFTW

class PYME.Deconv.dec.dec_conv_slow(*args, **kwargs)

Bases: ICTMDeconvolution, ClassicMappingNP