decode.simulation package#

Submodules#

decode.simulation.background module#

class decode.simulation.background.Background(forward_return=None)[source]#

Bases: ABC

Parameters:

forward_return (Optional[str]) – determines the return of the forward function. ‘like’ returns a sample of the same size as the input, ‘cum’ adds the sample to the input and ‘tuple’ returns both the sum and the bg component alone.

forward(x)[source]#

Samples background in the same shape and on the same device as the input x. Depending on the ‘forward_return’ attribute the bg is

  • returned alone (‘like’)

  • added to the input (‘cum’)

  • is added and returned as tuple (‘tuple’)

Parameters:

x (Tensor) – input frames. Dimension \((N,C,H,W)\)

Returns:

(see above description)

abstract sample(size, device=device(type='cpu'))[source]#

Samples from background implementation in the specified size.

Parameters:

  • size (Size) – size of the sample

  • device – where to put the data

Return type:

Tensor

Returns:

background sample

sample_like(x)[source]#

Samples background in the shape and on the device as the the input.

Parameters:

x (Tensor) – input

Return type:

Tensor

Returns:

background sample

sanity_check()[source]#

Tests the sanity of the instance.

class decode.simulation.background.BgPerEmitterFromBgFrame(filter_size, xextent, yextent, img_shape)[source]#

Bases: object

Parameters:

  • filter_size (int) – size of the mean filter

  • xextent (tuple) – extent in x

  • yextent (tuple) – extent in y

  • img_shape (tuple) – image shape

forward(tar_em, tar_bg)[source]#
class decode.simulation.background.UniformBackground(bg_uniform=None, bg_sampler=None, forward_return=None)[source]#

Bases: Background

Adds spatially constant background.

Parameters:

  • bg_uniform (float or tuple of floats) – background value or background range. If tuple (bg range) the value will be sampled from a random uniform.

  • bg_sampler (function) – a custom bg sampler function that can take a sample_shape argument

static parse(param)[source]#
sample(size, device=device(type='cpu'))[source]#

Samples from background implementation in the specified size.

Parameters:

  • size – size of the sample

  • device – where to put the data

Returns:

background sample

decode.simulation.camera module#

class decode.simulation.camera.Camera[source]#

Bases: ABC

abstract backward(x, device=None)[source]#
Return type:

Tensor

abstract forward(x, device=None)[source]#
Return type:

Tensor

class decode.simulation.camera.PerfectCamera(device=None)[source]#

Bases: Photon2Camera

Convenience wrapper for perfect camera, i.e. only shot noise. By design in ‘photon units’.

Parameters:

device (Union[str, device, None]) – device for simulation

classmethod parse(param)[source]#
class decode.simulation.camera.Photon2Camera(*, qe, spur_noise, em_gain, e_per_adu, baseline, read_sigma, photon_units, device=None)[source]#

Bases: Camera

Parameters:

  • qe (float) – quantum efficiency :math:`0 … 1’

  • spur_noise (float) – spurious noise

  • em_gain (Optional[float]) – em gain

  • e_per_adu (float) – electrons per analog digital unit

  • baseline (float) – manufacturer baseline / offset

  • read_sigma (float) – readout sigma

  • photon_units (bool) – convert back to photon units

  • device (Union[str, device, None]) – device (cpu / cuda)

backward(x, device=None)[source]#

Calculates the expected number of photons from a noisy image.

Parameters:

  • x (Tensor) –

  • device (Union[str, device, None]) –

Return type:

Tensor

Returns:

forward(x, device=None)[source]#

Forwards frame through camera

Parameters:

  • x (Tensor) – camera frame of dimension *, H, W

  • device (Union[str, device, None]) – device for forward

Return type:

Tensor

Returns:

torch.Tensor

classmethod parse(param)[source]#
class decode.simulation.camera.SCMOS(qe, spur_noise, em_gain, e_per_adu, baseline, read_sigma, photon_units, sample_mode, device=None)[source]#

Bases: Photon2Camera

Parameters:

  • qe – quantum efficiency :math:`0 … 1’

  • spur_noise – spurious noise

  • em_gain – em gain

  • e_per_adu – electrons per analog digital unit

  • baseline – manufacturer baseline / offset

  • read_sigma – readout sigma

  • photon_units – convert back to photon units

  • device – device (cpu / cuda)

check_sanity()[source]#
forward(x, device=None)[source]#

Forwards model input image ‘x’ through camera.

