Reconstruction Options

This module provides multiple image processing and reconstruction options. For instance, calculate the average image, calculate one moment-reconstructed image of a defined order, calculate all moment-reconstructed or cumulant reconstructed images to the user-defined highest order, calculate average moment or cumulant reconstructions over multiple user- defind blocks, with or without Fourier interpolation or bleaching correction.

Functions

pysofi.reconstruction.average_image(filepath, filename, frames=[])

Get the average image for a video file (tiff stack), either for the whole video or for user defined frames.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • frames (list of int, optional) – Start and end frame number if not the whole video is used.

Returns

mean_im – The average image.

Return type

ndarray

pysofi.reconstruction.average_image_with_finterp(filepath, filename, interp_num)

Get the average image with fourier interpolation for a video file.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • interp_num (int) – Interpolation factor.

Returns

  • mean_im (ndarray) – The average image after fourier interpolation. Interpolated

  • images can be further used for SOFI processing.

pysofi.reconstruction.block_ave_cumulants(filepath, filename, highest_order, smooth_kernel=251, fbc=0.04)

Get average cumulant-reconstructed images of all blocks determined by user-defined noise filtering and bleaching correction factor (fbc).

Within each block, the amount of signal decrease is identical. This amount of signal decrease is characterized by the bleaching correction factor, fbc, which is the fractional signal decrease within each block (as compared to the total signal decrease over the whole signal plot).

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • highest_order (int) – The highest order number of moment-reconstructed images.

  • smooth_kernel (int) – The size of the median filter (‘filtering.med_smooth’) window.

  • fbc (float) – The fraction of signal decrease within each block compared to the total signal decrease.

Returns

ave_k_set – order number (int) -> image (ndarray) A dictionary of avereage cumulant-reconstructed images of all blocks.

Return type

dict

Notes

For more information on noise filtering and bleaching corrextion, please see appendix 3 of [1].

References

1

  1. Yi, and S. Weiss. “Cusp-artifacts in high order superresolution

optical fluctuation imaging.” bioRxiv: 545574 (2019).

pysofi.reconstruction.block_ave_moments(filepath, filename, highest_order, smooth_kernel=251, fbc=0.04)

Get average moment-reconstructed images of all blocks determined by user-defined noise filtering and bleaching correction factor (fbc). Similar to ‘block_ave_cumulants’.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • highest_order (int) – The highest order number of moment-reconstructed images.

  • smooth_kernel (int) – The size of the median filter (‘filtering.med_smooth’) window.

  • fbc (float) – The fraction of signal decrease within each block compared to the total signal decrease.

Returns

ave_m_set – order number (int) -> image (ndarray) A dictionary of avereage moment-reconstructed images of all blocks.

Return type

dict

pysofi.reconstruction.calc_block_moments(filepath, filename, highest_order, frames=[])

Get moment-reconstructed images for user-defined frames (block) of a video file(tiff stack).

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • highest_order (int) – The highest order number of moment-reconstructed images.

  • frames (list of int) – Start and end frame number.

Returns

m_set – order number (int) -> image (ndarray) A dictionary of calcualted moment-reconstructed images.

Return type

dict

Notes

Similar to ‘calc_moments’. Here we omit previously calculated m_set and mean_im as inputs since a block usually has much fewer number of frames and takes shorter calculation time.

pysofi.reconstruction.calc_cumulants_from_moments(moment_set)

Calculate cumulant images from moment images using the recursive relation.

Parameters

moment_set (dict) – order number (int) -> image (ndarray) A dictionary of calcualted moment- images.

Returns

k_set – order number (int) -> image (ndarray) A dictionary of calcualted cumulant-reconstructed images.

Return type

dict

pysofi.reconstruction.calc_cumulants_from_moments_with_lag(m_set, tauSeries)

Calculate cumulant-reconstructed images from moment-reconstructed images with time lags.

Parameters

  • m_set (dict) – order (int) -> dict (partition (tuple) -> image (ndarray)) A nested dictionary of moment-reconstructions of all partitions that calculated from ‘calc_moments_with_lag’.

  • tauSeries (list of int) – A list of time lags for frames contribute to moment reconstruction. The first element is recommended to be 0, and there should be seven elements in the list. The values should be the same as the input for ‘calc_moments_with_lag’.

Returns

k_set – order number (int) -> image (ndarray) A dictionary of calcualted cumulant-reconstructed images with time lags.

Return type

dict

pysofi.reconstruction.calc_moment_im(filepath, filename, order, frames=[], mean_im=None)

Get one moment-reconstructed image of a defined order for a video file.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • order (int) – The order number of moment-reconstructed image.

  • frames (list of int) – The start and end frame number.

  • mean_im (ndarray) – Average image of the tiff stack.

Returns

moment_im – The moments-reconstructed image.

Return type

ndarray

pysofi.reconstruction.calc_moments(filepath, filename, highest_order, frames=None, m_set=None, mean_im=None)

Get all moment-reconstructed images to the user-defined highest order for a video file(tiff stack).

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • highest_order (int) – The highest order number of moment-reconstructed images.

  • frames (list of int) – The start and end frame number.

  • m_set (dict) – order number (int) -> image (ndarray) A dictionary of previously calcualted moment-reconstructed images.

  • mean_im (ndarray) – Average image of the tiff stack.

Returns

m_set – order number (int) -> image (ndarray) A dictionary of calcualted moment-reconstructed images.

Return type

dict

pysofi.reconstruction.calc_moments_with_lag(filepath, filename, tauSeries, frames=[])

Get moment-reconnstructed images with defined time lags.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • tauSeries (list of int) – A list of time lags for frames contribute to moment reconstruction. The first element is recommended to be 0, and there should seven elements in the list.

  • frames (list of int) – The start and end frame number.

