pyfli.analysis.utils#

Collect numerical, masking, simulation, plotting, and export utilities shared by analysis workflows.

This module belongs to pyfli.analysis and is part of PyFLI post-processing, diagnostics, statistical comparison, and result-loading utilities for fitted FLI/FLIM datasets. Public API includes functions circular_convolution_fft(), single_ex_decay_summed_overtime(), gate_j(), Pj_continuous_mono(), Pj_from_samples_mono(), multimodal_normal(), recovery_plot(), threshold_masking(), data_masking(), and save_3d_array_as_tiff_sequence().

Functions

PhasorFreqComputaion([laser_period, ...])

Run the phasor freq computaion routine.

Pj_continuous_mono(f, m, T[, epsabs, epsrel])

Run the pj continuous mono routine.

Pj_from_samples_mono(t_samples, y_samples, m, T)

Run the pj from samples mono routine.

circular_convolution_fft(x, h[, broadcast_irf])

Run the circular convolution FFT routine.

data_masking(*arrays, mask[, return_list])

Run the data masking routine.

gate_j(m, T)

Run the gate j routine.

multimodal_normal([n_samples, mus, sigma, ...])

Run the multimodal normal routine.

plot_pixel_diagnostic(binned_decay, ...[, ...])

Plot pixel diagnostic.

random_true_pixel(bool_array)

Run the random true pixel routine.

recovery_plot(gt_dict, est_dict[, keys_to_plot])

Plots Ground Truth vs Estimates for specific keys.

save_3d_array_as_tiff_sequence(array_3d, ...)

Saves a 3D numpy array (H, W, T) as a series of 2D TIFF files.

save_as_uint16_sequence(data, output_folder)

Saves (H, W, T) array as 16-bit integer TIFFs.

save_plot(save_dir, name[, fig, dpi, close])

Save plot.

single_ex_decay_summed_overtime(tau, irf_data)

Run the single ex decay summed overtime routine.

threshold_masking(fli, irf[, threshold])

Run the threshold masking routine.
circular_convolution_fft(x, h, broadcast_irf=True)[source]#

Run the circular convolution FFT routine.

Parameters:

  • x (np.ndarray) – Input array, coordinate, or signal being transformed.

  • h (np.ndarray) – IRF, image height, or temporal kernel used by the routine.

  • broadcast_irf (bool) – Whether a shared IRF should be broadcast to every pixel.

Returns:

Circular convolution result with the same length as the input decay.

Return type:

np.ndarray

single_ex_decay_summed_overtime(tau, irf_data, alpha=1.0, err=0.0, laser_period=12.5, seed=None)[source]#

Run the single ex decay summed overtime routine.

Parameters:

  • tau (np.ndarray) – Lifetime value or lifetime map in nanoseconds.

  • irf_data (np.ndarray) – Instrument response data used to convolve or simulate decays.

  • alpha (float) – Regularization strength, fraction value, or significance threshold used by the

  • routine.

  • err (float) – Noise or perturbation level applied to simulated decays.

  • laser_period (float) – Laser repetition period in nanoseconds.

  • seed (int | None) – Random seed used for reproducible sampling.

Returns:

Tuple containing the integrated single-exponential decay and time samples.

Return type:

tuple[Any, ]

gate_j(m, T)[source]#

Run the gate j routine.

Parameters:

  • m (int) – Gate, harmonic, or interval index.

  • T (float) – Time axis or acquisition period used by the calculation.

Returns:

Integrated gate image or trace for the requested gate index.

Return type:

np.ndarray

Pj_continuous_mono(f, m, T, epsabs=1e-8, epsrel=1e-8)[source]#

Run the pj continuous mono routine.

Parameters:

  • f (np.ndarray) – Decay basis, distribution, or signal function used by the calculation.

  • m (int) – Gate, harmonic, or interval index.

  • T (float) – Time axis or acquisition period used by the calculation.

  • epsabs (float) – Absolute integration tolerance.

  • epsrel (float) – Relative integration tolerance.

Returns:

Object produced by pj continuous mono.

Return type:

Any

Pj_from_samples_mono(t_samples, y_samples, m, T)[source]#

Run the pj from samples mono routine.

Parameters:

  • t_samples (np.ndarray) – Sample times used to integrate a mono-exponential decay.

  • y_samples (np.ndarray) – Sampled mono-exponential values integrated over gates.

  • m (int) – Gate, harmonic, or interval index.

  • T (float) – Time axis or acquisition period used by the calculation.

Returns:

Object produced by pj from samples mono.

Return type:

Any

multimodal_normal(n_samples=10000, mus=None, sigma=None, weights=None, seed=None)[source]#

Run the multimodal normal routine.