Parameters:

  • x (Tensor) – model image

  • device (Union[str, device, None]) –

Return type:

Tensor

Returns:

Sampled noisy image

forward_on_sampled_sensor_window(x, device=None)[source]#

Forwards model input image ‘x’ through camera where x is possibly smaller than the camera sensor. A random window on the sensor is sampled and returned as second return argument.

Parameters:

  • x (Tensor) – model image

  • device (Union[str, device, None]) –

Return type:

(Tensor, Tensor)

Returns:

Sampled noisy image Sampled camera window(s)

sample_sensor_window(size_nxy)[source]#

Samples a random window from the sensor and returns the corresponding readout noise values

Parameters:

size_nxy (tuple) – number of samples and window size, i.e. tuple of len 3, where (N, H, W)

Return type:

Tensor

Returns:

read-out noise window samples

decode.simulation.emitter_generator module#

class decode.simulation.emitter_generator.EmitterPopperMultiFrame(*args, **kwargs)[source]#

Bases: object

class decode.simulation.emitter_generator.EmitterPopperSingle(*args, **kwargs)[source]#

Bases: object

class decode.simulation.emitter_generator.EmitterSampler(structure, xy_unit, px_size)[source]#

Bases: ABC

Abstract emitter sampler. All implementations / childs must implement a sample method.

abstract sample()[source]#
Return type:

EmitterSet

class decode.simulation.emitter_generator.EmitterSamplerBlinking(*, structure, intensity_mu_sig, lifetime, frame_range, xy_unit, px_size, density=None, em_avg=None, intensity_th=None)[source]#

Bases: EmitterSamplerFrameIndependent

Parameters:

  • structure (StructurePrior) –

  • intensity_mu_sig (tuple) –

  • lifetime (float) –

  • xy_unit (str) –

  • px_size (tuple) –

  • frame_range (tuple) – specifies the frame range

  • density –

  • em_avg –

  • intensity_th –

property num_frames#
classmethod parse(param, structure, frames)[source]#
sample()[source]#

Return sampled EmitterSet in the specified frame range.

Returns:

EmitterSet

sample_loose_emitter(n)[source]#

Generate loose EmitterSet. Loose emitters are emitters that are not yet binned to frames.

Parameters:

n – number of ‘loose’ emitters

Return type:

LooseEmitterSet

Returns:

LooseEmitterSet

sample_n(*args, **kwargs)[source]#

Sample ‘n’ emitters, i.e. the number of emitters is given and is not sampled from the Poisson dist.

Parameters:

n – number of emitters

t0_dist#

Determine the total number of emitters. Depends on lifetime, frames and emitters. (lifetime + 1) because of binning effect.

class decode.simulation.emitter_generator.EmitterSamplerFrameIndependent(*, structure, photon_range, density=None, em_avg=None, xy_unit, px_size)[source]#

Bases: EmitterSampler

Parameters:

  • structure (StructurePrior) – structure to sample from

  • photon_range (tuple) – range of photon value to sample from (uniformly)

  • density (Optional[float]) – target emitter density (exactly only when em_avg is None)

  • em_avg (Optional[float]) – target emitter average (exactly only when density is None)

  • xy_unit (str) – emitter xy unit

  • px_size (tuple) – emitter pixel size

property em_avg: float#
photon_range#