Returns

m_set – order (int) -> dict (partition (tuple) -> image (ndarray)) A nested dictionary of moment-reconstructions of all partitions.

Return type

dict

pysofi.reconstruction.calc_total_signal(filepath, filename)

Calculate the total signal intensity of each frame for the whole video (tiff stack).

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

Returns

total_signal – Signal intensity of each frame ordered by the frame number.

Return type

1darray

pysofi.reconstruction.calc_xc_im(filepath, filename, ri_range, frames=[])

Get cross-cumulant image with different pixel combinations.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • ri_range (int) – Maximium distance (# pixels) between the original the selected pixel.

  • frames (list of int) – The start and end frame number.

Returns

xc – pixel (tuple) -> image (ndarray) A dictionary of reconstructed images with pixel index as keys.

Return type

dict

pysofi.reconstruction.correct_bleaching(filepath, filename, fbc=0.04, smooth_kernel=251, save_option=True, return_option=False)

Performs bleaching correction on a tiff image (stack).

Parameters

  • fbc (float) – The fraction of signal decrease within each block compared to the total signal decrease. Only used when bleach correction is True.

  • smooth_kernel (int) – The size of the median filter window.

  • save_option (bool) – Whether to save the corrected images into tiff files.

  • return_option (bool) – Whether to return the corrected image series as a 3d array.

Returns

bc_im – All bleaching-corrected imagee in a 3d array.

Return type

ndarray

pysofi.reconstruction.cumulants_all_blocks(m_set_all_blocks)

Calculate cumulant-reconstructed images from moment-reconstructed images of each block. Similar to ‘calc_cumulants_from_moments’.

pysofi.reconstruction.cut_frames(signal_level, fbc=0.04)

Find the list of frame number to cut the whole signal plot into seperate blocks based on the change of total signal intensity.

Parameters

  • signal_level (1darray) – Signal change over time (can be derived from ‘calc_total_signal’).

  • fbc (float) – The fraction of signal decrease within each block compared to the total signal decrease.

Returns

  • bounds (list of int) – Signal intensities on the boundary of each block.

  • frame_lst (list of int) – Frame number where to cut the whole signal plot into blocks.

Notes

The number of blocks is the inverse of the bleaching correction factor, fbc. For instance, if fbc=0.04, it means that in each block, the decrease in signal intensity is 4% if the total decrease, and the whole plot / video is cut into 25 blocks. For some data, it is possible that the maximun signal intensity does not appear at the beginning of the signal plot. Here, we consider all frames before the maximum in the same block as the maximum frame / intensity since usually the number of frames is not too large. The user can add in extra blocks if the initial intensity is much smaller than the maximum.

pysofi.reconstruction.min_image(filepath, filename, frames=[])

Get the minimum image for a video file (tiff stack), either for the whole video or for user defined frames.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • frames (list of int, optional) – Start and end frame number if not the whole video is used.

Returns

min_im – The minimum image.

Return type

ndarray

pysofi.reconstruction.moment_im_with_finterp(filepath, filename, order, interp_num, frames=[], mean_im=None)

Get one moment-reconstructed image of a defined order for a video file.

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • order (int) – The order number of moment-reconstructed image.

  • interp_num (int) – The interpolation factor.

  • mvlength (int) – The length of video for the reconstruction.

  • mean_im (ndarray) – Average image of the tiff stack.

Returns

moment_im – The moments-reconstructed image.

Return type

ndarray

pysofi.reconstruction.moments_all_blocks(filepath, filename, highest_order, smooth_kernel=251, fbc=0.04)

Get moment-reconstructed images for seperate blocks with user-defined noise filtering and bleaching correction factor (fbc).

Within each block, the amount of signal decrease is identical. This amount of signal decrease is characterized by the bleaching correction factor, fbc, which is the fractional signal decrease within each block (as compared to the total signal decrease over the whole signal plot).

Parameters

  • filepath (str) – Path to the tiff file.

  • filename (str) – Name of the tiff file.

  • highest_order (int) – The highest order number of moment-reconstructed images.

  • smooth_kernel (int) – The size of the median filter (‘filtering.med_smooth’) window.

  • fbc (float) – The fraction of signal decrease within each block compared to the total signal decrease.

Returns

m_set_all_blocks – block_number (int) -> {order number (int) -> image (ndarray)} A dictionary of moment-reconstructed images of each block.

Return type

dict

Notes

Similar to ‘calc_moments’. Here we omit previously calculated m_set and mean_im as inputs since a block usually has much fewer number of frames and takes shorter calculation time.

pysofi.reconstruction.sorted_k_partitions(seq, k)

Returns a list of all unique k-partitions of seq. Each partition is a list of parts, and each part is a tuple.

Examples

To calculate fourth-order moment-reconstructed image using frame 50 to 100 of the input video with FOurier interpolation (factor=2):

m_im = reconstruction.moment_im_with_finterp(filepath, filename, order=4, interp_num=2, frames=[50,100])

To calculate up to the fourth-order cumulant-reconstructed image:

m_set = reconstruction.calc_moments(filepath, filename, highest_order=4)
k_set = reconstruction.calc_cumulants_from_moments(m_set)

To calculate the average moment reconstruction by dividing the whol video into 25 blocks, and in each block the signal decrease is 4% of the total signal decrease:

mean_mim = reconstruction.block_ave_moments(filepath, filename, 4, smooth_kernel=251, fbc=0.04)

To perform bleaching correction on a input video and save the corrected images in a new tiff file:

reconstruction.correct_bleaching(filepath, filename, fbc=0.04, smooth_kernel=251,
                                 save_option=True, return_option=False)