cbi_toolbox.reconstruct.vhf

This module implements virtual high-framerate sequence reconstruction methods for periodic signals.

[1] Mariani, O., Ernst, A., Mercader, N. and Liebling, M., 2019. Reconstruction of image sequences from ungated and scanning-aberrated laser scanning microscopy images of the beating heart. IEEE transactions on computational imaging, 6, pp.385-395.

cbi_toolbox.reconstruct.vhf.argsort_tsp(images)[source]

Returns the indices that sort a sequence of images using TSP to obtain a virtual high-framerate signal. The direction of the produced sequence is undefined.

Parameters:

images (numpy.ndarray [N, ...]) – List of images to sort.

Returns:

Array of indices that sort the sequence according to the TSP slution.

Return type:

numpy.ndarray(int)

Raises:

RuntimeWarning – When the TSP solver does not converge.

cbi_toolbox.reconstruct.vhf.average_frequency(phases, acq_frequency, n_periods=2, unfold=True)[source]

Computes the initial average frequency of a periodic signal from uniformly sampled phases by fitting a line using least squares.

Parameters:

  • phases (numpy.ndarray (float) [N]) – The unitless phases sampled in the signal.

  • acq_frequency (float) – The frequency at which the signal was sampled.

  • n_periods (float, optional) – The number of periods over which to compute the average, by default 1.

  • unfold (bool, optional) – If the input phases are folded over a single period, by default True.

Returns:

The average frequency of the sampled signal over the given region. The utits are the same as the acquisition frequency.

Return type:

float

cbi_toolbox.reconstruct.vhf.estimate_di(phases, distances, k_size, w_width, d_i_k=None)[source]

Estimate the image function distance on phases based on phase neighbours.

Parameters:

  • phases (numpy.ndarray (float) [N]) – The phase array.

  • distances (numpy.ndarray (float) [N, N]) – The pairwise image distances.

  • k_size (int) – The number of points of di to estimate.

  • w_width (float) – The size of the weighting window.

  • d_i_k (numpy.ndarray (float) [N, K+1], optional) – The array to store the d_i_kput, by default None

Returns:

  • numpy.ndarray [N, K+1] – The estimated distance functions for each point.

  • float – The residual error after optimization.

Raises:

  • ValueError –

  • RuntimeWarning –

cbi_toolbox.reconstruct.vhf.l_curve(phases, images, seq_lengths=None, w_width=0.03, k_size=None, n_points=21, iterations=50, **kwargs)[source]

Correct a sequence of phases corresponding to a periodic signal using both image-to-image and phase distances to find non uniform samplings. This method assumes that the images have been acquired at regular time intervals in one or multiple consecutive sequences.

Parameters:

  • phases (numpy.ndarray (float) [N]) – The initial estimate for the phases, given in acquisition order.

  • images (numpy.ndarray (float) [N, ...]) – The acquired images, in order of acquisition. phases[i] should correspond to images[i].

  • seq_lengths (tuple (int)) – The lengths of sequences of images acquired consecutively, if multiple sequences have been acquired. The total sum of sequence lengths must be equal to the total number of images N. By default, None: considers the entire sequence to be consecutive.

  • w_width (float, optional) – Gaussian window width (standard deviation) used to weight contributions of neighbours, by default 3e-2

  • k_size (int, optional) – Number of poins used to sample distance functions, by default None (uses N/2)

  • n_points (int, optional) – Number of values of lambda to compute for the L-curve. By default 21.

  • iterations (int, optional) – Maximum number of iterations for the phase correction algorithm. By default 50.

  • kwargs (**) – a_tol : float, optional. Absolute tolerance used to define convergence, by default 1e-4 learning_rate : float, optional. The learning rate of the gradient descent, by default 1e-3

Returns:

  • losses (numpy.ndarray [2, n_points]) – The values of the losses for each lambda, given in the order (distance cost, regularization cost)

  • lambdas (numpy.ndarray [n_points]) – The lambda values

cbi_toolbox.reconstruct.vhf.orient_phases(phases, seq_lengths=None, in_place=False)[source]

Detect the orientation of a sequence of phases sorted using TSP and flip it if necessary. Assumes that the phases have been acquired in continuous sequences under Shannon sampling assumption.

Parameters:

  • phases (numpy.ndarray (float) [N]) – The phases to orient, given in the order of acquisition.

  • seq_lengths (tuple (int)) – The lengths of sequences of images acquired consecutively, if multiple sequences have been acquired. The total sum of sequence lengths must be equal to the total number of images N. By default, None: considers the entire sequence to be consecutive.

Returns:

c_phases – The estimated unitless phases corresponding to the input images.

Return type:

numpy.ndarray (float) [N]

Raises:

ValueError –

cbi_toolbox.reconstruct.vhf.phase_correction(phases, images, seq_lengths=None, w_width=0.03, k_size=None, regu_lambda=0.5, precision_passes=0, **kwargs)[source]

Correct a sequence of phases corresponding to a periodic signal using both image-to-image and phase distances to find non uniform samplings. This method assumes that the images have been acquired at regular time intervals in one or multiple consecutive sequences.

