smlmlp.blink_temporal_on module

smlmlp.blink_temporal_on(channels, crop_fr=None, /, psf_sigma_nm=100.0, *, exposure_ms=50.0, channels_pixels_nm=100.0, cuda=False, parallel=False)

Estimate the blinking on-time from temporal autocorrelations.

This function computes a temporal autocorrelation curve for each channel after subtracting a smooth background estimated from the PSF scale. The channel autocorrelations are then averaged and fitted with a 1D exponential model in order to estimate the characteristic on-time.

The returned info dictionary contains the main intermediate results, including the per-channel autocorrelations, their average, the fitted curve, and the associated time axis.

Parameters:

• channels (sequence of ndarray) – Sequence of image stacks, one per channel. Each channel is expected to have shape (n_frames, height, width).

• crop_fr (int or None, optional) – Number of temporal lags to keep from the autocorrelation. If None, it is set to half of the first channel frame count minus one.

• psf_sigma_nm (float or sequence, optional) – PSF sigma in nanometers, one value per channel or a scalar shared across channels. This value is used to define the Gaussian smoothing scale for the background estimation.

• exposure_ms (float, optional) – Exposure time in milliseconds.

• channels_pixels_nm (float or sequence, optional) – Pixel size in nanometers for each channel. This value is normalized through smlmlp.Config so that one pixel size pair is available for each channel.

• cuda (bool, optional) – Whether to use CUDA-enabled array operations when supported.

• parallel (bool, optional) – Whether to enable parallel execution in the backend functions.

Returns:

A tuple (on_time, info) where:

• on_time is the fitted characteristic on-time in milliseconds,

• info is a dictionary containing the main intermediate results.

The dictionary contains the following keys:

'ac'

Temporal autocorrelation curve for each channel.

'average'

Average temporal autocorrelation across channels.

'fit'

Fitted exponential decay evaluated on the lag grid.

'time'

Time axis in milliseconds corresponding to the fitted curve.

Return type:

tuple

Notes

For each channel, the background is estimated with a Gaussian filter using a scale of psf_sigma_nm[i] * 3. After subtraction, the temporal autocorrelation is computed, cropped, spatially averaged, shifted by its last value, and normalized by its first value.

The averaged autocorrelation is fitted with funclp.Exponential1, and the returned on-time is:

\[\tau_\mathrm{on} = \tau \times \mathrm{exposure\_ms}\]

where \(\tau\) is the fitted exponential parameter in frame units.

Examples

Estimate the on-time for one channel:

>>> import numpy as np
>>> channel = np.random.rand(50, 32, 32).astype(np.float32)
>>> on_time, info = blink_temporal_on([channel], psf_sigma_nm=[120.0])
>>> isinstance(on_time, float)
True
>>> "average" in info
True

Estimate the on-time for two channels with explicit exposure time:

>>> channels = [
...     np.random.rand(50, 32, 32).astype(np.float32),
...     np.random.rand(50, 32, 32).astype(np.float32),
... ]
>>> on_time, info = blink_temporal_on(
...     channels,
...     crop_fr=10,
...     psf_sigma_nm=[120.0, 140.0],
...     exposure_ms=25.0,
...     channels_pixels_nm=[(100.0, 100.0), (110.0, 110.0)],
... )
>>> len(info["ac"])
2
>>> info["time"].shape[0]
10