PSF definition#

This module provides functions fitting a 2D point spread function (PSF) to a thumbnail. By default, only the position and amplitude (contrast) are fitted. For efficient fitting, the PSF is evaluated on a grid and the fitting is done using a lookup table.

The module is designed, to enable compilation with numba, caching and parallelisation.

class massphoto.psf_fitting.PSF2D(psf_fun=None, psf_params=None, psf_experimental=None, psf_size=None, cache_divider=None, cache_interpolate=None)[source]#

Bases: object

A class to represent a 2D point spread function (PSF) with custom or default parameters. Provides methods to get the PSF thumbnail, fit function, and lookup function. Currently just a wrapper around the psf_2d function and get_lookup_fun which has to be a static method for compilation, caching, and parallelisation.

Note

Available as both massphoto.PSF2D and massphoto.psf_fitting.PSF2D.

Parameters:

psf_fun (Callable | ndarray | None)
psf_params (dict | None)
psf_experimental (ndarray | None)
psf_size (int | None)
cache_divider (int | None)
cache_interpolate (bool | None)

get_thumbnail(thumbnail_size=None)[source]#

Parameters:: thumbnail_size (int | None)
Return type:: ndarray

get_lookup_and_fitfun()[source]#

Return type:: tuple[Callable, Callable]

property fitfun: Callable#

property lookupfun: Callable#

get_fitfun()[source]#

Return type:: Callable

get_lookupfun()[source]#

Return type:: Callable

massphoto.psf_fitting.estimate_psf(data, max_freq=True, image_mask=True, image_mask_blur=1.0, subtract_image_mean=True, subtract_otf_background=True, psf_size=None, return_otf=False, centre_psf=False)[source]#

Estimate the Point Spread Function (PSF) of an image by calculating the Optical Transfer Function (OTF) and applying an inverse Fourier Transform.

Parameters:

data (np.ndarray) – The input image data.
max_freq (float | bool, optional) – The radius of the circular mask used to filter the OTF. If True, the maximum frequency is estimated automatically. Defaults to True.
image_mask (bool, optional) – Whether to apply an image mask to the data. Defaults to True.
image_mask_blur (float, optional) – The standard deviation of the Gaussian blur applied to the image mask. Defaults to 1.0.
subtract_image_mean (bool, optional) – Whether to subtract the mean of the data. Defaults to True.
subtract_otf_background (bool | float, optional) – Whether to subtract the background from the OTF. If True, the background is estimated using the mask. If a float, it is used as the background value. Defaults to True.
psf_size (int | None, optional) – The size of the returned PSF. If specified, the PSF will be cropped to this size. Defaults to None.
return_otf (bool, optional) – Whether to return the Optical Transfer Function (OTF) instead of the PSF. Defaults to False.
centre_psf (bool, optional) – Whether to centre the PSF by taking the absolute value of the OTF. Note: this removes phase information and may introduce unwanted symmetry. Defaults to False.

Returns:

The estimated PSF or OTF. np.ndarray: (optional) If return_otf is True, the estimated OTF is returned as well.

Return type:

np.ndarray

massphoto.psf_fitting.frc_profile(fft_img, threshold=0.5, min_frequency=0.1)[source]#

Calculate the radial profile of a given FFT image.

Parameters:

fft_img (np.ndarray) – The input FFT image. Expects the center of the image to be the center of the FFT.
threshold (float, optional) – The threshold value for determining the resolution. Defaults to 0.5.
min_frequency (float, optional) – The minimum frequency value. Defaults to 0.1.

Returns:

A tuple containing the radius bin centers, ring brightness values, and the estimated max_frequency.

Return type:

tuple[np.ndarray, np.ndarray, float]

massphoto.psf_fitting.fit_psf_params(psf_guess, p0=None, fit_params=('a12', 'w', 's', 'r_mask'), update_defaults=False)[source]#

Fit the parameters of the PSF model to a given PSF guess.

Note

Available as both massphoto.fit_psf_params and massphoto.psf_fitting.fit_psf_params.

Parameters:

psf_guess (np.ndarray) – The PSF guess.
p0 (list[float]) – The initial parameter values.
update_defaults (bool)

Returns:

The fitted PSF and the fitted parameters.

Return type:

tuple[np.ndarray, list[float]]

massphoto.psf_fitting.get_indices(x_idx, size_padded, pad, divider)[source]#

massphoto.psf_fitting.pad_xy(psf, x_pad, y_pad, size)[source]#

massphoto.psf_fitting.fft_upscale(array, scale)[source]#

Upsample the last two dimensions of an array by an integer factor using FFT. Preserves the amplitude of the input array.

Parameters:

array (2D numpy ndarray) – Input array to be upsampled.
scale (int) – Integer scale factor for upsampling.

Returns:

array_up – Upsampled array.

Return type:

numpy ndarray

massphoto.psf_fitting.calculate_grid(fun, size=1, divider=256, pad=1, D4_symmetry=False, **kwargs)[source]#

massphoto.psf_fitting.get_lookup_fun(fun, img_only=False, size=1, divider=256, pad=1, D4_symmetry=False, interpolate=False, **kwargs)[source]#

PSF Utilities#

Point Spread Function (PSF) models for mass photometry.

Provides analytical PSF as described in: Foley et al. Nature Methods (2021): https://doi.org/10.1038/s41592-021-01261-w

massphoto.psf.psf_jinc(r, a1, w1, a2=0.0, w2=1.0, sigma=inf)[source]#

Two-component jinc-based point spread function (PSF) with Gaussian envelope.

The jinc function is normalised such that \(\mathrm{jinc}(0) = 1\):

\[\mathrm{jinc}(x) = 2\,\frac{J_1(\pi x)}{\pi x}\]

The PSF is then defined as:

\[I(r) = \left[a_1\,\mathrm{jinc}\left(\frac{r}{w_1}\right) + a_2\,\mathrm{jinc}\left(\frac{r}{w_2}\right)\right] e^{-1/2*(r/\sigma)^2}\]

so that at \(r=0\) the peak intensity equals \(a_1 + a_2\).

Notes

This PSF represents the difference between two jinc functions multiplied by a Gaussian envelope. It follows the form described in Equation (2) of the publication:

Foley et al. Nature Methods (2021). https://doi.org/10.1038/s41592-021-01261-w

Parameters:

r (NDArray[np.float64]) – Radial coordinate or array of radial coordinates.
a1 (float) – Amplitudes of the two jinc components.
a2 (float) – Amplitudes of the two jinc components.
w1 (float) – Width parameters of the two jinc components.
w2 (float) – Width parameters of the two jinc components.
sigma (float) – Gaussian envelope width.

Returns:

Intensity at radius r.

Return type:

NDArray[np.float64]

massphoto.psf.psf_2d(x, y, c=None, a12=None, w=None, s=None, r_mask=None, r_aperture=None)[source]#

Compute the two-dimensional point spread function (PSF) based on a dual-jinc model multiplied by a Gaussian envelope.

The PSF is evaluated using psf_jinc() with parameters derived from the supplied arguments or, if omitted, from defaults.psf_params:

\(a_1 + a_2 = c\)
\(a_1 / a_2 = a_{12}\)
\(w_1 = w\)
\(w_2 = w \times r_{\text{aperture}} / r_{\text{mask}}\)
\(\sigma = s\)

Parameters:

x (ArrayLike) – Cartesian coordinates.
y (ArrayLike) – Cartesian coordinates.
c (float, optional) – Overall amplitude (sum of a1 + a2). Defaults to 1.0.
a12 (float, optional) – PSF parameters. Missing values are read from defaults.psf_params.
w (float, optional) – PSF parameters. Missing values are read from defaults.psf_params.
s (float, optional) – PSF parameters. Missing values are read from defaults.psf_params.
r_mask (float, optional) – PSF parameters. Missing values are read from defaults.psf_params.
r_aperture (float, optional) – PSF parameters. Missing values are read from defaults.psf_params.

Returns:

Two-dimensional PSF intensity distribution.

Return type:

NDArray[np.float64]