Parameters:

  • phases (numpy.ndarray (float) [N]) – The initial estimate for the phases, given in acquisition order.

  • images (numpy.ndarray (float) [N, ...]) – The acquired images, in order of acquisition. phases[i] should correspond to images[i].

  • seq_lengths (tuple (int)) – The lengths of sequences of images acquired consecutively, if multiple sequences have been acquired. The total sum of sequence lengths must be equal to the total number of images N. By default, None: considers the entire sequence to be consecutive.

  • w_width (float, optional) – Gaussian window width (standard deviation) used to weight contributions of neighbours, by default 3e-2

  • k_size (int, optional) – Number of poins used to sample distance functions, by default None (uses N/2)

  • regu_lambda (float, optional) – The regularization strength, by default 0.5

  • precision_passes (int, optional) – The number of precision passes to perform. At each pass, window width is halved and k_size is doubled. By default 0.

  • kwargs (**) –

    max_iterint, optional

    Maximum iterations of the algorithm, by default 100

    a_tolfloat, optional

    Absolute tolerance used to define convergence, by default 1e-4

    grad_iterint, optional

    Max number of iterations of the gradient descent, by default 100

    learning_ratefloat, optional

    The learning rate of the gradient descent, by default 1e-3

Returns:

  • phases (numpy.ndarray (float) [N]) – The corrected phases

  • status (tuple) – The convergence status, containing: converged : bool. If the algorithm converged. n_iter : int. The number of iterations ran. losses : tuple(float). The final distance and regularization losses, in that order.

Raises:

ValueError –

cbi_toolbox.reconstruct.vhf.phase_diff(phase_a, phase_b)[source]

Compute the difference between unitless phases (between 0 and 1). The result of the difference lies in the interval [-0.5, 0.5[.

Parameters:

  • phase_a (array-like of floats (or float)) – Unitless phases, first operand of the difference.

  • phase_b (array-like of floats (or float)) – Unitless phases, second operand of the difference.

Returns:

The phase difference.

Return type:

type(phase_a)

cbi_toolbox.reconstruct.vhf.phase_error(phase_a, phase_b, floating_origin=True)[source]

Compute the absolute phase error between unitless phases (between 0 and 1). If the starting phases of the two operands are not fixed with respect to one another, the operands are first shifted by a scalar bias to minimize this error (i.e. the zero phase of the second sighal is set so that the mean phase differnce between the two operands is zero).

Parameters:

  • phase_a (array-like of floats) – Reference unitless phases.

  • phase_b (array-like of floats) – Target unitless phases.

  • floating_origin (bool, optional) – If the zero phase of the target phase can be shifted with respect to the zero of the reference phases to minimize the error, by default True.

Returns:

The absolute phase error between the two.

Return type:

numpy.ndarray(float)

cbi_toolbox.reconstruct.vhf.sample_video(images, phases, n_frames)[source]

Re-sample a non-uniformly sampled image sequence to generate a video.

Parameters:

  • images (np.ndarray [N, ...]) – Sequence of images of size N.

  • phases (np.ndarray [N]) – Sequence of phases corresponding to the images respectively.

  • n_frames (int) – Number of frames in the generated video

Returns:

video – The resampled video.

Return type:

np.ndarray [n_frames, W, H]

cbi_toolbox.reconstruct.vhf.unfold_phases(phases, threshold=-0.25, in_place=False)[source]

Unfold consecutive unitless phases from the range [0, 1] to R based on a negative delta threshold.

Parameters:

  • phases (numpy.ndarray [N]) – The unitless phases to unfold, in [0, 1].

  • threshold (float, optional) – The negative threshold to go to the next period, by default -0.25

  • in_place (bool, optional) – Compute operations in-place, by default False

Returns:

The unfolded phases over multiple periods.

Return type:

numpy.ndarray [N]

cbi_toolbox.reconstruct.vhf.vhf_phase_naive(images)[source]

Use naive vhf method to estimate the phases corresponding to a randomly sampled periodic signal by solving TSP, as exposed in [1].

Parameters:

images (numpy.ndarray [N, ...]) – The measured images.

Returns:

The estimated unitless phases corresponding to each input image.

Return type:

numpy.ndarray (float) [N]

cbi_toolbox.reconstruct.vhf.vhf_phase_uncorrected(images, seq_lengths=None)[source]

Use naive vhf to estimate the phases corresponding to a periodic signal sampled at regular time intervals, and its starting average frequency. The phases are estimated to be uniformly sampled, which can be improved by running the .vhf.phase_correction algorithm.

Parameters:

  • images (numpy.ndarray (float) [N, ...]) – The acquired images, in acquisition order.

  • seq_lengths (tuple (int)) – The lengths of sequences of images acquired consecutively, if multiple sequences have been acquired. The total sum of sequence lengths must be equal to the total number of images N. By default, None: considers the entire sequence to be consecutive.

Returns:

uni_phases – The estimated unitless phases corresponding to the input images.

Return type:

numpy.ndarray (float) [N]