Sanity Checks. U shall not pa(rse)! (Emitter Average and Density at the same time!

sample()[source]#

Sample an EmitterSet.

Return type:

EmitterSet

sample_n(n)[source]#

Sample ‘n’ emitters, i.e. the number of emitters is given and is not sampled from the Poisson dist.

Parameters:

n (int) – number of emitters

Return type:

EmitterSet

decode.simulation.noise_distributions module#

class decode.simulation.noise_distributions.Gamma(scale)[source]#

Bases: NoiseDistribution

Parameters:

scale (float) – 1 / rate of the Gamma distribution

forward(x)[source]#

Samples the noise distribution based on the input x.

Parameters:

x – input

Returns:

noisy sample

class decode.simulation.noise_distributions.Gaussian(sigma)[source]#

Bases: NoiseDistribution

Parameters:

sigma ((float, Tensor)) – standard deviation fo the gaussian

forward(x)[source]#

Samples the noise distribution based on the input x.

Parameters:

x – input

Returns:

noisy sample

class decode.simulation.noise_distributions.NoiseDistribution[source]#

Bases: ABC

Abstract noise.

abstract forward(x)[source]#

Samples the noise distribution based on the input x.

Parameters:

x (Tensor) – input

Return type:

Tensor

Returns:

noisy sample

class decode.simulation.noise_distributions.Poisson[source]#

Bases: NoiseDistribution

Poisson noise. ‘Non-parametric’ with respect initialisation since the only parameter (lambda) comes from the input in the forward method itself.

forward(x)[source]#

Samples the noise distribution based on the input x.

Parameters:

x – input

Returns:

noisy sample

class decode.simulation.noise_distributions.ZeroNoise[source]#

Bases: NoiseDistribution

The No-Noise noise.

forward(x)[source]#

Samples the noise distribution based on the input x.

Parameters:

x – input

Returns:

noisy sample

decode.simulation.psf_kernel module#

class decode.simulation.psf_kernel.CubicSplinePSF(xextent, yextent, img_shape, ref0, coeff, vx_size, *, roi_size=None, ref_re=None, roi_auto_center=False, device='cuda:0', max_roi_chunk=500000)[source]#

Bases: PSF

Initialise Spline PSF

Parameters:

  • ref_re –

  • xextent (tuple) – extent in x

  • yextent (tuple) – extent in y

  • img_shape (tuple) – img_shape

  • coeff – spline coefficients

  • ref0 (tuple) – zero reference point in implementation units

  • vx_size (tuple) – pixel / voxel size

  • roi_size (tuple, None, optional) – roi_size. optional. can be determined from dimension of coefficients.

  • device – specify the device for the implementation to run on. Must be like (‘cpu’, ‘cuda’, ‘cuda:1’)

  • max_roi_chunk (int) – max number of rois to be processed at a time via the cuda kernel. If you run into memory allocation errors, decrease this number or free some space on your CUDA device.

coord2impl(xyz)[source]#

Transforms nanometre coordinates to implementation coordiantes

Parameters:

xyz – (torch.Tensor)

Returns:

cpu()[source]#

Returns a copy of this object with implementation in CPU code. If already on CPU, return original object.

Returns:

CubicSplinePSF instance

crlb(xyz, phot, bg, inversion=None)[source]#

Computes the Cramer-Rao bound. Outputs ROIs additionally (since its computationally free of charge).

Parameters:

  • xyz (Tensor) –

  • phot (Tensor) –

  • bg (Tensor) –

  • inversion – (function) overwrite default inversion with another function that can batch(!) invert matrices. The last two dimensions are the the to be inverted dimensions. Dimension of fisher matrix: N x H x W where N is the batch dimension.

Returns:

Cramer-Rao-Lower Bound. Dimension N x N_par rois (torch.Tensor): ROIs with background added. Dimension N x H x W

Return type:

crlb (torch.Tensor)

crlb_sq(xyz, phot, bg, inversion=None)[source]#

Function for the lazy ones to compute the sqrt Cramer-Rao bound. Outputs ROIs additionally (since its computationally free of charge).

Parameters:

  • xyz (Tensor) –

  • phot (Tensor) –

  • bg (Tensor) –

  • inversion – (function) overwrite default inversion with another function that can batch invert matrices

Returns:

Cramer-Rao-Lower Bound. Dimension N x N_par rois (torch.Tensor): ROIs with background added. Dimension N x H x W

Return type:

crlb (torch.Tensor)

cuda(ix=0)[source]#

Returns a copy of this object with implementation in CUDA. If already on CUDA and selected device, return original object.

Parameters:

ix (int) – device index

Returns:

CubicSplinePSF instance

property cuda_compiled: bool#

Returns true if (1) a CUDA capable device is available and (2) spline was compiled with CUDA support. Technically (1) could come without (2).

static cuda_is_available()[source]#

This is a dummy method to check whether CUDA is available without the need to init the class. I wonder whether Python has ‘static properties’?

Return type:

bool

derivative(xyz, phot, bg, add_bg=True)[source]#

Computes the px wise derivative per ROI. Outputs ROIs additionally (since its computationally free of charge). The coordinates are (as the forward_rois method) relative to the reference of the PSF; i.e. when working in px units, adding 1 in x or y direction does not change anything.

Parameters:

  • xyz (Tensor) –

  • phot (Tensor) –

  • bg (Tensor) –

  • add_bg (bool) – add background value in ROI calculation

Returns:

derivatives in correct units. Dimension N x N_par x H x W rois (torch.Tensor): ROIs. Dimension N x H x W

Return type:

derivatives (torch.Tensor)

fisher(xyz, phot, bg)[source]#

Calculates the fisher matrix ROI wise. Outputs ROIs additionally (since its computationally free of charge).

Parameters:

  • xyz (Tensor) –

  • phot (Tensor) –

  • bg (Tensor) –

Returns:

Fisher Matrix. Dimension N x N_par x N_par rois (torch.Tensor): ROIs with background added. Dimension N x H x W

Return type:

fisher (torch.Tensor)

forward(xyz, weight, frame_ix=None, ix_low=None, ix_high=None)[source]#

Forward coordinates frame index aware through the psf model.

Parameters:

  • xyz (Tensor) – coordinates of size N x (2 or 3)

  • weight (Tensor) – photon value

  • frame_ix (Optional[Tensor]) – (optional) frame index

  • ix_low (Optional[int]) – (optional) lower frame_index, if None will be determined automatically

  • ix_high (Optional[int]) – (optional) upper frame_index, if None will be determined automatically

Returns:

(torch.Tensor)

Return type:

frames

forward_rois(xyz, phot)[source]#

Computes a ROI per position. The emitter is always centred as by the reference of the PSF; i.e. when working in px units, adding 1 in x or y direction does not change anything.

Parameters:

  • xyz – coordinates relative to the ROI centre.

  • phot – photon count

Returns:

torch.Tensor with size N x roi_x x roi_y where N is the number of emitters / coordinates

and roi_x/y the respective ROI size

frame2roi_coord(xyz_nm)[source]#

Computes ROI wise coordinate from the coordinate on the frame and returns the px on the frame in addition

Parameters:

xyz_nm (Tensor) –

Returns:

roi-wise relative coordinates onframe_ix: ix where to place the roi on the final frame (caution: might be negative when roi is outside frame, but then we don’t mean negative in pythonic sense)

Return type:

xyz_r

inv_default()#

inverse(input, *, out=None) -> Tensor

Alias for torch.linalg.inv()

n_par = 5#
sanity_check()[source]#

Perform some class specific safety checks Returns:

class decode.simulation.psf_kernel.DeltaPSF(xextent, yextent, img_shape)[source]#

Bases: PSF

Constructor to comprise a couple of default attributes

Parameters:

  • xextent –

  • yextent –

  • zextent –

  • img_shape –

property bin_ctr_x#

Read only bin_ctr_x

property bin_ctr_y#

Read only bin_ctr_y

forward(xyz, weight=None, frame_ix=None, ix_low=None, ix_high=None)[source]#

Forward coordinates frame index aware through the psf model.

Parameters:

  • xyz (Tensor) – coordinates of size N x (2 or 3)

  • weight (Optional[Tensor]) – photon value

  • frame_ix (Optional[Tensor]) – (optional) frame index

  • ix_low – (optional) lower frame_index, if None will be determined automatically

  • ix_high – (optional) upper frame_index, if None will be determined automatically

Returns:

frames of size N x H x W where N is the batch dimension.

Return type:

frames (torch.Tensor)

search_bin_index(xy, raise_outside=True)[source]#

Returns the index of the bin in question, x ix and y ix. Make sure items are actually fit in the bins (i.e. filter outside ones before) or handle those items later on.

Parameters:

  • xy (Tensor) – xy coordinates

  • raise_outside (bool) – raise error if anything is outside of the specified bins; otherwise those coordinate’s indices are -1 and len(bin) which means outside of the bin’s range.

class decode.simulation.psf_kernel.GaussianPSF(xextent, yextent, zextent, img_shape, sigma_0, peak_weight=False)[source]#

Bases: PSF

Init of Gaussian Expect. If no z extent is provided we assume 2D PSF.

Parameters:

  • xextent (Tuple[float, float]) – (tuple of float) extent of psf in x

  • yextent – (tuple of float) extent of psf in y

  • zextent – (tuple of float or None, optional) extent of psf in z

  • img_shape – (tuple) img shape

  • sigma_0 – sigma in focus in px

  • peak_weight – (bool) if true: use peak intensity instead of integral under the curve

static astigmatism(z, sigma_0=1.0, foc_shift=250, rl_range=280.0)[source]#

Computes width of gaussian dependent on the z value as by the Gaussian Beam model.

Parameters:

  • z – (torch.Tensor, N) z values

  • sigma_0 – initial sigma in px units

  • foc_shift – focal shift upon introduction of cylindrical lens in nm

  • rl_range – rayleigh range in nm

Returns:

sigma values for x and y

forward(xyz, weight, frame_ix=None, ix_low=None, ix_high=None)[source]#

Forward coordinates frame index aware through the psf model.

Parameters:

  • xyz (Tensor) – coordinates of size N x (2 or 3)

  • weight (Tensor) – photon value

  • frame_ix (Optional[Tensor]) – (optional) frame index

  • ix_low – (optional) lower frame_index, if None will be determined automatically

  • ix_high – (optional) upper frame_index, if None will be determined automatically

Returns:

frames of size N x H x W where N is the batch dimension.

Return type:

frames (torch.Tensor)

class decode.simulation.psf_kernel.PSF(xextent=(None, None), yextent=(None, None), zextent=None, img_shape=(None, None))[source]#

Bases: ABC

Constructor to comprise a couple of default attributes

Parameters:

  • xextent –

  • yextent –

  • zextent –

  • img_shape –

crlb(*args, **kwargs)[source]#
abstract forward(xyz, weight, frame_ix, ix_low, ix_high)[source]#

Forward coordinates frame index aware through the psf model. Implementation methods should call this method first in order not to handle the default argument stuff.

Example::

If implementation do not implement a batched forward method, they may call this method, and then refer to the single-frame wrapper as. Their forward implementation will then look like this:

>>> xyz, weight, frame_ix, ix_low, ix_high = super().forward(xyz, weight, frame_ix, ix_low, ix_high)
>>> return self._forward_single_frame_wrapper(xyz, weight, frame_ix, ix_low, ix_high)
Parameters:

  • xyz (Tensor) – coordinates of size N x (2 or 3)

  • weight (Tensor) – photon values of size N or None

  • frame_ix (Tensor) – (optional) frame index

  • ix_low (int) – (optional) lower frame_index, if None will be determined automatically

  • ix_high (int) – (optional) upper frame_index, if None will be determined automatically

Returns:

frames of size N x H x W where N is the batch dimension.

Return type:

frames (torch.Tensor)

decode.simulation.simulator module#

class decode.simulation.simulator.Simulation(psf, em_sampler=None, background=None, noise=None, frame_range=None)[source]#

Bases: object

Init Simulation.

Parameters:

  • psf (PSF) – point spread function instance

  • em_sampler – callable that returns an EmitterSet upon call

  • background – background instance

  • noise – noise instance

  • frame_range (Optional[Tuple[int, int]]) – limit frames to static range

forward(em, ix_low=None, ix_high=None)[source]#

Forward an EmitterSet through the simulation pipeline. Setting ix_low or ix_high overwrites the frame range specified in the init.

Parameters:

  • em (EmitterSet) – Emitter Set

  • ix_low (Optional[int]) – lower frame index

  • ix_high (Optional[int]) – upper frame index (inclusive)

Returns:

simulated frames torch.Tensor: background frames (e.g. to predict the bg seperately)

Return type:

torch.Tensor

sample()[source]#

Sample a new set of emitters and forward them through the simulation pipeline.

Returns:

sampled emitters torch.Tensor: simulated frames torch.Tensor: background frames

Return type:

EmitterSet

decode.simulation.structure_prior module#

class decode.simulation.structure_prior.RandomStructure(xextent, yextent, zextent)[source]#

Bases: StructurePrior

Parameters:

  • xextent (Tuple[float, float]) – extent in x

  • yextent (Tuple[float, float]) – extent in y

  • zextent (Tuple[float, float]) – extent in z, set (0., 0.) for a 2D structure

Example

The following initialises this class in a range of 32 x 32 px in x and y and +/- 750nm in z. >>> prior_struct = RandomStructure(xextent=(-0.5, 31.5), yextent=(-0.5, 31.5), zextent=(-750., 750.))

property area: float#

Calculate the area which is occupied by the structure. This is useful to later calculate the density, and the effective number of emitters). This is the 2D projection. Not the volume.

classmethod parse(param)[source]#
sample(n)[source]#

Sample n samples from structure.

Parameters:

n (int) – number of samples

Return type:

Tensor

class decode.simulation.structure_prior.StructurePrior[source]#

Bases: ABC

Abstract structure which can be sampled from. All implementation / childs must define a ‘pop’ method and an area property that describes the area the structure occupies.

abstract property area: float#

Calculate the area which is occupied by the structure. This is useful to later calculate the density, and the effective number of emitters). This is the 2D projection. Not the volume.

abstract sample(n)[source]#

Sample n samples from structure.

Parameters:

n (int) – number of samples

Return type:

Tensor

Module contents#