Parameters:

  • n_samples (int) – Number of samples, components, gates, or iterations used by the routine.

  • mus (np.ndarray | None) – Gaussian component means used by the multimodal sampler.

  • sigma (float | None) – Standard deviation used by a sampler or noise model.

  • weights (np.ndarray | None) – Sampling or model weights used by the routine.

  • seed (int | None) – Random seed used for reproducible sampling.

Returns:

Tuple containing sampled values from the configured normal mixture.

Return type:

tuple[Any, ]

recovery_plot(gt_dict, est_dict, keys_to_plot=None)[source]#

Plots Ground Truth vs Estimates for specific keys. Handles data shapes: (N, X, Y) or (N, Batch, X, Y).

Parameters:

  • gt_dict (ndarray) – Dictionary of Ground Truth arrays.

  • est_dict (ndarray) – Dictionary of Estimated arrays.

  • keys_to_plot (ndarray | None) – List of strings (keys). If None, plots all keys in gt_dict.

Return type:

ndarray

threshold_masking(fli, irf, threshold=100)[source]#

Run the threshold masking routine.

Parameters:

  • fli (np.ndarray) – FLI lifetime map or decay-derived image to threshold.

  • irf (np.ndarray) – Instrument response function aligned with the decay signal.

  • threshold (int) – Threshold used to mask, classify, or validate data.

Returns:

Tuple containing thresholded mask arrays and metadata.

Return type:

tuple[Any, ]

data_masking(*arrays, mask, return_list=False)[source]#

Run the data masking routine.

Parameters:

  • *arrays (Any) – Additional positional values accepted by the routine.

  • mask (np.ndarray) – Boolean or labeled mask selecting pixels for the operation.

  • return_list (bool) – If True, return a list of masks instead of a combined mask.

Returns:

Object produced by data masking.

Return type:

Any

save_3d_array_as_tiff_sequence(array_3d, output_folder, prefix='frame')[source]#

Saves a 3D numpy array (H, W, T) as a series of 2D TIFF files.

Parameters: - array_3d: The numpy array of shape (H, W, T) - output_folder: Path to the folder where TIFs will be saved - prefix: Filename prefix (e.g., ‘frame_001.tif’)

Parameters:
Return type:

None

save_as_uint16_sequence(data, output_folder, prefix='frame')[source]#

Saves (H, W, T) array as 16-bit integer TIFFs.

Parameters:
Return type:

None

random_true_pixel(bool_array)[source]#

Run the random true pixel routine.

Parameters:

bool_array (np.ndarray) – Boolean array from which a true pixel is selected.

Returns:

Object produced by random true pixel.

Return type:

Any

PhasorFreqComputaion(laser_period=12.5, gate_delay=None, num_gates=None)[source]#

Run the phasor freq computaion routine.

Parameters:

  • laser_period (float) – Laser repetition period in nanoseconds.

  • gate_delay (np.ndarray | None) – Delay of each gate relative to the excitation pulse.

  • num_gates (int | None) – Number of acquisition gates used for frequency computation.

Returns:

Phasor frequency-domain representation for the input decay.

Return type:

np.ndarray

save_plot(save_dir, name, fig=None, dpi=300, close=False)[source]#

Save plot.

Parameters:

  • save_dir (str) – Directory where outputs are saved.

  • name (str) – Dataset, experiment, figure, or output name.

  • fig (Any | None) – Matplotlib figure object to update or save.

  • dpi (int) – Resolution used when saving a figure.

  • close (bool) – Whether to close the figure after saving.

Returns:

No object is returned; the function save plot.

Return type:

None

plot_pixel_diagnostic(binned_decay, all_fitset, names, pixel=None, mask=None, t=None, yscale='log', model_type='BI-EXPONENTIAL', colors=None, figsize=(12, 6), raw_style='bar', map_aspect='equal', show_colorbar=True, show=True)[source]#

Plot pixel diagnostic.

Parameters:

  • binned_decay (np.ndarray) – Binned decay cube used for fitting or diagnostics.

  • all_fitset (np.ndarray) – Collection of fit-result dictionaries used for comparison or plotting.

  • names (Any) – Dataset names used in summaries and plots.

  • pixel (np.ndarray | None) – Selected pixel coordinate.

  • mask (np.ndarray | None) – Boolean or labeled mask selecting pixels for the operation.

  • t (np.ndarray | None) – Time axis or acquisition period used by the calculation.

  • yscale (str) – Scale used for the y-axis.

  • model_type (str) – FLI/FLIM model family, such as mono- or bi-exponential.

  • colors (Any | None) – Color sequence used for plotted sources or groups.

  • figsize (tuple[int, ]) – Figure size passed to Matplotlib.

  • raw_style (str) – Style used to draw raw pixel decay data.

  • map_aspect (str) – Aspect ratio used when rendering lifetime maps.

  • show_colorbar (bool) – Whether to draw a colorbar.

  • show (bool) – Whether to display the generated plot.

Returns:

Matplotlib figure or axes containing the pixel diagnostic plot.

Return type:

np.ndarray