pycat.toolbox #

Notes

The function uses the SimpleITK library for the bilateral filter application, ensuring high performance and quality of noise reduction. Images are temporarily converted to float32 for processing to maintain precision.

apply_laplace_of_gauss_enhancement(image, sigma=3)[source]#

Enhances an image using a Laplacian of Gaussian (LoG) filter followed by intensity rescaling and inversion to highlight edges. The process involves edge detection, shifting image intensity to ensure all values are positive, rescaling the intensity to a specified range, inverting the intensity to emphasize edges, and optionally multiplying with the original image for attenuation.

Parameters:

image (numpy.ndarray) – The input image to be enhanced.
sigma (float) – The standard deviation of the Gaussian kernel used in the LoG filter.

Returns:

enhanced_img (numpy.ndarray) – The enhanced image, which is the input image attenuated by the processed LoG image for edge enhancement.
inverted_img (numpy.ndarray) – The inverted LoG image, useful for visualization and analysis, can be applied as an attenuation mask to the original image.

apply_laplace_of_gauss_filter(image, sigma=3)[source]#

Applies a Laplacian of Gaussian (LoG) filter to an input image for edge detection. This method combines Gaussian smoothing with a Laplacian filter to reduce noise before detecting edges, enhancing feature definition and image quality.

Parameters:

image (numpy.ndarray) – The input image to be processed.
sigma (float) – Standard deviation of the Gaussian kernel, which determines the level of blurring and influences edge detection sensitivity.

Returns:

gauss_laplace_image – The image processed with the LoG filter, highlighting edges and returning it in the original data type.

Return type:

apply_rescale_intensity(image, out_min=None, out_max=None)[source]#

Rescales the intensity of an image to a specified range, adjusting its pixel values accordingly.

This function modifies the intensity values of the image so that the output image’s pixel intensities are scaled between out_min and out_max. This is useful for enhancing image contrast or normalizing image data.

Parameters:

image (numpy.ndarray) – The input image whose intensities are to be rescaled.
out_min (float, optional) – The minimum intensity value for the output image. If not provided, defaults to the minimum value supported by the input image’s data type.
out_max (float, optional) – The maximum intensity value for the output image. If not provided, defaults to the maximum value supported by the input image’s data type.

Returns:

rescaled_image – The image with rescaled intensity values.

Return type:

Notes

It is crucial not to set out_min and out_max to the same value to avoid a division by zero error. Also, ensure that the output range does not exceed the input image’s data type range; for example, scaling an 8-bit image to values outside 0-255 will lead to clipping and potential data loss.

background_inpainting_func(image, mask, ball_radius)[source]#

This function uses skimage biharmonic inpainting to ‘extend’ the masked region of an image to avoid edge effects and artifacts from the rolling ball background subtraction method.

This function first uses dilation and erosion of the mask to define the ‘unknown’ region for inpainting, then applies a biharmonic inpainting algorithm to fill in the background.

Parameters:

image (numpy.ndarray) – The input image as a NumPy array.
mask (numpy.ndarray) – A binary mask identifying the region of the image to be inpainted (background).
ball_radius (int) – Radius used to adjust the size of the mask dilation and erosion, aiding in defining the inpainting region.

Returns:

inpainted_img – The image with the background inpainted, returned as a NumPy array of the same type as the input image.

Return type:

compute_rolling_ball_background(image, ball_radius)[source]#

Computes the background of an image using a rolling ball algorithm. This method is particularly useful for subtracting background from unevenly lit images.

The function handles both 2D and 3D images, applying a suitable kernel for the rolling ball algorithm based on the image dimensions.

Parameters:

image (numpy.ndarray) – The input image as a NumPy array.
ball_radius (int) – Radius of the rolling ball, determining the size of the structure that can be subtracted.

Returns:

rb_background – The background of the image computed using the rolling ball algorithm, matching the shape and dtype of the original image.

Return type:

deblur_by_pixel_reassignment(I_in, PSF, gain, window_radius)[source]#

Performs Deblurring by Pixel Reassignment, adapted from MATLAB code, enhancing microscopy image quality by reducing blurriness and improving visualization of microscopic entities [dpr_1].

Parameters:

I_in (numpy.ndarray) – The input image array to be processed.
PSF (float) – Point Spread Function width, quantifying blurriness in terms of pixels.
gain (float) – Gain factor to adjust the intensity of pixel displacement.
window_radius (int) – Radius in pixels for the local minimum filter, enhancing local contrast.

Returns:

single_frame_I_out (numpy.ndarray) – The DPR processed deblurred image.
single_frame_I_magnified (numpy.ndarray) – The magnified input image.

Notes

The function adapts MATLAB code to Python, implementing modifications to suit Pythonic nuances and the specific data. Modifications include scaling down the gain to reduce artifacts introduced by integer gain values in Python, which differ from MATLAB’s handling.

References

[dpr_1]

MATLAB code source: [DPR Project](biomicroscopy/DPR-Project) - Related paper: “Advanced Photonics, Vol. 5, Issue 6, 066004 (October 2023)”, available at https://doi.org/10.1117/1.AP.5.6.066004

gabor_filter_func(image)[source]#

Applies a Gabor filter to an image to enhance texture and feature visibility at specific orientations. This function utilizes a bank of Gabor filters at four distinct angles (0, 45, 90, and 135 degrees), which helps in capturing edge and texture information effectively. The results from these orientations are summed to create a composite image that emphasizes variations in pixel intensity related to the filter orientations, thereby enhancing the visibility of features aligned with these angles.

Parameters:: image (numpy.ndarray) – A 2D array representing the input image. The image can be of any unsigned data type.
Returns:: A 2D numpy array of the enhanced image. This output emphasizes the texture and edge features present in the original image at the specified filter orientations. The output image is converted back to the original image data type, ensuring compatibility with further processing or visualization steps.
Return type:: numpy.ndarray

Notes

The function processes the image using a float32 intermediate data type for filtering operations to ensure accuracy while maintaining performance. The output is then rescaled to emphasize feature variations and converted back to the original image data type.

invert_image(image)[source]#

Inverts the intensity of an image, mapping dark regions to light and vice versa, suitable for different data types.

This function applies an inversion transformation where each pixel’s intensity is subtracted from the maximum possible value for its data type, effectively reversing its brightness. This operation is tailored for different data types to maintain the integrity of the image’s contrast and appearance.

Parameters:: image (numpy.ndarray) – The input image to be processed. The image can be of any data type that is supported by the function.
Returns:: inverted_image – The intensity-inverted image, matching the input image’s data type and dimensions.
Return type:: numpy.ndarray

Notes

The inversion logic varies by data type: - Unsigned integers: Subtract pixel values from their maximum possible value. - Signed integers: Subtract pixel values from -1, flipping their sign. - Floats (0 to 1 range): Subtract pixel values from 1.

This function assumes the input image’s pixel values are appropriately scaled for their data type.

peak_and_edge_enhancement_func(image, ball_radius)[source]#

Enhances the edges and peaks of features within an image through a sequence of image processing operations. This includes Gaussian background division, application of a Gabor filter, morphological operations, and adaptive histogram equalization to improve contrast.

Parameters:

image (numpy.ndarray) – The input image to be enhanced, which can be of any unsigned integer data type.
ball_radius (int) – Determines the size of the Gaussian filter used for initial smoothing, indirectly affecting the scale of features targeted for enhancement.

Returns:

output_image – The enhanced image, showing improved visibility of edges and peaks. The output retains the same data type as the input.

Return type:

Notes

The sequence starts with Gaussian background division to highlight edges by suppressing steady background features, followed by a Gabor filter for edge and texture enhancement. Morphological dilation and erosion emphasize structures, and adaptive histogram equalization adjusts contrast. The process is designed for small to medium-sized features, making it suitable for applications like microscopy or detailed texture analysis.

pre_process_image(image, ball_radius, window_size)[source]#

Enhances features in an image through a comprehensive pre-processing pipeline that includes noise reduction, feature enhancement, and contrast improvement. This function is tailored for images where maintaining feature integrity and detail is crucial, such as in microscopic imaging.

Parameters:

image (numpy.ndarray) – The input image array to be processed.
ball_radius (int) – The radius used for the disk element in the White Top Hat filter and other morphological operations.
window_size (int) – The window size used for CLAHE, influencing how contrast is adapted locally in the image.

Returns:

output_image – The pre-processed image, converted back to its original data type, with enhanced features and reduced noise.

Return type:

Notes

The pre-processing pipeline includes the following steps: - Converting image data type to float32 for processing. - Applying a White Top Hat filter to highlight bright elements smaller than the footprint. - Enhancing the image using a Laplacian of Gaussian filter. - Removing background and noise using a custom wavelet based noise and backkgroud removal function. - Performing erosion and dilation for noise reduction. - Applying Gaussian filter for smoothing. - Enhancing contrast using CLAHE (Contrast Limited Adaptive Histogram Equalization).

rb_gaussian_background_removal(image, ball_radius, equalize_intensity=False, roi_mask=None)[source]#

Removes background from an image using rolling ball and Gaussian blur techniques, aiming to enhance contrast and detail by minimizing background noise. The rolling ball algorithm is used first to model and subtract the background. Then, Gaussian blur is applied to smooth all image details into the background, which is then subtracted from the original image to remove the remaining background.

Parameters:

image (numpy.ndarray) – The input image array from which to remove background noise.
ball_radius (int) – Determines the radius for the rolling ball filter and influences the smoothing level of the Gaussian blur.
equalize_intensity (bool, optional) – Enables intensity histogram equalization for the output image for improved visualization. Defaults to False.
roi_mask (numpy.ndarray, optional) – A binary mask indicating the region of interest within the image. Background removal is confined to this region.

Returns:

bg_removed_image – The image with the background removed, maintaining the same dimensions and data type as the input.

Return type:

Note

The function handles data type conversions internally for processing and reverts to the original data type for compatibility with downstream imaging tasks.

rb_gaussian_bg_removal_with_edge_enhancement(image, ball_radius, roi_mask=None)[source]#

Applies background removal and edge enhancement to an image using a combination of processing techniques. The method involves rolling ball and Gaussian background subtraction followed by edge enhancement through Gabor filtering and adaptive histogram equalization to improve feature visibility, particularly useful in microscopic image analysis.

Parameters:

image (numpy.ndarray) – The input image to be processed.
ball_radius (int) – The radius of the rolling ball filter, used in the initial background removal step.
roi_mask (numpy.ndarray, optional) – A binary mask defining the region of interest (ROI); processing is confined to this region if provided.

Returns:

output_image – The enhanced image after background removal and edge enhancement, returned in the original data type.

Return type:

Note

The sequence of image processing steps integrates background subtraction with texture and edge enhancement to enhance microscopic images or similar detailed visual data.

run_apply_bilateral_filter(radius_input, viewer)[source]#

Applies a bilateral filter to an active image layer in a Napari viewer to reduce noise while preserving important details. The filter radius is retrieved from the user’s input.

Parameters:

radius_input (QLineEdit) – The input field where users specify the filter radius.
viewer (napari.Viewer) – The viewer instance where the processed image will be displayed.

Raises:

Error – If no active image layer is selected.

Notes

The function retrieves the radius from the input, applies the bilateral filter, and displays the result as a new layer in the viewer, facilitating immediate visual feedback.

run_apply_laplace_of_gauss_filter(sigma_input, viewer)[source]#

Applies the Laplacian of Gaussian (LoG) filter to the currently active image layer in a Napari viewer, using a user-specified sigma value from UI input. This enhances the image by highlighting edges through LoG filtering.

Parameters:

sigma_input (UI Element) – A UI element that allows the user to input the sigma value for the LoG filter.
viewer (napari.Viewer) – The Napari viewer instance where the image layer is displayed and processed.

Raises:

Error – If no active image layer is selected in the viewer, prevent the application of the filter.

run_apply_rescale_intensity(out_min_input, out_max_input, viewer)[source]#

Applies intensity rescaling to the currently active image layer in a Napari viewer based on user-specified minimum and maximum output intensity values.

This function interacts with a Napari viewer, allowing users to rescale the intensity of the selected image layer directly through UI elements for specifying the intensity range. The adjusted image is then displayed in the viewer.

Parameters:

out_min_input (UI Element) – A UI element for user input of the minimum output intensity value. Typically a text input field.
out_max_input (UI Element) – A UI element for user input of the maximum output intensity value. Typically a text input field.
viewer (napari.Viewer) – The Napari viewer instance where the image layers are managed and displayed.

Raises:

Error – If no active image layer is selected or if the active layer is not compatible as an image layer for processing.

Notes

It is assumed that out_min_input and out_max_input are components of a graphical user interface and can retrieve textual input from the user, which is then converted to floating point values for the rescaling function.

Error handling for digit inputs should be added. For example:

# Ensure the input is valid and convert to an integer
if new_label_input.text() == "" or not new_label_input.text().isdigit():
    print("Please enter a valid label value.")
    return

run_clahe(clip_input, k_size_input, viewer)[source]#

Applies Contrast Limited Adaptive Histogram Equalization (CLAHE) to the currently active image layer in the Napari viewer. This technique enhances the contrast of the image by dividing it into small blocks and applying histogram equalization to each block independently, limiting the amplification of noise common in standard methods.

Parameters:

clip_input (UI Element (Text Input)) – A UI element that allows the user to input the clip limit value for CLAHE.
k_size_input (UI Element (Text Input)) – A UI element that allows the user to input the kernel size for CLAHE.
viewer (napari.Viewer) – The Napari viewer instance where the image layer is displayed and processed.

Raises:

Error – If no active image layer is selected in the viewer.

Notes

The function processes the image by converting it to float32 for enhanced precision during CLAHE and then converts it back to its original data type. The clip limit and kernel size are adjustable, allowing for fine-tuning of the contrast enhancement based on specific image requirements.

run_dpr(psf_input, gain_input, data_instance, viewer)[source]#

Executes the Deblurring by Pixel Reassignment (DPR) process on a selected layer within a napari viewer, using user-defined PSF and gain settings to improve image clarity and detail.

Parameters:

psf_input (QLineEdit) – Widget for inputting the PSF value.
gain_input (QLineEdit) – Widget for inputting the gain value.
data_instance (object) – Contains data and metadata, such as cell diameter.
viewer (napari.Viewer) – Viewer instance where images are displayed.

Raises:

Error – If no active image layer is selected in the viewer.

run_enhanced_rb_gaussian_bg_removal(data_instance, viewer)[source]#

Executes an enhanced RB Gaussian background removal process on the active image layer within a napari viewer, improving the image by removing background noise and enhancing edges. The processed image is then displayed as a new layer in the viewer.

Parameters:

viewer (napari.Viewer) – The napari viewer object to which the processed image will be added.
data_instance (DataInstance) – Encapsulates relevant data and parameters for the session, including the necessary ball radius for processing.

Raises:

Error – If no active image layer is selected, preventing process execution.

Note

Retrieves parameters from the data_instance, applies the background removal and enhancement process, and updates the viewer with a new layer named to indicate the applied enhancements.

run_invert_image(viewer)[source]#

Inverts the intensity of the currently active image layer in the Napari viewer using PyQt GUI components.

This function retrieves the currently selected image layer from the Napari viewer, inverts its intensity, and displays the result as a new layer in the viewer. This is particularly useful for enhancing visual contrast or highlighting specific features in biophysical imaging data.

Parameters:: viewer (napari.Viewer) – The Napari viewer instance, used for displaying and processing the image layers. The viewer is expected to be part of a PyQt application, integrating seamlessly with other GUI components.
Raises:: Error – If no active image layer is selected, or if the selected layer is not suitable for processing (e.g., not an image layer).

run_morphological_gaussian_filter(filter_size_input, viewer)[source]#

Applies morphological operations and Gaussian smoothing to the active image layer in the Napari viewer, enhancing structural features and reducing noise. The process involves morphological dilation and erosion followed by Gaussian smoothing, with the results added as a new layer to the viewer.

Parameters:

filter_size_input (text input) – A user interface element that allows the user to input the filter size, influencing the extent of the morphological operations and Gaussian smoothing.
viewer (Viewer) – An image viewer object that contains image layers, such as in a Napari viewer.

Raises:

Error – If no active image layer is selected in the viewer.

Notes

The filter size from the user input determines the size of the disk-shaped structural element used for morphological dilation and erosion, directly impacting the degree of feature enhancement and noise reduction.

run_peak_and_edge_enhancement(data_instance, viewer)[source]#

Applies peak and edge enhancement techniques to the currently active image layer in a Napari viewer. The enhancement process includes Gabor filtering, morphological operations, Gaussian smoothing, and adaptive histogram equalization.

Parameters:: viewer (napari.Viewer) – The viewer containing the image layer to be enhanced.
Raises:: Error – If no active image layer is selected, preventing the function from proceeding.

Notes

The function retrieves the currently active image layer, applies the peak_and_edge_enhancement_func, and adds the enhanced image back as a new layer to the viewer.

run_pre_process_image(data_instance, viewer)[source]#

Run the pre-processing function on an image selected in a viewer interface. This function handles the selection of an active image layer, retrieves necessary parameters from a data instance, applies the pre-processing, and then adds the processed image back to the viewer.

Parameters:

viewer (napari.Viewer) – The Napari viewer instance where the image layers are managed.
data_instance (object) – An object containing the data repository with parameters such as ball radius and window size for the pre-processing.

Raises:

Error – If no active image layer is selected.

Notes

Retrieves necessary parameters from the data_instance, applies a comprehensive pre-processing pipeline to the selected image, and displays the enhanced image as a new layer in the viewer. This allows users to immediately observe and analyze the effects of the pre-processing on the original image.

run_rb_gaussian_background_removal(eq_int_input, data_instance, viewer)[source]#

Executes the rb_gaussian_background_removal function on an active image layer within a napari viewer, enhancing the image by removing background noise using a combined rolling ball and Gaussian blur approach.

Parameters:

eq_int_input (QtWidgets.QCheckBox) – Input checkbox to specify whether intensity equalization should be applied to the processed image.
data_instance (DataInstance) – An object encapsulating relevant data and parameters, including the ball radius for background removal.
viewer (napari.Viewer) – The image viewer in which the processed image will be displayed.

Raises:

Error – If no active image layer is selected or if the layer is not compatible for processing.

Note

This function fetches parameters from the data_instance, applies background removal to the selected image, and updates the viewer by adding the processed image as a new layer. The name of the new layer reflects the background removal process.

run_upscaling_func(data_checkbox, data_instance, viewer)[source]#

Applies the upscale_image_interp function to selected image layers within a viewer interface, potentially updating related data in the data_instance based on the upscaling process and user input. It iterates over selected image layers, applies upscaling, and optionally updates related data in the data_instance. The result is added back to the viewer as a new image layer.

Parameters:

viewer (napari.Viewer) – The viewer object that contains the image layers to be upscaled.
data_instance (DataInstance) – An object containing data and parameters that may need updating based on the image upscaling (e.g., object sizes, resolution information).
data_checkbox (Checkbox) – A user interface element indicating whether to update certain data in the data_instance based on the upscaling results.

Notes

The function ensures that upscaling does not apply to images already at or above a specific size threshold (2048x2048). It also corrects data types and ranges for upscaled images to ensure they are suitable for further processing or display within the viewer. This function interacts directly with the Napari viewer’s GUI elements, facilitating a seamless user experience in adjusting image properties.

run_wavelet_noise_subtraction(psf_input, noise_level_input, viewer)[source]#

Applies the wavelet noise subtraction from the WBNS process to an active image layer selected in a viewer. Reads PSF and noise level values from input fields, processes the selected image using the WBNS algorithm, and updates the viewer with the corrected image.

Parameters:

psf_input (QLineEdit) – Input field for specifying the point spread function (PSF) value, which determines the wavelet decomposition levels for noise processing.
noise_level_input (QLineEdit) – Input field for setting the noise level, indicating the intensity of noise reduction to apply.
viewer (napari.Viewer) – Viewer instance where the processed images are displayed.

Raises:

Error – If no active image layer is selected.

run_wbns(psf_input, noise_level_input, viewer)[source]#

Executes the WBNS process on an active image layer within a napari viewer, enhancing the image by removing background noise and correcting noise artifacts based on user-input PSF and noise level settings.

Parameters:

psf_input (QLineEdit) – Input field for the PSF value, determining the decomposition level for wavelet processing.
noise_level_input (QLineEdit) – Input field for the noise level, specifying how many wavelet decomposition levels are used for noise reduction.
viewer (napari.viewer.Viewer) – Viewer instance where the processed images are displayed.

Raises:

Error – If no active image layer is selected.

Notes

The function retrieves settings from user inputs, applies the WBNS algorithm to the selected image, and updates the viewer with the processed image, adding it as a new layer with a descriptive name.

subtract_background(image, background, bg_scaling_factor=0.75, equalize_intensity=False, window_size=None)[source]#

Subtracts the background from an image, optionally scaling the background intensity and applying local contrast enhancement.

Parameters:

image (numpy.ndarray) – The input image from which to subtract the background.
background (numpy.ndarray) – The computed background to be subtracted.
bg_scaling_factor (float, optional) – A scaling factor for the background intensity before subtraction, defaulting to 0.75.
equalize_intensity (bool, optional) – Whether to apply adaptive histogram equalization to the result, defaulting to False.
window_size (int, optional) – The window size for adaptive histogram equalization, required if equalize_intensity is True.

Returns:

ouput_image – The image with the background subtracted and optional contrast enhancement, matching the original data type.

Return type:

upscale_image_interp(image, num_row_initial, num_col_initial, upscale_factor=2, pad=False)[source]#

Upscales an image using bicubic interpolation to enhance its resolution. This function increases the density of image pixels based on the given upscale factor, applying bicubic spline interpolation to estimate the pixel values at new grid points.

Parameters:

image (numpy.ndarray) – The input image array to be upscaled.
num_row_initial (int) – The number of rows in the input image.
num_col_initial (int) – The number of columns in the input image.
upscale_factor (int, optional) – The factor by which the image resolution is to be increased, doubling the dimensions by default.
pad (bool, optional) – If True, retains a constant border padding of 10 pixels to mitigate edge artifacts. Default is False, which removes the padding from the final output.

Returns:

magnified_image – The upscaled image with increased resolution. If padding is not removed, the returned image includes a 10-pixel border around the edges.

Return type:

Note

The function pads the upscaled image with a constant border of 10 pixels to mitigate edge artifacts, unless specified otherwise by the pad parameter. This is important for applications where edge continuity is critical.

wavelet_bg_and_noise_calculation(image, num_levels, noise_lvl)[source]#

Decomposes an image using a wavelet transform and selectively modifies the coefficients to isolate and remove noise and background before reconstructing the image. This method allows for precise background and noise estimation and removal.

Parameters:

image (numpy.ndarray) – Input image array for processing.
num_levels (int) – Number of decomposition levels for background estimation in the wavelet transform.
noise_lvl (int) – Levels considered for noise estimation and removal in the wavelet decomposition.

Returns:

Background (numpy.ndarray) – The estimated background after wavelet decomposition and reconstruction.
Noise (numpy.ndarray) – The noise component extracted from the wavelet decomposition.
BG_unfiltered (numpy.ndarray) – The raw background before filtering and Gaussian smoothing.
Authors
——-
- Manuel Hüpfel, Institute of Applied Physics, KIT, Karlsruhe, Germany
- Improved documentation (Christian Neureuter, University at Buffalo)

wbns_func(img, psf_px_resolution, noise_lvl)[source]#

Wrapper function for wavelet-based background and noise subtraction (WBNS), adapted from [wbns_1]. It adjusts image dimensions for compatibility, performs background and noise subtraction using wavelet transforms, and restores original dimensions, improving image clarity.

Parameters:

img (numpy.ndarray) – Input image array to be processed.
psf_px_resolution (int) – Resolution of the image in pixels, based on the point spread function (PSF) size, used to calculate decomposition levels for wavelet processing.
noise_lvl (int) – Number of levels to consider for noise estimation and removal during wavelet processing.

Returns:

bg_noise_output_image (numpy.ndarray) – The image with background and noise subtracted, maintaining the original data type.
noise_output_image (numpy.ndarray) – The image with noise subtracted, but not backgroud correction, maintains the original data type.
tuple – Returns a tuple of numpy.ndarrays: the background and noise corrected image, and the noise-only corrected image.

Notes

In adapting this code, the paralell processing was removed as was the 3D z-stack processing. It would be simpe enough to refer to their original source code, should the functionality be desired to be re-added. The noise level also had a gaussian blur added to it, similar to the reconstrcuted background, to further reduce artifacts, as leaving it as is, caused some artifacts in the final image. The background and noise images were scaled by 0.75 and 0.25 respectively, as leaving them as is, was a bit aggressive.

References

[wbns_1]

Original Python code: [HuepfelM WBNS](NienhausLabKIT/HuepfelM) - Related paper: Biomed. Opt. Express 12, 969-980 (2021), [DOI](https://doi.org/10.1364/BOE.413181)

Segmentation#

Image Segmentation and Analysis Module for PyCAT

This module provides functions for image segmentation and analysis, including local thresholding, watershed segmentation, felzenszwalb segmentation, cellpose segmentation, random forest pixel classification, and more. These functions are designed to process grayscale images and binary masks, segment objects of interest, and extract relevant features for further analysis. Segmentation and post-segmentation filtering and processing functions are contained within to ensure accurate and reliable segmentation results.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

apply_watershed_labeling(original_image, binary_mask, sigma=1.5)[source]#

Apply watershed segmentation to an image for labeling different segments. The segmentation is based on a binary mask that defines the regions of interest. The function first converts the original image to a suitable dtype, applies Gaussian filtering to smooth the image, calculates the distance transform of the binary mask, and then performs the watershed segmentation on the smoothed distance map. Finally, it refines the segmentation by a binary morphological operation and labels the segments.

Parameters:

original_image (numpy.ndarray) – The original image to be segmented. It can be of any dimensional shape.
binary_mask (numpy.ndarray) – A binary mask defining the regions of interest in the original_image. It must have the same shape as original_image.
sigma (float, optional) – The sigma value for the Gaussian filter applied to the distance transform. This controls the amount of smoothing. Default is 1.5.

Returns:

labeled_segments – An array of the same shape as original_image and binary_mask, containing labels for different segments identified by the watershed algorithm.

Return type:

Notes

The watershed algorithm is sensitive to the number of local maxima in the distance transform, which are used as markers. The sigma parameter can be adjusted to control the smoothing applied to the distance transform, thus influencing the segmentation result. This function utilizes a disk-shaped structuring element for the final morphological operation to refine the segmentation. The size and shape of this element can be adjusted for different applications.

Examples

>>> original_image = np.array([...])  # Some image data
>>> binary_mask = np.array([...])    # A binary mask for the image
>>> labeled_segments = apply_watershed_labeling(original_image, binary_mask, sigma=1.5)

cell_mask_stretching(image, cell_masks)[source]#

Enhances the contrast within specific areas of an image defined by cell masks, followed by smoothing operations.

The function dilates the cell masks to include surrounding areas, then applies CLAHE (Contrast Limited Adaptive Histogram Equalization) to these regions for contrast enhancement. The areas are then slightly eroded to fit the original mask dimensions. After processing all masks, the background is zeroed out, and the image is smoothed using grey-scale morphological operations to avoid blurring.

Parameters:

image (numpy.ndarray) – The input image to perform contrast stretching on. Must be a 2D array.
cell_masks (numpy.ndarray) – A labeled mask image where each cell is represented by a unique integer label, and the background is 0.

Returns:

output_image – The image after applying contrast enhancement and smoothing operations, in the original data type.

Return type:

Notes

This function assumes the presence of at least one cell label in cell_masks (i.e., not all values are 0). It enhances only the areas defined by the masks, leaving the background unaffected except for smoothing. The CLAHE parameters are dynamically adjusted based on the object’s estimated radius from its area.

cellpose_segmentation(image, object_diameter)[source]#

Perform cell segmentation on an image using Cellpose, a deep-learning-based method for cell/nucleus segmentation.

This function processes an input image to enhance its features and applies the Cellpose deep learning model for cell and nucleus segmentation. It focuses on segmenting the image into distinct cell or nucleus areas. The object_diameter parameter is used to determine the scale of the objects to be segmented.

Parameters:

image (numpy.ndarray) – The input image for cell segmentation, expected to be in a format compatible with Cellpose.
object_diameter (int) – The approximate diameter (in pixels) of the cells or nuclei to be segmented in the image. This value scales the segmentation process.

Returns:

mask – A binary mask of the segmented cells/nuclei in the input image, refined to enhance separation between adjacent objects and extend segmentation to image edges.

Return type:

Notes

Cellpose model ‘cyto2’ is used by default for broader applicability in cell and nucleus segmentation.
The input image is processed through several steps including dynamic range conversion, adaptive histogram equalization, denoising, and intensity rescaling to optimize it for segmentation.
Ensure that the Cellpose library is installed and properly configured in your environment. For more information on Cellpose, see: https://cellpose.readthedocs.io/en/latest/.
This function assumes the availability of several skimage and custom preprocessing functions to prepare the image for segmentation.

felzenszwalb_segmentation_and_merging(image, scale=7.0, sigma=0.5, min_size=2)[source]#

Performs image segmentation using Felzenszwalb’s method followed by merging based on color similarity.

This function applies an initial segmentation to the input image using Felzenszwalb’s efficient graph-based segmentation algorithm. It then constructs a Region Adjacency Graph (RAG) from the initial segments and merges segments based on the similarity of their mean color (intensity for grayscale). The merging process is controlled by comparing the color distance between segments against a threshold derived from the image’s standard deviation.

Parameters:

image (numpy.ndarray) – The input image to segment. Can be a grayscale or RGB image.
scale (float, optional) – The scale parameter influences the size of the clusters in the initial segmentation. Higher values result in larger clusters. This controls how aggressively pixels are merged together in the initial segmentation. Defaults to 7.0.
sigma (float, optional) – The standard deviation for the Gaussian kernel used in smoothing the image before segmenting. This preprocessing step can help reduce noise and improve the quality of segmentation. Defaults to 0.5.
min_size (int, optional) – The minimum size of final segments. Smaller segments are merged during post-processing to ensure that every segment is at least this size. Defaults to 2.

Returns:

segmented_img – The segmented image with segments represented by the average color (or intensity) of their respective pixels, returned in the same data type as the input.

Return type:

Notes

‘scale’ directly influences how aggressively pixels are merged in the initial segmentation, correlating with the ‘k’ parameter in Felzenszwalb’s paper.
Appropriate selection of ‘scale’, ‘sigma’, and ‘min_size’ is crucial for optimal segmentation results, depending on the image’s specific characteristics.

fz_segmentation_and_binarization(image, mask, ball_radius)[source]#

Applies Felzenszwalb’s segmentation method followed by additional processing to convert the segmented image into a refined binary mask. This involves contrast adjustments, morphological operations, and local thresholding to highlight distinct objects within a specified region of interest. Additionally, external contours are detected and filled to ensure solid object representation in the binary mask.

Parameters:

image (numpy.ndarray) – The input grayscale image for segmentation.
mask (numpy.ndarray) – A binary mask defining the region of interest where segmentation is focused.
ball_radius (int) – The radius influencing the segmentation sensitivity and scale, particularly used in local thresholding.

Returns:

boolean_mask – A binary mask refined from the segmented image, highlighting detected objects within the region defined by the input mask.

Return type:

Notes

The process dynamically adjusts to the ‘ball_radius’ to ensure appropriate scale processing for different image details.
A correct ‘ball_radius’ is crucial for optimal segmentation and post-processing results.
The function assumes the input image has undergone basic preprocessing for noise reduction and contrast enhancement.
The binary mask is further processed through morphological operations and local thresholding to ensure a clean and usable output.

local_thresholding_func(image, window_size, k_val=-0.5, mode='AND')[source]#

Applies local thresholding on the input image based on the specified method and parameters. Local thresholding is applied using either the Niblack or Sauvola method, or a combination thereof, to produce a binary mask that highlights regions of interest in the image based on local pixel value variations.

Parameters:

image (numpy.ndarray) – The input grayscale image to undergo thresholding.
window_size (int) – Size of the window for local threshold calculations. Adjusted to the nearest odd number if even.
k_val (float, optional) – The parameter influencing the threshold computation for both Niblack and Sauvola methods. Defaults to -0.5.
mode (str, optional) – Specifies the thresholding method or the combination of binary masks. Valid options are ‘Niblack’, ‘Sauvola’, ‘AND’ (intersection of Niblack and Sauvola masks), and ‘OR’ (union of Niblack and Sauvola masks). Defaults to ‘AND’.

Returns:

thresh_mask – Binary mask from the applied thresholds, indicating areas of interest (1) against the background (0).

Return type:

Raises:

ValueError – If the mode provided is not supported.

Example

Applying combined Niblack and Sauvola thresholding with a window size of 15 and a k-value of -0.5: >>> image = np.random.rand(100, 100) >>> mask = local_thresholding_func(image, 15, -0.5, ‘AND’) >>> mask.shape (100, 100)

merge_mean_color(graph, src, dst)[source]#

Callback called before merging two nodes of a mean color distance graph.

Prior to merging two nodes in a RAG, this function updates the dst node’s attributes to reflect the combined color information of both src and dst. This is crucial for accurately computing the mean color of the merged node, ensuring the graph’s integrity and the accuracy of its color representation.

Parameters:

graph (RAG) – The graph under consideration.
src (int) – The vertices in graph to be merged.
dst (int) – The vertices in graph to be merged.

opencv_watershed_func(binary_mask, original_image=None, dist_thresh=0.5, sigma=3.5, dilation_size=2, dilation_iterations=3)[source]#

Applies the Watershed algorithm to segment objects from a binary mask of an image. This function refines the binary mask using morphological operations, applies a distance transform, and uses the Watershed algorithm to delineate separate objects. Optionally, the algorithm can utilize the original image for improved segmentation accuracy.

Parameters:

binary_mask (numpy.ndarray) – A binary mask where the contours are to be detected and drawn. The mask should be in a format compatible with OpenCV (usually a binary image).
original_image (numpy.ndarray, optional) – The original intensity image which, if provided, should match the dimensions of binary_mask.
dist_thresh (float, optional) – Threshold for the distance transform, specified as a fraction of its maximum value. Defaults to 0.5.
sigma (float, optional) – The standard deviation for Gaussian filtering, used to smooth the distance transform and the original image if provided. Defaults to 3.5.
dilation_size (int, optional) – The size of the structuring element used for dilation, which helps define sure background areas. Defaults to 2.
dilation_iterations (int, optional) – The number of iterations for dilation, used to enhance the background determination. Defaults to 3.

Returns:

watershed_contours – A binary mask indicating the boundary contours of segmented objects, with the same dimensions as the input binary_mask.

Return type:

Raises:

ValueError – If the dimensions of the original image and binary mask do not match.

Notes

The function performs an initial morphological opening to clean up small noise in the mask, followed by dilation to determine sure background areas. It applies a Gaussian blur to smooth the distance transform and optionally the original image, uses a threshold to identify sure foreground areas, and subtracts the foreground from the background to define regions of uncertainty. The Watershed algorithm is then applied using either the original image or the refined mask, depending on the input provided. The resulting segmented boundaries are returned as a binary mask.

puncta_refinement_filtering_func(original_img, processed_img, puncta_mask, cell_mask, labeled_puncta_mask, min_spot_radius)[source]#

Refines a segmentation mask by filtering based on intensity, size, shape, and local background conditions. It aims to ensure that detected objects are valid and significant relative to the cell and the background, employing multiple criteria including intensity thresholds, kurtosis, ellipticity, area conditions, and signal-to-noise ratio (SNR).

Parameters:

original_img (numpy.ndarray) – The original image, before any processing.
processed_img (numpy.ndarray) – The processed image, potentially after enhancing objects or other preprocessing steps.
puncta_mask (numpy.ndarray) – A binary mask where the objects are identified, before refinement.
cell_mask (numpy.ndarray) – A binary mask of the cell(s), used to define the cell background and exclude non-cell areas.
labeled_puncta_mask (numpy.ndarray) – A labeled mask of the objects, where each punctum is assigned a unique label.
min_spot_radius (float) – The minimum radius of objects, used in various calculations and filtering criteria.

Returns:

refined_puncta_mask – The refined binary mask of objects after applying the filtering criteria.

Return type:

Notes

This function applies a series of criteria to refine detected objects, including: - Local and global intensity thresholds to remove false objects. - Kurtosis to filter out objects with flat pixel intensity distributions, which are likely false positives. - Area conditions to exclude objects that are too large or too small. - Ellipticity to remove objects that are too long and narrow. - Gradient and SNR conditions to ensure objects stand out from their background and are not indistinguishable from noise.

puncta_refinement_func(original_image, processed_image, puncta_mask, cell_mask, min_spot_radius=2)[source]#

Refines a puncta mask through a series of image processing steps, including smoothing, morphological operations, refinement filtering, and watershed segmentation. This function is designed to improve the accuracy of puncta detection and segmentation by reducing noise and separating closely positioned objects.

Parameters:

original_image (numpy.ndarray) – The original microscopy image, before any processing. This image is used to guide the refinement process and to apply the watershed segmentation.
processed_image (numpy.ndarray) – The processed image, which has potentially undergone preprocessing steps to enhance puncta or otherwise prepare the image for segmentation.
puncta_mask (numpy.ndarray) – A binary mask where puncta have been initially identified. This mask is subject to refinement through this function.
cell_mask (numpy.ndarray) – A binary mask of the cell(s) used to define areas of interest and exclude regions outside of cells.
min_spot_radius (float, optional) – The minimum radius of puncta, which influences several processing steps including smoothing and watershed segmentation. Default is 2.

Returns:

refined_mask – The refined binary mask of puncta after applying all processing and refinement steps.

Return type:

Notes

The refinement process includes: - Converting images to a suitable data type and smoothing based on the minimum spot size. - Applying binary opening to the initial puncta mask to remove single-pixel noise. - Labeling the puncta mask for individual puncta identification. - Refining the labeled puncta mask through custom filtering criteria (primarily based on the local intensity distribution aroud the object). - Separating closely positioned objects using watershed segmentation. - Further refining the segmentation to ensure accurate and distinct object detection, providing an iterative refinement approach. - Final morphological opening to clean up the segmentation result.

refine_labels_with_contours(refined_labels, min_area)[source]#

Refines segmentation masks for each label within a given input mask using contour detection and area filtering. This function iterates over each unique label in the input mask, extracts contours for each label using the specified minimum area criteria, and applies morphological operations to refine these contours.

Parameters:

refined_labels (numpy.ndarray) – The input mask containing different labels for segmented regions, typically obtained from segmentation algorithms.
min_area (int) – The minimum area threshold for contours to be considered during the refinement process. Only contours larger than this threshold are included.

Returns:

refined_masks – A list of refined masks for each label present in refined_labels. Each mask in the list corresponds to a unique label and contains the refined contours for that label.

Return type:

List[numpy.ndarray]

Notes

The function first segregates each label within the input mask and then applies opencv_contour_func to detect and draw contours that meet the specified area criteria. It further refines these contours using a binary morphological operation (e.g., opening) to smooth edges and remove small artifacts. If no valid objects are found for a label after processing, a message is printed, and the label is skipped in the output. The resulting refined masks are returned as a list, one for each label, ensuring that the refined contours correspond to the initial segmented regions.

run_cellpose_segmentation(image_layer, data_instance, viewer)[source]#

Applies cell segmentation to an image layer using Cellpose and displays the results in the Napari viewer.

Retrieves the necessary parameters from provided objects, executes cell segmentation with cellpose_segmentation, and integrates the resulting mask into the viewer as a new layer.

Parameters:

image_layer (napari.layers.Image) – The image layer to be segmented.
data_instance (object) – An object containing a data repository with segmentation parameters, such as ‘cell_diameter’.
viewer (napari.Viewer) – The viewer object where the segmentation results will be displayed.

run_fz_segmentation_and_merging(scale_input, sigma_input, min_size_input, viewer)[source]#

Applies Felzenszwalb’s segmentation and merging to an active image layer in a Napari viewer based on user-provided settings. This function allows for dynamic interaction, enabling users to adjust segmentation parameters in real-time.

Parameters:

scale_input (QLineEdit) – Input field for the scale parameter, affecting the size of the initial segmentation clusters.
sigma_input (QLineEdit) – Input field for the sigma parameter, controlling the degree of Gaussian smoothing prior to segmentation.
min_size_input (QLineEdit) – Input field for the minimum size of the segments to be considered in the final output.
viewer (napari.viewer.Viewer) – Viewer instance where the segmented image will be displayed.

Raises:

Error – If no active image layer is selected.

run_local_thresholding(k_slider, window_slider, mode_dropdown, viewer)[source]#

Applies local thresholding to an active image layer in a Napari viewer based on user inputs from sliders and a dropdown menu. The process uses either Niblack, Sauvola, or a combination of these methods to highlight areas of interest in the image.

Parameters:

k_slider (QSlider) – A slider widget to set the k-value for thresholding, adjusting the sensitivity of the method.
window_slider (QSlider) – A slider widget to set the window size for local threshold calculations.
mode_dropdown (QComboBox) – A dropdown to select the thresholding mode: ‘Niblack’, ‘Sauvola’, ‘AND’, or ‘OR’.
viewer (napari.viewer.Viewer) – The viewer instance where the processed image will be displayed.

Raises:

Error – If no active image layer is selected.

Notes

This function retrieves settings from the sliders and dropdown, applies the thresholding to the selected image, and updates the viewer by either adding a new layer or updating an existing one with the processed image.

run_segment_subcellular_objects(pre_processed_image_layer, original_image_layer, data_instance, viewer)[source]#

Orchestrates the segmentation and refinement of subcellular objects across all cells in an image. It utilizes the napari viewer for visualization and operates on pre-processed and original images to detect and refine objects such as puncta within cell masks.

Parameters:

pre_processed_image_layer (napari.layers.Image) – The pre-processed image layer, ready for segmentation.
original_image_layer (napari.layers.Image) – The original image layer before any processing.
data_instance (object) – An instance containing a data repository with necessary parameters such as ball_radius.
viewer (napari.Viewer) – The napari viewer instance used for adding the segmentation results as new layers.

Raises:

Warning – If the ‘Labeled Cell Mask’ layer is not present in the viewer, a warning is issued as the function is intended to be used after running the Cell Analyzer. If the layer is absent, the function will run on the entire image, which may lead to unintended behavior.

Notes

The function iterates over all cells, segments subcellular objects, and refines the segmentation. It relies on cell-specific metrics if available. The final segmentation masks for all cells are combined and added to the napari viewer as new layers for visualization and further analysis.

run_train_and_apply_rf_classifier(image_layer, label_layer, data_instance, viewer)[source]#

Facilitates the training and application of a Random Forest classifier on an image layer and displays the results in a Napari viewer.

This function extracts the necessary data from the provided image and label layers, trains a Random Forest classifier based on the training labels, and applies this classifier to segment the image. The segmented results are then displayed as new layers in the viewer.

Parameters:

image_layer (napari.layers.Image) – The layer containing the image data to be segmented.
label_layer (napari.layers.Labels) – The layer containing label data used for training the classifier.
data_instance (object) – An object containing additional parameters such as ‘cell_diameter’ needed for processing.
viewer (napari.Viewer) – The viewer in which to display the segmented results.

Notes

Multiple refined masks are displayed in separate layers if more than one valid object classification is found.

segment_subcellular_objects(original_image, pre_processed_image, cell_mask, cell_label, ball_radius, cell_df=None)[source]#

Segments and refines subcellular objects within a specified cell mask from microscopy images. The function uses pre-processed images and cell-specific metrics to remove background, enhance edges, and segment objects like puncta. It then refines the segmentation based on image quality metrics such as kurtosis and signal-to-noise ratio (SNR).

Parameters:

original_image (numpy.ndarray) – The original microscopy image before any processing.
pre_processed_image (numpy.ndarray) – The image after pre-processing steps, ready for segmentation.
cell_mask (numpy.ndarray) – A binary mask representing a single cell within which objects are to be segmented.
cell_label (int or float) – The label identifying the current cell within cell_df or used for reporting.
ball_radius (float) – The radius used in background removal and edge enhancement algorithms.
cell_df (pandas.DataFrame, optional) – A DataFrame containing cell-specific metrics such as kurtosis and SNR. Default is None.

Returns:

refined_puncta_mask (numpy.ndarray) – The refined binary mask of segmented subcellular objects.
puncta_mask (numpy.ndarray) – The initial binary mask of segmented subcellular objects before refinement.

Notes

This function applies background removal and edge enhancement before segmenting objects. It assesses the quality of segmentation using contrast checks and refines the segmentation through a separate refinement function to ensure accurate object detection.

train_and_apply_rf_classifier(image, training_labels, object_diameter)[source]#

Trains and applies a Random Forest classifier to segment an image based on training labels.

The function enhances the input image using adaptive histogram equalization and denoising techniques before training a Random Forest classifier. The classifier is then used to predict segmentation masks across the entire image. These masks are refined to improve the segmentation quality.

Parameters:

image (numpy.ndarray) – The input image for segmentation, expected to be in grayscale or compatible format.
training_labels (numpy.ndarray) – The ground truth labels for training the classifier, must be the same dimensions as the image.
object_diameter (int) – The approximate diameter of the target objects in pixels, used to tailor image preprocessing.

Returns:

refined_masks – A list of refined segmentation masks for each detected classification type, adjusted for segmentation quality.

Return type:

List[numpy.ndarray]

Notes

The segmentation process includes image preprocessing for feature enhancement, classifier training on specified regions, and applying this classifier to the whole image. The resulting masks are then refined through morphological operations and contour adjustments to produce the final segmented output.

Feature Analysis#

Image Feature Analysis Module for PyCAT

This module provides functions for analyzing image features, including texture, intensity, and shape properties. It supports the calculation of Gray Level Co-occurrence Matrix (GLCM) features, image entropy, kurtosis, and Local Binary Pattern (LBP) features. These functions provide insights into the texture and statistical properties of images and segmented regions, enabling detailed analysis and comparison of image data.

This is also the module where the cell and puncta analysis functions are located. These functions are designed to analyze segmented cells and puncta within cells, calculating various properties and statistics to provide insights into cell and sub-cellular object characteristics. The functions integrate image processing, segmentation, and feature calculation to facilitate comprehensive analysis of biological images. The results are stored in a data repository for further analysis and visualization.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

calculate_glcm_features(image, object_size, roi_mask=None, min_object_size=3)[source]#

Calculates Gray Level Co-occurrence Matrix (GLCM) features for an image using specified object size parameters and an optional region of interest (ROI) mask.

This function processes the image to extract texture features based on GLCM. It supports customization of the analysis area through an ROI mask and adjusts the calculation detail level using object size specifications.

Parameters:

image (numpy.ndarray) – The input image for which to calculate GLCM features. Expected to be in a compatible format.
object_size (int) – Defines the scale of the object in the image to determine the calculation granularity.
roi_mask (numpy.ndarray, optional) – A binary mask that specifies the region of interest within the image. If None, the entire image is analyzed.
min_object_size (int, optional) – The minimum size for objects when calculating distances in GLCM, defaults to 3.

Returns:

features_df – A DataFrame containing the calculated GLCM features for each combination of distance and angle.

Return type:

Notes

The function performs several preprocessing steps on the image, including rescaling and conversion to 8-bit. It computes GLCM over a range of distances and angles based on the specified object size and extracts features such as contrast, dissimilarity, homogeneity, ASM, energy, and correlation from the GLCM. The results are averaged over all angles and distances and returned in a DataFrame for easy analysis.

calculate_image_entropy(image, ball_radius, roi_mask=None)[source]#

Calculates the entropy of an image using a local neighborhood defined by a specified ball radius, and optionally, within a region of interest (ROI). This function processes the image at multiple bit-depths to derive entropy measures that reflect the complexity and texture variations across the image.

Parameters:

image (numpy.ndarray) – The input image on which entropy calculations are to be performed. Expected to be in a compatible format.
ball_radius (int) – The radius of the structuring element (ball) used to calculate local entropy within the image.
roi_mask (numpy.ndarray, optional) – A binary mask that defines the region of interest within the image. If None, the entire image is considered.

Returns:

entropy_df – A DataFrame containing the calculated entropy values for the image at different bit-depths and local entropy averaged over the specified ROI.

Return type:

Notes

The entropy calculation includes: - Conversion of the image to 8-bit and 32-bit formats for entropy analysis. - Calculation of global entropy for both 8-bit and 32-bit images to assess overall randomness. - Calculation of mean local entropy using a ball structuring element, which highlights local variations in image texture. The results are presented in a DataFrame, facilitating easy comparison and further analysis.

calculate_image_features(image, data_instance, roi_mask=None)[source]#

Calculate a comprehensive set of features for an image, combining various texture and statistical analyses. This function orchestrates the computation of Gray Level Co-occurrence Matrix (GLCM) features, image entropy, kurtosis, and Local Binary Pattern (LBP) features. It requires a data instance object for accessing global parameters relevant to the feature calculations.

Parameters:

image (numpy.ndarray) – The input image array. This is the primary data on which all feature calculations are based.
data_instance (object) – An object containing a data repository with parameters like object_size and ball_radius which are used in the feature calculation processes.
roi_mask (numpy.ndarray, optional) – A boolean array of the same shape as image to define the region of interest within the image. If None (default), the entire image is considered.

Returns:

image_features_df – A pandas DataFrame aggregating the features calculated by the individual functions. This DataFrame provides a comprehensive overview of the image’s texture and statistical properties.

Return type:

Notes

The function leverages other specialized feature calculation functions, each focusing on a different aspect of image analysis. The resulting feature DataFrames from these functions are concatenated to form a single, comprehensive DataFrame that encompasses a wide range of image characteristics. This approach allows for a holistic analysis of the image based on multiple feature sets.

calculate_image_kurtosis(image, roi_mask=None)[source]#

Calculate the kurtosis of pixel intensity values within an image, optionally within a specified region of interest (ROI). The function applies data type conversion, intensity scaling, outlier removal, and finally computes the kurtosis and other statistical measures.

Parameters:

image (numpy.ndarray) – The input image array. The image can be of any dimensional shape but must be compatible with the provided roi_mask if used.
roi_mask (numpy.ndarray, optional) – A boolean array of the same shape as image that defines the ROI within the image. If None (default), the entire image is considered as the ROI.

Returns:

kurtosis_df – A pandas DataFrame containing the calculated kurtosis, standardized sixth moment, kurtosis z-score, and p-value of the kurtosis test. Each of these metrics provides insights into the distribution of pixel intensities within the specified ROI.

Return type:

Notes

The function internally converts the image to 32-bit floating point for processing, and then to 16-bit unsigned integer for compatibility with kurtosis calculations. It also applies an intensity rescaling and outlier removal based on the interquartile range. The Laplace distribution has a heavier tail (higher kurtosis) than the normal distribution. The uniform distribution (which has negative kurtosis) has the thinnest tail.

calculate_lbp_features(image, roi_mask=None, min_object_size=3)[source]#

Calculate Local Binary Pattern (LBP) features of an image, within an optional region of interest (ROI). This function processes the image to compute LBP histograms and derives statistical measures from these histograms, such as mean, standard deviation, and entropy of the LBP distribution.

Parameters:

image (numpy.ndarray) – The input image array. The image can be of any dimensional shape.
roi_mask (numpy.ndarray, optional) – A boolean array of the same shape as image that defines the ROI within the image. If None (default), the entire image is considered as the ROI.
min_object_size (int, optional) – The minimum size of objects to consider within the image for LBP calculations. Defaults to 3.

Returns:

lbp_features_df – A pandas DataFrame containing statistical measures derived from the LBP histogram, including mean, standard deviation, and entropy.

Return type:

Notes

The function performs several preprocessing steps on the image: conversion to 32-bit floating point for numerical stability, rescaling of intensity values, conversion to 8-bit for compatibility with LBP computation, and application of the ROI mask. The LBP histogram is computed within the ROI, and the resulting features provide insights into the texture of the image within this region.

cell_analysis_func(image, cell_masks, omission_mask, data_instance)[source]#

Analyzes segmented cells in a greyscale image by calculating various intensity and shape statistics for each cell. It leverages a binary mask to identify cell regions and performs statistical analysis on these regions to generate insights into cell characteristics. Optionally, an omission mask can be provided to exclude specific areas from the analysis.

Parameters:

image (numpy.ndarray) – The original grayscale image from which cell properties are derived.
cell_masks (numpy.ndarray) – A binary mask indicating regions identified as cells for segmentation and analysis.
omission_mask (numpy.ndarray, optional) – A mask that specifies regions to be excluded from the analysis, if provided.
data_instance (object) – An object that contains relevant analysis parameters, such as cell diameter and pixel size, stored within a data repository.

Returns:

labeled_cells (numpy.ndarray) – An image with unique labels for each segmented cell, facilitating individual analysis.
final_df (pandas.DataFrame) – A DataFrame containing statistical information about each segmented cell, including metrics like cell area, average intensity, eccentricity, and others derived from the segmented regions.

Notes

This function integrates multiple image processing and analysis steps: - Converts the cell mask to a binary format and applies contour detection based on a minimum cell area. - Enhances cell contours using morphological operations to improve segmentation accuracy. - Optionally applies an omission mask to exclude certain areas from analysis. - Calculates statistical metrics such as intensity mean, standard deviation, median, and total intensity, along with additional features for each segmented cell. - Utilizes background noise estimations to compute signal-to-noise ratios (SNRs) for the cells. - Aggregates all computed data into a comprehensive DataFrame that includes intensity statistics and additional calculated features, enhancing insights into cell characteristics within the analyzed image.

puncta_analysis_func(puncta_masks, image, labeled_cells, data_instance)[source]#

Analyzes sub-cellular objects within segmented cells, calculating properties of puncta such as area, intensity, and shape metrics. It associates puncta with their respective cells, computes various statistics on the puncta distribution within cells, and updates the cell DataFrame with these statistics.

Parameters:

puncta_masks (numpy.ndarray) – A binary mask indicating the locations of puncta within the image.
image (numpy.ndarray) – The original greyscale image from which puncta properties are to be measured.
labeled_cells (numpy.ndarray) – An image with cells labeled by unique integers, used to associate puncta with specific cells.
data_instance (object) – An object that provides access to a data repository for storing and retrieving analysis results.

Returns:

cell_labeled_puncta – An image where puncta are labeled according to the cell they belong to.

Return type:

Notes

This function iterates through each labeled cell, identifying and labeling puncta within each cell. It calculates puncta properties (area, intensity mean, etc.) and custom metrics such as ellipticity and circularity. These metrics, along with cell-specific puncta statistics (like total puncta intensity and mean puncta area), are stored in the cell DataFrame. This function is designed to work as part of a larger analysis pipeline, specifically after cell segmentation and labeling have been performed.

run_cell_analysis_func(mask_layer, omit_mask_layer, image_layer, data_instance, viewer)[source]#

Orchestrates comprehensive cell analysis by leveraging mask and image layers in Napari. It ensures mask and image compatibility, performs cell segmentation and analysis, and visualizes results in the viewer, while saving the data for further use in the active data class’ data repository.

Parameters:

mask_layer (napari.layers.Labels) – The layer containing binary mask data that differentiates cell regions from the background.
omit_mask_layer (napari.layers.Labels, optional) – An optional layer containing masks of regions to omit from the analysis, if provided.
image_layer (napari.layers.Image) – The layer containing the original grayscale image data used for analysis.
data_instance (object) – An object encapsulating a repository for storing analysis results and other relevant data.
viewer (napari.Viewer) – The viewer object used for displaying analysis results, including labeled segmented cells and statistics.

Notes

This function serves as the main entry point for conducting cell analysis. It ensures that the provided mask and image layers are compatible in shape. It then proceeds to segment and analyze the cells based on the provided mask, storing the results for future reference. The segmented cells are visualized in the viewer, and a dialog is presented with the cell statistics, facilitating an interactive analysis experience.

run_puncta_analysis_func(puncta_mask_layer, image_layer, data_instance, viewer)[source]#

Orchestrates the workflow for analyzing puncta within labeled cells in an image. This function assumes that cell segmentation has been previously conducted and labeled cell masks are available. It utilizes the puncta mask and the original image to perform puncta analysis, integrating the results with the cell data, and then updates the viewer with new layers showing the analysis results.

Parameters:

puncta_mask_layer (napari.layers.Labels) – Layer containing the binary masks of puncta. Each punctum is represented as a distinct region in the binary mask.
image_layer (napari.layers.Image) – Layer containing the original image data used for intensity measurements of puncta and cells.
data_instance (object) – An instance containing a data repository where analysis results are stored and retrieved.
viewer (napari.Viewer) – The viewer object used for visualizing analysis results. New layers will be added to this viewer to display the outcomes of the puncta analysis.

Raises:

ValueError – If the cell segmentation and puncta masks are not available, an error is raised to indicate the missing data.

Notes

This function directly modifies the viewer by adding new layers to visualize the results of the puncta analysis. It requires that the cell segmentation has been previously done to correctly associate puncta with their respective cells. It raises warnings if the prerequisites are not met, ensuring the user is aware of the expected workflow.

Correlation Analysis#

Correlation Function Analysis Module for PyCAT

This module provides functions for computing and analyzing cross-correlation functions (CCF) between two arrays or images. The CCF is a measure of similarity between two signals or images as a function of a shift applied to one of them. The module includes functions for computing 1D and 2D CCFs, fitting Gaussian models to the CCFs, and visualizing the results. It also provides utilities for preparing the results in a structured format for further analysis and reporting.

This module alos provides functions for computing the auto-correlation function (ACF) of a single image and fitting Gaussian models to the ACF. The ACF is a measure of the similarity of an image with itself as a function of a shift applied to the image. The ACF can be used to estimate the size of features in the image.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

autocorrelation_analysis(image, roi_mask, lower_limit, upper_limit, micron_resolution, label_flag=False)[source]#

Performs detailed autocorrelation analysis on an image, optionally utilizing a region of interest (ROI), and provides outputs including Gaussian fit parameters for both 1D and 2D analyses.

This function calculates the 2D autocorrelation of the image or its ROI, extracts specific regions based on given limits for further analysis, fits Gaussian models to these extracted regions in both 1D (central horizontal slice) and 2D, and plots these results.

Parameters:

image (numpy.ndarray) – The image data on which autocorrelation analysis is performed. Should be a 2D numpy array.
roi_mask (numpy.ndarray or None) – A binary mask defining the ROI within the image. If None, the entire image is analyzed.
lower_limit (int) – The lower limit for calculating indices and plot limits in the autocorrelation function. This affects the range of autocorrelation data to be analyzed and visualized.
upper_limit (int) – The upper limit for the same purposes as the lower limit.
micron_resolution (float) – The resolution of the image in microns per pixel. This is used to scale the dimensions of the results in the output, converting pixel measurements to microns.
label_flag (bool) – If False, results of the analysis (such as the 2D autocorrelation function and Gaussian fits) are plotted. If True, plotting is skipped; useful for batch processing or when visualization is not required.

Returns:

acf_values_df (pandas.DataFrame) – DataFrame of the autocorrelation values, suitable for further analysis or export.
fitted_params_df_2d (pandas.DataFrame) – DataFrame containing the parameters from the 2D Gaussian fit, along with their covariances, and scaled object dimensions in microns.
fitted_params_df_1d (pandas.DataFrame) – DataFrame containing the parameters from the 1D Gaussian fit, along with their covariances, and the scaled object diameter in microns.

Notes

The function is designed to handle various types of image data and can accommodate different analysis scenarios through its parameters. It integrates several computational steps such as ROI application, autocorrelation computation, Gaussian fitting, and optional visualization, providing a comprehensive tool for image analysis.

This method is typically used to determine ‘cluster’ or (blob like) object sizes in the image data, where the ACF values are indicative of the spatial distribution of pixel intensities. It is useful in quantifying the size of objects which are not well defined in terms of their boundary. For condensates, many kinds of aggregates, clumps, clusters, and other objects, especially in in-cellulo data, are not well defined spherical droplets and therefore this becomes an invaluable analysis tool; particularly useful for ‘pre-determining’ the size of objects before using other PyCAT methods to segment them.

calculate_autocorrelation(image)[source]#

Calculate the autocorrelation of an image using Fourier transforms. This method exploits the Wiener-Khinchin theorem, which states that the autocorrelation function of a signal can be obtained by taking the inverse Fourier transform of the power spectrum (magnitude squared of the Fourier transform) of the signal.

Parameters:: image (numpy.ndarray) – The input image for which the autocorrelation is to be computed. This should be a 2D numpy array representing pixel intensities.
Returns:: shifted_autocorrelation – The shifted autocorrelation function of the input image, normalized to [0, 1]. The zero-frequency component is shifted to the center of the array, providing a more intuitive visual representation of the autocorrelation function.
Return type:: numpy.ndarray

Notes

The autocorrelation function computed here provides a measure of how the image correlates with itself as it is translated over itself. High values in the autocorrelation function indicate high similarity or redundancy at the corresponding shift values.

calculate_indices_and_plot_limits(acf_shape, lower_limit, upper_limit)[source]#

Calculate the indices for accessing array elements based on specified limits and determine the plot limits for visualization within an autocorrelation function (ACF) array.

This function translates a coordinate system centered around zero (used for specifying limits) to an array index system, ensuring the indices and plot limits do not exceed the dimensions of the ACF or a default plotting range. It effectively manages the translation from a potentially negative data range to positive-only index space used in array slicing.

Parameters:

acf_shape (tuple of int) – Shape of the ACF array, expected as (height, width).
lower_limit (int or None) – The lower bound for both x and y indices in the coordinate system centered around zero. If None, defaults to half the negative shape dimension to center the view.
upper_limit (int or None) – The upper bound for both x and y indices in the coordinate system centered around zero. If None, defaults to half the positive shape dimension to center the view.

Returns:

(tuple of int): Lower and upper x indices (inclusive) for ACF array slicing.
(tuple of int): Lower and upper y indices (inclusive) for ACF array slicing.
(tuple of int): Lower and upper x limits for plotting.
(tuple of int): Lower and upper y limits for plotting.

Return type:

tuple

Notes

This function is designed to adapt the indices for practical use in Python arrays, where indices must be non-negative. The plot limits are set with a default range but adapt based on the provided limits to enhance visualization flexibility.

ccf_analysis(image1, image2, roi_mask, label_flag=False)[source]#

Performs cross-correlation function (CCF) analysis on two images and processes the results depending on the dimensionality (1D or 2D) of the images. It optionally skips the plotting of results based on the label_flag, which is useful for batch processing or when visual output is unnecessary.

Parameters:

image1 (numpy.ndarray) – The first input image for CCF analysis. Must be of the same dimension as image2.
image2 (numpy.ndarray) – The second input image for CCF analysis. Must be of the same dimension as image1.
roi_mask (numpy.ndarray) – A binary or labeled array indicating the region of interest (ROI) within the images.
label_flag (bool, optional) – If True, skips the plotting of results. This is particularly useful for automated batch processing where visual output is not required. Default is False.

Returns:

fitted_params_df (pandas.DataFrame) – DataFrame containing the fitted Gaussian parameters and their covariance, structured for further analysis.
raw_params_df (pandas.DataFrame) – DataFrame containing the raw CCF parameters and values, providing the basic outputs of the CCF analysis.

Notes

The function handles different dimensionalities by checking the shape of image1. If process_ccf returns None, it indicates an unsuccessful fit, possibly due to inadequate correlation, and results in empty DataFrames being returned. Ensure that process_ccf and other utility functions are correctly implemented and that the data passed to them conforms to expected structures.

fit_gaussian_1d(ccf_values, shifts)[source]#

Fits a Gaussian function to 1D cross-correlation function values to determine the peak and width of the correlation.

Parameters:

ccf_values (numpy.ndarray) – The cross-correlation function values obtained from shifting one array over another.
shifts (numpy.ndarray) – The array of shift values corresponding to each CCF value.

Returns:

results – A dictionary containing the results of the Gaussian fitting (parameters and diagnostics) or None if the fitting fails.

Return type:

dict or None

Notes

The Gaussian fitting process assumes a bell-shaped curve typical for cross-correlation functions in signal processing. This function uses the curve_fit method from scipy.optimize to perform the fitting. The initial guesses for the Gaussian parameters are determined based on the properties of the CCF values.

fit_gaussian_1d_acf(acf_values, shifts)[source]#

Fits a Gaussian function to 1D autocorrelation function (ACF) values. This method is typically used to determine ‘cluster’ sizes in the image data, where the ACF values are indicative of the spatial distribution of pixel intensities. In reality it is a noisy piecewise gaussian function, but this offset allows us to look at different parts of the ACF without such a complicated model.

Parameters:

acf_values (numpy.ndarray) – The autocorrelation function values obtained by correlating a signal with itself at varying shifts.
shifts (numpy.ndarray) – The corresponding values of pixels at which the autocorrelation was computed. These ‘shifts’ are used as the x-values for Gaussian fitting.

Returns:

results – A dictionary containing the results of the Gaussian fitting (parameters and diagnostics) or None if the fitting fails.

Return type:

dict or None

fit_gaussian_2d(ccf_values, x, y)[source]#

Fits a 2D Gaussian function to the computed cross-correlation function values to determine the peak correlation and its distribution in two dimensions.

Parameters:

ccf_values (numpy.ndarray) – The 2D cross-correlation function values obtained from comparing two arrays.
x (numpy.ndarray) – The x-coordinates of the shifts applied during the cross-correlation calculation.
y (numpy.ndarray) – The y-coordinates of the shifts applied during the cross-correlation calculation.

Returns:

results – A dictionary containing the results of the Gaussian fitting, including parameters and diagnostics, or None if the fitting fails.

Return type:

dict or None

Notes

The fitting process assumes a symmetric Gaussian distribution, typical for peak correlation distributions. This method uses curve fitting techniques from scipy.optimize to find the best fit parameters.

gaussian_1d(x, amplitude, mean, stddev)[source]#

Computes a one-dimensional Gaussian function, often used to model the distribution of data.

Parameters:

x (numpy.ndarray) – The input values over which the Gaussian function is computed.
amplitude (float) – The peak amplitude of the Gaussian function.
mean (float) – The mean (center) of the Gaussian function, where the peak occurs.
stddev (float) – The standard deviation of the Gaussian, determining the width of the bell curve.

Returns:

The values of the Gaussian function evaluated at ‘x’.

Return type:

Example

>>> gaussian_1d(np.array([1, 2, 3]), amplitude=1, mean=2, stddev=1)
array([0.60653066, 1.        , 0.60653066])

gaussian_1d_offset(x, amplitude, mean, stddev, dc_offset)[source]#

Computes a one-dimensional Gaussian function with an offset, which is commonly used to model distributions of data where a non-zero baseline might be present due to background noise or other baseline shifts.

Parameters:

x (numpy.ndarray) – The input values over which the Gaussian function is computed.
amplitude (float) – The peak amplitude of the Gaussian function. This is the height of the peak above the dc_offset.
mean (float) – The position (mean or center) of the peak of the Gaussian curve.
stddev (float) – The standard deviation of the Gaussian function, describing the width of the bell-shaped curve.
dc_offset (float) – A constant value added to the entire function, representing a baseline offset from zero.

Returns:

The computed Gaussian function values for each element in x, adjusted by the dc_offset.

Return type:

gaussian_2d(xy, amplitude, x0, y0, sigma_x, sigma_y)[source]#

Computes a two-dimensional Gaussian function, often used in image processing to generate Gaussian blurs.

Parameters:

xy (tuple of numpy.ndarray) – A pair of arrays (x, y) representing the meshgrid coordinates over which the Gaussian function is computed.
amplitude (float) – The peak amplitude of the Gaussian function.
x0 (float) – The center of the Gaussian function in x and y dimensions.
y0 (float) – The center of the Gaussian function in x and y dimensions.
sigma_x (float) – The standard deviations (widths) of the Gaussian function in x and y dimensions.
sigma_y (float) – The standard deviations (widths) of the Gaussian function in x and y dimensions.

Returns:

The values of the Gaussian function evaluated over the 2D space defined by ‘xy’.

Return type:

Example

>>> x = np.linspace(-1, 1, 3)
>>> y = np.linspace(-1, 1, 3)
>>> xx, yy = np.meshgrid(x, y)
>>> gaussian_2d((xx, yy), amplitude=1, x0=0, y0=0, sigma_x=1, sigma_y=1)
array([[0.36787944, 0.60653066, 0.36787944],
       [0.60653066, 1.        , 0.60653066],
       [0.36787944, 0.60653066, 0.36787944]])

plot_1d_auto_correlation(autocorrelation, x_lims, gaussian_params_df, title='Central Slice of ACF')[source]#

Plot a 1D slice of the autocorrelation function along with a fitted Gaussian curve to analyze the distribution along a single dimension.

Parameters:

autocorrelation (ndarray) – The autocorrelation array, expected to be 2D, from which a central slice will be extracted and plotted.
x_lims (tuple) – The x-axis limits for the plot, specified as a tuple (min, max) to define the visible range.
gaussian_params_df (DataFrame) – DataFrame containing the parameters for the Gaussian fit, specifically values for amplitude, mean (mu), and standard deviation (sigma) of the Gaussian.
title (str, optional) – The title of the plot. Default is “Central Slice of ACF”.

Notes

This function plots both the actual data from the central slice of the autocorrelation function and the Gaussian fit, facilitating comparisons between the model and empirical data.

plot_1d_results(results)[source]#

Plots the 1D cross-correlation function (CCF) and its Gaussian fit. This visualization includes the original CCF values and the Gaussian model overlaid to show the fitting quality.

Parameters:: results (dict) – A dictionary containing the results of the 1D CCF analysis. This must include ‘shifts’, ‘ccf_values’, ‘gaussian_params’, and ‘r_squared’ among other possible keys.

plot_2d_autocorrelation(autocorrelation, x_lims, y_lims, title='2D Autocorrelation Function')[source]#

Plot a 2D visualization of the autocorrelation function, highlighting spatial relationships and symmetries.

Parameters:

autocorrelation (numpy.ndarray) – The autocorrelation array to be plotted, expected to be a 2D numpy array representing autocorrelation values.
x_lims (tuple) – The x-axis limits for the plot, specified as a tuple (min, max) to define the visible range.
y_lims (tuple) – The y-axis limits for the plot, specified as a tuple (min, max) to define the visible range.
title (str, optional) – The title of the plot. Default is “2D Autocorrelation Function”.

Notes

The plot is configured with a color map and boundaries defined by the shape of the autocorrelation array, centered around the middle of the array. It uses matplotlib for plotting.

plot_2d_results(results)[source]#

Plots the 2D cross-correlation function (CCF) and its Gaussian fit. The function generates two subplots: one for the original CCF and another for the fitted Gaussian function, both with colorbars to assist in interpretation.

Parameters:: results (dict) – A dictionary containing the results of the 2D CCF analysis. This includes ‘shifts’, ‘ccf_values’, and ‘gaussian_params’ among other possible keys.

plot_acf_image(image, title='Image', cmap='CMRmap')[source]#

Plot an image using a specified colormap, providing visual insights into the spatial structures of the image.

Parameters:

image (ndarray) – The image to plot, typically a 2D numpy array of pixel intensities.
title (str, optional) – The title for the plot. Default is “Image”.
cmap (str, optional) – The colormap to use for the plot. Default is ‘CMRmap’, which is suitable for highlighting features in autocorrelation data.

Notes

This plot function is designed for general-purpose image visualization with an emphasis on flexibility in colormap choice. It employs matplotlib’s imshow function for rendering.

prepare_1d_result_dfs(results)[source]#

Prepares pandas DataFrames for both the raw CCF values and the fitted Gaussian parameters from the results of 1D cross-correlation analysis. This facilitates easier analysis and visualization of the CCF fitting results.

Parameters:

results (dict) – A dictionary containing the results of the 1D CCF analysis, including Gaussian fitting parameters and their goodness of fit, among other metrics.

Returns:

fitted_params_df (pandas.DataFrame) – DataFrame containing the names and values of the fitted Gaussian parameters along with their covariance.
raw_params_df (pandas.DataFrame) – DataFrame containing the names and values of raw CCF metrics, including peak amplitude and location.

Notes

Ensure that all expected keys are present in the results dictionary to avoid KeyError.

prepare_2d_result_dfs(results)[source]#

Prepares pandas DataFrames for both the raw CCF values and the fitted Gaussian parameters from the results of 2D cross-correlation analysis. These DataFrames organize the CCF and Gaussian fitting results, making them more accessible for further analysis and reporting.

Parameters:

results (dict) – A dictionary containing the results of the 2D CCF analysis, including Gaussian fitting parameters and their goodness of fit, among other metrics.

Returns:

fitted_params_df (pandas.DataFrame) – DataFrame containing the names and values of the fitted Gaussian parameters along with their covariance.
raw_params_df (pandas.DataFrame) – DataFrame containing the names and values of raw CCF metrics, such as peak amplitude and locations along both axes.

Notes

This function assumes that the results dictionary contains all necessary keys and values. Missing keys will result in KeyError.

process_ccf(array1, array2, roi_mask)[source]#

Performs cross-correlation analysis on 1D or 2D arrays with optional region of interest (ROI) masking. This function calculates the cross-correlation function (CCF) and fits a Gaussian model to it.

Parameters:

array1 (numpy.array) – The first input array for correlation analysis. Must be of the same dimension as array2.
array2 (numpy.array) – The second input array for correlation analysis. Must be of the same dimension as array1.
roi_mask (numpy.array, optional) – An optional mask to specify the region of interest within the arrays. If not provided, the entire array is considered.

Returns:

results – A dictionary containing the results of the CCF analysis and Gaussian fitting. This includes CCF values, Gaussian parameters, and other relevant metrics depending on whether the analysis was 1D or 2D.

Return type:

dict

Raises:

ValueError – If the dimensions of the input arrays are neither 1D nor 2D.

run_autocorrelation_analysis(image_layer, roi_mask_layer, lower_lim_input, upper_lim_input, data_instance)[source]#

Coordinates the autocorrelation analysis of an image using optional ROI masks and manages the presentation and storage of results within a specified data framework. This function extracts image and ROI mask data, handles GUI inputs for analysis bounds, and performs autocorrelation analysis with proper Gaussian fitting. The results are displayed in a custom dialog and stored for later retrieval.

Parameters:

image_layer (napari.layers.Image) – An object containing the image data to be analyzed. Expected to provide access to 2D numpy array data.
roi_mask_layer (napari.layers.Labels or None) – An object containing the ROI mask data, if applicable. If None, no ROI mask is applied.
lower_lim_input (QLineEdit (textbox)) – GUI input element for specifying the lower limit of index calculations, affecting the range of autocorrelation analysis.
upper_lim_input (QLineEdit (textbox)) – GUI input element for specifying the upper limit of index calculations, similar to lower_lim_input.
data_instance (object) – A custom object for managing the storage and retrieval of analysis data, including results of the autocorrelation analysis.

Raises:

ValueError – If the image and ROI mask do not have the same shape, preventing proper analysis.

Notes

This function is capable of handling both labeled and binary ROI masks, adjusting its processing logic accordingly to provide detailed and scalable analysis results. The results are displayed in a dialog for easy access and interpretation.This method is typically used to determine ‘cluster’ or (blob like) object sizes in the image data. Since there are often objects of various size domains, the function is really a piecewise gaussian, here we recommend using pre-processing and ROI masking to narrow down the analysis to specific objects of interest. However, in the event that is not feasible, we provide the limit inputs to allow the user to focus on specific size regimes of interest. You can run the function, look at the domains in the 1D ACF and then re-run with different limits to focus on specific size regimes.

run_ccf_analysis(image_layer1, image_layer2, roi_mask_layer, data_instance)[source]#

Orchestrates the cross-correlation function (CCF) analysis for pairs of image layers, handling different types of ROI masks (binary or labeled) and integrating results into a specified data management object. It supports handling multiple ROI labels and aggregates results in a consistent format for analysis and visualization.

Parameters:

image_layer1 (napari.layers.Image) – The first image layer containing data for CCF analysis.
image_layer2 (napari.layers.Image) – The second image layer containing data for CCF analysis.
roi_mask_layer (napari.layers.Labels or None) – The image layer containing the ROI mask data. Can be None if no ROI is to be applied.
data_instance (object) – An object that stores and manages the results of the CCF analysis, typically having a ‘data_repository’ attribute for storing results data.

Raises:

ValueError – If the input images do not have the same shape, or if the ROI mask does not match the dimensions of the images.

Notes

The function processes labeled masks by isolating each label into its own binary mask and performs CCF analysis separately for each. The results are then aggregated. For binary masks or the absence of a mask, analysis is done directly. Results are displayed in a custom dialog and stored in the provided data instance.

The function updates the data_instance.data_repository with two key DataFrames: - CCF_fitted_params_df: Contains the fitted Gaussian parameters - CCF_raw_params_df: Contains the raw CCF parameters

smooth_array(array, window_size=3)[source]#

Applies a moving average filter to smooth the input array. This is commonly used to reduce noise in a signal.

Parameters:

array (numpy.ndarray) – The input array to be smoothed. Can be any one-dimensional array of numerical values.
window_size (int, optional) – The size of the moving average window, specifying how many elements are averaged to compute the smoothed value. Defaults to 3.

Returns:

The smoothed array, which will have the same shape as the input array. Edges of the array will be less affected by the averaging due to boundary effects in the convolution.

Return type:

Example

>>> smooth_array(np.array([1, 2, 3, 4, 5]), window_size=3)
array([1.33333333, 2.        , 3.        , 4.        , 3.66666667])

Pixel-Wise Correlation Coefficient Analysis (PWCA) Module for PyCAT

This module contains functions for pixel-wise correlation analysis, including Pearson’s correlation, Spearman’s correlation, Kendall’s Tau, and Costes’ thresholding method for colocalization analysis. It also provides tools for generating cross-correlation matrices, calculating intensity correlation coefficients, and scrambling pixels for testing statistical significance purposes. The module includes functions for visualizing correlation results, such as scatter plots, cytofluorograms, and histograms for intensity correlation analysis.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

class pwcaDialog(parent=None)[source]#

Bases: QDialog

A PyQt dialog window designed for the selection of correlation analysis methods within the Napari pyQT application. This dialog provides checkboxes grouped by different types of analysis such as Correlation Coefficient Analysis (CCA), Modified Costes Analysis (MCA), Correlation Matrix Analysis (CMA), and Intensity Correlation Plots. Users can select, deselect, accept, or cancel their choices, making it versatile for varied analytical needs.

checkboxes#

A list of QCheckBox widgets used to enable selection of different analysis methods.

Type:: list

Parameters:: parent (QWidget, optional) – The parent widget of this dialog, typically the main window of the application. Defaults to None.

_create_section_layout(title, options):: Helper method to create a section with checkboxes based on the provided title and list of options.

_create_selection_buttons():: Helper method to create layout with ‘Select All’ and ‘Deselect All’ buttons.

_create_action_buttons():: Helper method to create layout with ‘OK’ and ‘Cancel’ buttons.

select_all():: Selects all checkboxes within the dialog.

deselect_all():: Deselects all checkboxes within the dialog.

get_selected_methods():: Returns a list of the selected analysis methods based on the checkboxes that are checked.

__init__(parent=None)[source]#: Initializes the pwcaDialog with various sections for selecting correlation analysis methods, including buttons for selecting all options, deselecting all, accepting the selection, or cancelling.

deselect_all()[source]#: Deselects all checkboxes within the dialog.

get_selected_methods()[source]#

Retrieves the list of analysis methods that have been selected by the user. This method checks the state of each checkbox to compile a list of chosen methods.

Returns:: A list containing the labels of the selected checkboxes, representing the user’s chosen analysis methods.
Return type:: list of str

select_all()[source]#: Selects all checkboxes within the dialog.

costes_linear_model(x, a, b)[source]#

Defines a linear model y = ax + b for fitting in Costes’ thresholding algorithm, which is used to analyze the relationship between the intensity values of two fluorescence channels.

Parameters:

x (numpy.ndarray) – An array of x-values, which are the intensity values of one channel (e.g., red channel).
a (float) – The slope of the linear model, representing the rate of change in y relative to x.
b (float) – The intercept of the linear model, representing the y-value when x is zero.

Returns:

The computed y-values for each x-value, based on the linear model.

Return type:

Notes

This function is used within a curve fitting procedure to determine the optimal linear relationship between two fluorescence channels, which is a critical step in Costes’ automatic thresholding for colocalization analysis.

costes_thresholding(red_channel, green_channel, roi_mask)[source]#

Applies Costes’ thresholding method to determine intensity thresholds above which there is significant colocalization between two fluorescence channels, typically used in microscopy images.

Parameters:

red_channel (numpy.ndarray) – A 2D array representing the red channel of an image, where the colocalization is to be analyzed.
green_channel (numpy.ndarray) – A 2D array representing the green channel of an image, where the colocalization is to be analyzed.
roi_mask (numpy.ndarray or None) – A boolean mask indicating the region of interest. If None, the entire image is considered for analysis.

Returns:

threshold_red (float) – The calculated threshold for the red channel above which significant colocalization is observed.
threshold_green (float) – The calculated threshold for the green channel above which significant colocalization is observed.

Notes

The method iteratively finds the optimal thresholds by fitting a linear model to the intensities of the two channels and then calculating Pearson correlation coefficients. The process aims to maximize the correlation by excluding pixels below the thresholds that contribute insignificantly to the overall correlation, ensuring only significant colocalized signals are considered. This method assumes a primarily positive correlation between the channels and will not be effective for negatively correlated images.

cross_correlation_matrix(image1, image2, roi_mask=None)[source]#

Computes the cross-correlation matrix for two images to assess the degree to which they are correlated with each other at different shifts and displacements. Optionally, the computation can be confined to a specified region of interest (ROI). Additionally, this function calculates the peak value of the cross-correlation matrix, identifies its location, and determines the mean squared error (MSE) between the two images, providing a comprehensive assessment of their similarity.

Parameters:

image1 (numpy.ndarray) – The first input image, expected to be a 2D array.
image2 (numpy.ndarray) – The second input image, expected to be of the same dimensions as image1.
roi_mask (numpy.ndarray, optional) – An optional boolean array of the same shape as image1 and image2, indicating the region of interest. If provided, calculations are restricted to the masked area.

Returns:

cc_scipy (numpy.ndarray) – The cross-correlation matrix, rounded to four decimal places.
peak_value (float) – The peak value of the cross-correlation matrix, rounded to four decimal places.
peak_location (tuple) – The (y, x) location of the peak value within the matrix.
mse (float) – The mean squared error (MSE) between the two images, rounded to four decimal places.

Notes

Cross-correlation is a measure of similarity between two signal sources as a function of the displacement of one relative to the other. This function is particularly useful in applications where alignment or similarity between two images needs to be evaluated, such as in image registration or tracking. The calculation of MSE provides an additional metric for assessing the direct pixel-wise differences between the images.

cytofluorogram_plot(image1, image2)[source]#

Creates a cytofluorogram by plotting the intensity values of one image against those of another, typically used in cellular studies to compare two different fluorescence markers.

Parameters:

image1 (numpy.ndarray) – Intensity values of the first image.
image2 (numpy.ndarray) – Intensity values of the second image.

Notes

A cytofluorogram is a scatter plot that is useful for visualizing the correlation between the fluorescence intensities of two distinct images, facilitating the analysis of how these intensities vary in relation to each other.

kendall_tau_calculation(image1, image2, roi_mask)[source]#

Calculates Kendall’s Tau, a non-parametric statistic used to measure the ordinal association between two measured quantities, optionally within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

kendall_coeff (float) – Kendall’s Tau coefficient rounded to four decimal places.
kendall_p (float) – The p-value associated with the Kendall’s Tau coefficient, rounded to four decimal places.

Notes

Kendall’s Tau is especially useful for data without a normal distribution and can handle ties in the data.

li_ica_histogram(image1, image2, roi_mask)[source]#

Generates data for a 2D histogram to visualize Li’s Intensity Correlation Analysis (ICA) between two images, optionally within a region of interest (ROI). This visualization assists in interpreting the intensity correlation results.

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

ica_product (numpy.ndarray) – The product of differences from the mean for each pixel, suitable for histogram plotting.
image1 (numpy.ndarray) – The masked first image, suitable for histogram plotting.
image2 (numpy.ndarray) – The masked second image, suitable for histogram plotting.

Notes

This histogram data can be useful for detailed analysis and presentation of co-localization results, helping to identify patterns or anomalies in the correlation of intensities between the two images.

li_ica_plot(ica_product, image1, image2)[source]#

Generates scatter plots to visualize the relationship between the Li’s ICA product and the intensities of two images, helping to understand the correlation and intensity distribution between the two.

Parameters:

ica_product (numpy.ndarray) – The product of differences from the mean for each pixel, obtained from Li’s ICA.
image1 (numpy.ndarray) – Intensity values of the first image.
image2 (numpy.ndarray) – Intensity values of the second image.

Notes

Two scatter plots are created side by side: one plotting the ICA product versus image1’s intensities, and the other against image2’s intensities. This visual representation can be pivotal for assessing the degree of co-localization or interaction between the two images.

Please see figure 2 in the reference for an example of how this histogram can be used to interpret the results [ica_plot_1]: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6729428/

References

[ica_plot_1]

Li, Q., Lau, A., Morris, T. J., Guo, L., Fordyce, C. B., & Stanley, E. F. (2004). A syntaxin 1, Galpha(o), and N-type calcium channel complex at a presynaptic nerve terminal: analysis by quantitative immunocolocalization. Journal of Neuroscience, 24(16), 4070-4081. doi: 10.1523/JNEUROSCI.0346-04.2004

li_intensity_correlation(image1, image2, roi_mask)[source]#

Calculates Li’s Intensity Correlation Analysis (ICA) coefficient [li_ica_1], which quantifies the pixel intensity relationship between two images, particularly useful for co-localization studies in bioimaging, optionally within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

icq (float) – The Intensity Correlation Quotient (ICQ) rounded to four decimal places.
p_val (float) – The p-value associated with the ICQ, calculated using the z-score for a two-tailed test rounded to four decimal places.
tuple – The Intensity Correlation Quotient (ICQ) and its associated p-value, both rounded to four decimal places.

Notes

Li’s ICA is particularly effective in bioimaging for assessing the degree of co-localization between different fluorescent markers. The ICQ provides a normalized measure of correlation, with values above zero indicating positive correlation.

References

[li_ica_1]

manders_k1_calculation(image1, image2, roi_mask)[source]#

Calculates Mander’s k1 coefficient, reflecting the contribution of the first image’s intensity to the overlap within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest.

Returns:

k1 (float) – Mander’s k1 coefficient rounded to four decimal places.
p_val (float) – NaN as a placeholder for a p-value which is not available for this method.

Notes

Mander’s k1 coefficient measures how much of the first image’s intensity overlaps with the second image.

manders_k2_calculation(image1, image2, roi_mask)[source]#

Calculates Mander’s k2 coefficient, reflecting the contribution of the second image’s intensity to the overlap within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest.

Returns:

k2 (float) – Mander’s k2 coefficient rounded to four decimal places.
p_val (float) – NaN as a placeholder for a p-value which is not available for this method.

Notes

Mander’s k2 coefficient measures how much of the second image’s intensity overlaps with the first image.

manders_overlap(image1, image2, roi_mask)[source]#

Calculates Mander’s overlap coefficient for two images using a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray) – A boolean mask indicating the region of interest.

Returns:

moc (float) – The Mander’s overlap coefficient rounded to four decimal places.
p_val (float) – NaN as a placeholder for a p-value, which is not available for this method.

Notes

Mander’s overlap coefficient is used to quantify the degree of overlap between two images.

pearsons_correlation(image1, image2, roi_mask)[source]#

Calculates Pearson’s correlation coefficient between two images, optionally within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

pcc (float) – Pearson’s correlation coefficient.
p_val (float) – The corresponding p-value, both rounded to four decimal places.

Notes

Pearson’s correlation measures the linear correlation between two datasets. Results are only valid if both images are of the same size and the mask, if applied, matches their dimensions.

perform_costes_test(image1, image2, cc_method, roi_mask, num_randomizations=100)[source]#

Performs Costes’ statistical significance test to validate the non-randomness of colocalization between two images, using pixel randomization. This method compares an observed colocalization coefficient to a distribution generated by randomizing one image’s pixels.

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
cc_method (function) – The correlation coefficient method to be used for calculation (e.g., Pearson’s correlation).
roi_mask (numpy.ndarray) – A boolean mask indicating the region of interest for colocalization analysis.
num_randomizations (int, optional) – The number of randomizations to perform for generating the null distribution, default is 100.

Returns:

p_value (float) – The p-value for the observed colocalization coefficient against the null distribution, rounded to four decimal places.
cc_distribution (numpy.ndarray) – The null distribution of colocalization coefficients generated by randomizing one image’s pixels.

Notes

Costes’ test involves scrambling one of the images multiple times to generate a distribution of colocalization coefficients under the null hypothesis of random colocalization. The significance of the observed colocalization is assessed based on how extreme it is in this null distribution.

pixel_wise_correlation_analysis(image1, image2, roi_mask, method_selections, label_flag, viewer)[source]#

Performs selected pixel-wise correlation analyses on two images within an optional region of interest (ROI). This function can modify the Napari viewer by adding new layers or display various histograms or plots based on the methods selected. It leverages a method-function mapping to accommodate a wide range of correlation analysis techniques.

Parameters:

image1 (numpy.ndarray) – The first input image array; should have the same dimensions as image2.
image2 (numpy.ndarray) – The second input image array; should have the same dimensions as image1.
roi_mask (numpy.ndarray, optional) – A boolean array of the same shape as the input images that specifies the region of interest. If None, the analysis is performed on the entire image.
method_selections (list of str) – A list containing the names of correlation analysis methods to be performed.
label_flag (bool) – Indicates whether to return the results as pandas DataFrames (True) or to modify the viewer with new layers or display histograms/plots based on the selected methods (False).
viewer (napari.Viewer) – The Napari Viewer instance where analysis results may be displayed as new layers.

Returns:

table1_data (pandas.DataFrame or None) – The results of the pixel-wise correlation analysis, including the correlation coefficients and p-values.
table2_data (pandas.DataFrame or None) – The results of the Costes thresholding analysis, including the Costes coefficients and p-values.
correlation_matrix_table (pandas.DataFrame or None) – The correlation matrix analysis results, including the peak value, location, and mean squared error.

Notes

The function employs a dictionary to map selected methods to their respective analysis functions, facilitating flexible and dynamic analysis based on user selection. Special processing cases like Costes thresholding and correlation matrix analysis are handled separately within the function. The results of the analysis can be visualized directly in the Napari viewer or returned as structured data for further processing.

Depending on the value of label_flag, this function returns:

If label_flag is True: One or more pandas DataFrames containing the analysis results.
If label_flag is False: None, but the function modifies the Napari viewer or displays histograms/plots.

process_pwcca_methods(selected_methods, method_functions, image1, image2, roi_mask)[source]#

Processes selected correlation analysis methods for two images within an optional region of interest (ROI), compiling the results into a pandas DataFrame. This function iterates over a list of selected methods, applies the corresponding analysis function for each, and aggregates the results.

This setup allows for flexible addition or modification of analysis methods without altering the core function structure. Each method’s function is expected to return a correlation coefficient and a p-value, which are then recorded in a structured format.

Parameters:

selected_methods (list of str) – The names of the correlation analysis methods to be processed. This list may be modified to handle special cases such as Costes significance testing.
method_functions (dict) – A dictionary mapping method names to their respective function implementations. Each function should return a tuple (coefficient, p-value).
image1 (numpy.ndarray) – The first input image array. Must have the same dimensions as image2.
image2 (numpy.ndarray) – The second input image array. Must have the same dimensions as image1.
roi_mask (numpy.ndarray, optional) – A boolean array of the same shape as the input images specifying the region of interest. If None, the analysis is performed on the entire image.

Returns:

data_table1 – A DataFrame containing the results of the correlation analysis. Each row represents a method and includes the method name, the calculated coefficient, and the corresponding p-value. Additional columns, such as ‘Costes P-Value’, are included as necessary based on selected special processing cases.

Return type:

Notes

Special handling for ‘Calculate Costes Significance’ is implemented by checking its presence in the method list, performing the significance testing if applicable, and then adding the results to the output DataFrame. This method adapts to dynamic changes in the analysis methods list, facilitating easy updates or modifications to the analytical techniques employed.

run_pwcca(image_layer1, image_layer2, roi_mask_layer, data_instance, viewer)[source]#

Executes Pixel-Wise Correlation Coefficient Analysis (PWCCA) on two image layers with an optional region of interest (ROI) mask. The function facilitates user interaction to select specific analysis methods, performs the analysis, and displays the results. It also stores these results for future use in a provided data instance object.

Parameters:

image_layer1 (napari.layers.Image) – The first image layer for analysis, providing the primary dataset.
image_layer2 (napari.layers.Image) – The second image layer for analysis, which must be of the same dimensions as the first.
roi_mask_layer (napari.layers.Labels, optional) – An optional layer providing a mask to define the ROI for the analysis. The analysis will be restricted to this region if provided.
viewer (napari.Viewer) – The Napari viewer instance used for visualizing any results directly in the GUI.
data_instance (object) – An object designed to store the results of the analysis. This object must have a ‘data_repository’ attribute (a dictionary) where results are stored.

Raises:

ValueError – If the input images do not have the same dimensions, or if the ROI mask is provided and does not have the same dimensions as the images.

Notes

This function initiates a dialog for user input to select desired correlation methods, then proceeds to perform the analysis based on the user selections. Results can include various statistical measures and visual data representations, which are displayed in the viewer and stored in the data_instance object. The analysis can handle both simple binary masks and more complex labeled masks, facilitating detailed region-specific analyses.

scramble_blocks(image, block_size)[source]#

Scrambles the pixels of an image in blocks of a specified size. This function is intended for demonstration purposes and requires additional handling for images that are not perfectly divisible by the block size.

Parameters:

image (numpy.ndarray) – The image array to be scrambled.
block_size (tuple) – The size of each block to scramble, specified as a tuple matching the image dimensions.

Returns:

scrambled_image – The image with scrambled blocks.

Return type:

Notes

This function currently serves as a placeholder and lacks full implementation details. It assumes that the image dimensions are perfectly divisible by the block size. Further development is required for robust functionality.

scramble_pixels(image, roi_mask, block_size=1)[source]#

Scrambles the pixels of an image either globally or within a specified region of interest (ROI), with an option to scramble in blocks of specified sizes.

Parameters:

image (numpy.ndarray) – The image array to be scrambled.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is scrambled.
block_size (int or tuple of int, optional) – The size of blocks to be scrambled. If an integer is provided, it’s considered uniform across all dimensions. If a tuple, it should match the image dimensions.

Returns:

The scrambled image.

Return type:

Raises:

ValueError – If block_size is not an integer or a tuple matching the image dimensions, or if any dimension of block_size is less than 1.

Notes

This function provides flexibility in scrambling, allowing for selective scrambling within a region or across the entire image. It’s particularly useful for testing or simulating disturbances in image data.

scramble_pixels_within_mask(image, mask)[source]#

Scrambles the pixels within a specified mask of an image to disrupt any inherent spatial relationships. This method is often used in image analysis to assess the impact of pixel arrangement on analytical outcomes.

Parameters:

image (numpy.ndarray) – The image array in which pixels are to be scrambled.
mask (numpy.ndarray) – A boolean array of the same shape as image, indicating the pixels to be scrambled.

Returns:

scrambled_image – The image with pixels scrambled only within the specified mask regions.

Return type:

Notes

Only the pixels within the mask are scrambled, preserving the pixel values outside of the mask.

spearman_r_calculation(image1, image2, roi_mask)[source]#

Calculates Spearman’s rank correlation coefficient between two images, optionally within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

spearman_coeff (float) – The Spearman’s rank correlation coefficient rounded to four decimal places.
spearman_p (float) – The p-value associated with the Spearman’s correlation, rounded to four decimal places.

Notes

Spearman’s correlation assesses the monotonic relationship between two datasets, ranking the data before calculating the Pearson correlation on these ranks. This measure is non-parametric and does not assume a normal distribution of the data.

weighted_tau_calculation(image1, image2, roi_mask)[source]#

Calculates the weighted Tau coefficient between two images, providing a refined version of Kendall’s Tau that considers the strength of association between pairs, optionally within a region of interest (ROI).

Parameters:

image1 (numpy.ndarray) – The first image array.
image2 (numpy.ndarray) – The second image array.
roi_mask (numpy.ndarray, optional) – A boolean mask indicating the region of interest. If None, the entire image is considered.

Returns:

weighted_tau (float) – The weighted Tau coefficient rounded to four decimal places.
weighted_p (float) – The p-value associated with the weighted Tau coefficient, rounded to four decimal places.

Notes

Weighted Tau is advantageous in the presence of ties or varying degrees of association between rankings, making it suitable for complex data sets.

Colocalization Analysis#

Object Based Colocalization Analysis (OBCA) Module for PyCAT

This module contains functions for calculating colocalization coefficients and distances between objects in two masks. It also provides a dialog for selecting analysis methods and orchestrates the object-based colocalization analysis workflow. The functions support the calculation of Mander’s M1 and M2 coefficients, Jaccard Index, Sorensen-Dice Coefficient, and object-based distance analysis. The results are displayed in tabulated format for easy interpretation and further analysis.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

class obcaDialog(parent=None)[source]#

Bases: QDialog

A dialog class for selecting correlation and distance analysis methods in an object-based colocalization analysis (OBCA) context. It provides a user-friendly interface where users can choose from a predefined list of methods, organized into sections for different types of analyses.

checkboxes#

A list containing all the QCheckBox widgets in the dialog, representing available analysis methods.

Type:: list of QCheckBox

Parameters:: parent (QWidget, optional) – The parent widget of this dialog, typically the main window of the application. Defaults to None.

__init__(parent=None)[source]#

Initializes the obcaDialog with sections for selecting various correlation and distance analysis methods, and includes buttons for selecting or deselecting all options.

Parameters:: parent (QWidget, optional) – The parent widget of the dialog. Defaults to None.

deselect_all()[source]#: Deselects all checkboxes within the dialogue.

get_selected_methods()[source]#

Retrieves a list of the analysis methods selected by the user.

Returns:: A list of the names of the selected analysis methods.
Return type:: list of str

select_all()[source]#: Selects all checkboxes within the dialogue.

calculate_centroid_distance(region1, region2)[source]#

Calculates the Euclidean distance between the centroids of two regions. Each region is expected to have a ‘centroid’ attribute which represents the geometric center of the region.

Parameters:

region1 (object) – The first region, an object that must have a ‘centroid’ attribute.
region2 (object) – The second region, an object that must have a ‘centroid’ attribute.

Returns:

The Euclidean distance between the centroids of the two regions.

Return type:

categorize_pairings(overlap_df)[source]#

Categorizes the pairings of labels between two masks into single pairs and multiple pairs based on the uniqueness of the pairings within a provided DataFrame. Single pairs are unique pairings where each label from mask1 and mask2 appears only once. Multiple pairs are pairings where at least one label from either mask appears in multiple pairings.

Parameters:

overlap_df (pandas.DataFrame) – A DataFrame containing overlap information between two masks. It should have columns ‘Mask 1 Labels’, ‘Mask 2 Labels’, and ‘Overlap Area’. Rows with missing ‘Mask 2 Labels’ are excluded from the analysis.

Returns:

single_pairs_df (pandas.DataFrame) – A DataFrame containing only single pairs where each label pair is unique.
multiple_pairs_df (pandas.DataFrame) – A DataFrame containing multiple pairs where one or more labels appear in more than one pairing.

Notes

The function first eliminates any rows in the overlap_df that have missing values in ‘Mask 2 Labels’, which could represent incomplete pairings. It then identifies single pairs by checking for unique occurrences of ‘Mask 1 Labels’ and ‘Mask 2 Labels’. All remaining pairings that do not fit into single pairs are classified as multiple pairs. This categorization helps in subsequent analyses where the distinction between unique and repeated label pairings affects the computation of distances or other metrics.

jaccard_index_calculation(mask1, mask2, roi_mask)[source]#

Calculates the Jaccard Index, a measure of the overlap between two masks normalized by their union. The calculation can be restricted to a region of interest (ROI) if an ROI mask is provided.

Parameters:

mask1 (numpy.ndarray) – The first mask array.
mask2 (numpy.ndarray) – The second mask array.
roi_mask (numpy.ndarray, optional) – A mask defining the ROI for the calculation. Must be the same shape as mask1 and mask2.

Returns:

jaccard_index – The Jaccard Index, rounded to 4 decimal places. Returns np.nan if both masks sum to zero within the ROI.

Return type:

Notes

This function focuses the Jaccard Index calculation within the ROI if provided. If the ROI mask is not specified, the entire area of the masks is considered for the calculation.

manders_coloc(image1, mask2, roi_mask)[source]#

Calculates Mander’s Colocalization Coefficient (MCC) for two images within a specified region of interest (ROI). MCC is a measure of the fraction of total intensity from one image (image1) that overlaps with the pixels identified in a second mask (mask2). This coefficient ranges from 0 (no colocalization) to 1 (complete colocalization).

Parameters:

image1 (numpy.ndarray) – A 2D array representing the first image, where the colocalization is to be calculated.
mask2 (numpy.ndarray) – A 2D binary or label array representing the second image or mask, must have the same dimensions as image1.
roi_mask (numpy.ndarray, optional) – A boolean array of the same size as image1 and mask2 defining the ROI. If None, the entire image is considered.

Returns:

mcc – The Mander’s Colocalization Coefficient rounded to 4 decimal places.

Return type:

Raises:

ValueError – If any of the inputs are not 2D or if their dimensions do not match.

Note

The function utilizes skimage.measure.label for calculation if mask2 is not binary, ensuring it processes correctly labeled regions for accurate MCC calculation.

manders_m1_calculation(mask1, mask2, roi_mask)[source]#

Calculates Mander’s M1 coefficient, which measures the overlap of mask1 over mask2, normalized by the total intensity of mask1. The calculation can be restricted to a region of interest (ROI) if an ROI mask is provided.

Parameters:

mask1 (numpy.ndarray) – The first mask array.
mask2 (numpy.ndarray) – The second mask array.
roi_mask (numpy.ndarray, optional) – A mask defining the ROI for the calculation. Must be the same shape as mask1 and mask2.

Returns:

m1 – Mander’s M1 coefficient, rounded to 4 decimal places. Returns 0.0 if the sum of mask1 within the ROI is 0.

Return type:

Notes

This function focuses the M1 calculation within the ROI if provided. If the ROI mask is not specified, the entire area of the masks is considered for the calculation.

manders_m2_calculation(mask1, mask2, roi_mask)[source]#

Calculates Mander’s M2 coefficient, which measures the overlap of mask2 over mask1, normalized by the total intensity of mask2. The calculation can be restricted to a region of interest (ROI) if an ROI mask is provided.

Parameters:

mask1 (numpy.ndarray) – The first mask array.
mask2 (numpy.ndarray) – The second mask array.
roi_mask (numpy.ndarray, optional) – A mask defining the ROI for the calculation. Must be the same shape as mask1 and mask2.

Returns:

m2 – Mander’s M2 coefficient, rounded to 4 decimal places. Returns 0.0 if the sum of mask2 within the ROI is 0.

Return type:

Notes

This function focuses the M2 calculation within the ROI if provided. If the ROI mask is not specified, the entire area of the masks is considered for the calculation.

object_based_colocalization_analysis(object_mask1, object_mask2, roi_mask, method_selections, data_instance)[source]#

Performs object-based colocalization analysis on two object masks, optionally within a specified region of interest (ROI), based on selected methods. This analysis can include various correlation coefficients and distance measurements between objects identified in the masks.

Parameters:

object_mask1 (numpy.ndarray) – The first object mask for analysis, where each distinct object is labeled with a unique identifier.
object_mask2 (numpy.ndarray) – The second object mask for analysis, structured similarly to the first mask.
roi_mask (numpy.ndarray, optional) – An optional mask defining the region of interest for the analysis. If provided, the analysis is restricted to this region.
method_selections (list of str) – A list of selected methods for colocalization analysis, which can include various correlation coefficients and distance calculations.
data_instance (object) – An instance containing data repositories, which should include ‘microns_per_pixel_sq’ for distance calculations if distance analysis is selected.

Returns:

table1_data (pandas.DataFrame) – A DataFrame containing the results of the selected correlation coefficient analyses.
table2_data (pandas.DataFrame) – A DataFrame containing the results of the distance analysis, including the mean distance between objects in pixels and microns, along with the percentage of non-coincident objects.

Notes

The function processes each selected method for correlation coefficients and performs distance analysis if selected. For distance measurements, the function uses ‘microns_per_pixel_sq’ from the data instance to convert distance from pixels to microns, providing a practical measure for biological analysis. The output tables encapsulate the results of the selected analyses, facilitating further statistical processing or visualization.

object_based_distance_analysis(mask1, mask2, roi_mask)[source]#

Performs an object-based distance analysis between two binary masks, optionally within a specified region of interest (ROI). This analysis involves labeling the objects in both masks, calculating overlaps, and computing distances between centroids of overlapping objects. Additionally, it calculates the percentage of objects in either mask that do not overlap with any object in the other mask.

Parameters:

mask1 (numpy.ndarray) – The first binary mask where objects are to be analyzed.
mask2 (numpy.ndarray) – The second binary mask where objects are to be analyzed.
roi_mask (numpy.ndarray, optional) – A binary mask defining the region of interest for the analysis. If provided, the analysis is restricted to this region.

Returns:

final_mean_distance (float) – The mean distance between corresponding objects in the two masks, averaged across all pairs of overlapping objects. Returns np.nan if no valid comparisons can be made.
percentage_non_coincident (float) – The percentage of objects in either mask that do not overlap with any object in the other mask, expressed as a decimal between 0 and 1.

Notes

The function processes masks by first applying the ROI mask if provided. It then labels each distinct object in the masks. Overlaps between objects from different masks are identified, and distances between their centroids are calculated. The function handles single and multiple overlapping pairs differently, using specialized functions to calculate distances for these scenarios.

If either mask is entirely zero or if no objects overlap, the function will return np.nan for the mean distance and 1.0 for the percentage of non-coinciding objects.

process_multiple_pairs(multiple_pairs_df, labels1, labels2)[source]#

Processes multiple pairs of regions to calculate the average distances between their centroids. This function is particularly useful for cases where multiple pairings exist for a single label in the first mask. It calculates an average distance for each unique label in mask1 across all its pairings.

Parameters:

multiple_pairs_df (pandas.DataFrame) – A DataFrame containing rows of pairings between masks, potentially including multiple pairs for a single label from mask1. Expected to have a column ‘Mask 1 Labels’.
labels1 (numpy.ndarray) – Labeled image where each label corresponds to a distinct object or region.
labels2 (numpy.ndarray) – Labeled image where each label corresponds to a distinct object or region.

Returns:

distances – A list of average distances for each unique label in mask1 across its pairings. The averages are calculated from all pairings where the label from mask1 is involved.

Return type:

list

process_obca_methods(selected_methods, method_functions, mask1, mask2, roi_mask)[source]#

Processes a list of selected colocalization analysis methods for two object masks, potentially within a specified region of interest (ROI). Each method is applied to the masks, and the results are compiled into a DataFrame.

Parameters:

selected_methods (list of str) – A list of the names of methods to be applied. These methods should be keys in the method_functions dictionary.
method_functions (dict) – A dictionary mapping each method name to a function that implements the corresponding analysis. Each function is expected to take two masks (and optionally an ROI mask) and return a single numerical result (coefficient).
mask1 (numpy.ndarray) – The first object mask for analysis, where each distinct object is labeled with a unique identifier.
mask2 (numpy.ndarray) – The second object mask for analysis, structured similarly to the first mask.
roi_mask (numpy.ndarray, optional) – An optional mask defining the region of interest for the analysis. If provided, each method’s analysis will be restricted to this area.

Returns:

data_table1 – A DataFrame with columns ‘Method’ and ‘Coefficient’. Each row corresponds to one of the selected methods and contains the name of the method along with the calculated coefficient resulting from its application to the masks. The coefficients are derived from each method’s specific analysis procedure, which may include measurements of overlap, distance, or other statistical correlations.

Return type:

Notes

The function iterates over the list of selected methods. For each method, if it is included in the method_functions dictionary, the corresponding function is called with the masks and the ROI mask if provided. The results are then collected in a DataFrame which is returned. This DataFrame serves as a concise summary of the results from applying the selected colocalization analysis methods to the input masks.

process_single_pairs(single_pairs_df, labels1, labels2)[source]#

Processes single pairs of regions from two sets of labels to calculate the distances between their centroids. This function iterates through a DataFrame containing unique pairings of labels and calculates the centroid distance for each pair using the ‘calculate_centroid_distance’ function.

Parameters:

single_pairs_df (pandas.DataFrame) – A DataFrame containing rows of unique pairings between masks. Expected to have columns ‘Mask 1 Labels’ and ‘Mask 2 Labels’ indicating labels from labels1 and labels2 respectively.
labels1 (numpy.ndarray) – Labeled image where each label corresponds to a distinct region in the first mask.
labels2 (numpy.ndarray) – Labeled image where each label corresponds to a distinct region in the second mask.

Returns:

distances – A list of distances between centroids of each pair of regions.

Return type:

list

run_manders_coloc(image_layer1, mask_layer2, roi_mask_layer, data_instance)[source]#

Orchestrates the calculation of Mander’s Colocalization Coefficient (MCC) using provided image data layers, potentially within a specified region of interest (ROI), and updates the data instance with the results.

This function retrieves image data from provided layers, validates their shapes, executes the MCC calculation, and displays the result in a tabulated format. It also stores the results in the provided data instance for future reference.

Parameters:

image_layer1 (napari.layers.Image) – The first image layer containing image data for the MCC calculation. Expected to have a .data attribute with 2D image information.
mask_layer2 (napari.layers.Labels) – The second image layer containing a mask or another image as input for MCC. Expected to have a .data attribute.
roi_mask_layer (napari.layers.Labels, optional) – An optional layer specifying the ROI for the MCC calculation. If None, the entire image is considered. If provided, expected to be a boolean mask with the same dimensions as image1 and mask2.
data_instance (object) – An object (e.g., a data handling class instance) that stores the results. This object should have a ‘data_repository’ attribute where the MCC results are saved.

Raises:

ValueError – If the input images or the ROI mask (if provided) do not have matching shapes, indicating they cannot be directly compared or analyzed together.

Notes

The MCC calculation is sensitive to the exact alignment and matching dimensions of the input layers. Results are visualized in a dialog window and stored within the provided data_instance object under the key ‘manders_coloc_df’.

run_obca(mask_layer1, mask_layer2, roi_mask_layer, data_instance)[source]#

Executes the Object-Based Colocalization Analysis (OBCA) using two provided image mask layers and an optional Region of Interest (ROI) mask layer. This function manages the workflow from user interaction for method selection to processing the data and updating the provided data instance with analysis results.

Parameters:

mask_layer1 (MaskLayer) – The first image mask layer for analysis, containing image data where objects are presumably labeled.
mask_layer2 (MaskLayer) – The second image mask layer for analysis, structured similarly to the first.
roi_mask_layer (MaskLayer, optional) – An optional layer containing the ROI mask data. If provided, analysis is restricted to this region.
data_instance (DataInstance) – The data instance in which the analysis results will be stored. It should have a ‘data_repository’ attribute to store DataFrames of results.

Raises:

ValueError – If the shapes of mask_layer1 and mask_layer2 do not match, or if the shape of roi_mask_layer does not match the shapes of mask_layer1 and mask_layer2 when roi_mask_layer is not None.

Notes

The function initiates by displaying a dialog for the user to select methods for analysis. Depending on the user’s selections, it processes the masks using the chosen colocalization analysis methods. Results are compiled into DataFrames and are displayed to the user. Additionally, these results are stored in the data instance for future reference. The function does not return any value but ensures the results are accessible via the data instance.

sorensen_dice_coefficient_calculation(mask1, mask2, roi_mask)[source]#

Calculates the Sorensen-Dice coefficient, a measure of the overlap between two masks normalized by the size of each mask. The calculation can be restricted to a region of interest (ROI) if an ROI mask is provided.

Parameters:

mask1 (numpy.ndarray) – The first mask array.
mask2 (numpy.ndarray) – The second mask array.
roi_mask (numpy.ndarray, optional) – A mask defining the ROI for the calculation. Must be the same shape as mask1 and mask2.

Returns:

dice_coefficient – The Sorensen-Dice coefficient, rounded to 4 decimal places. Returns np.nan if both masks sum to zero within the ROI.

Return type:

Notes

This function focuses the Dice coefficient calculation within the ROI if provided. If the ROI mask is not specified, the entire area of the masks is considered for the calculation.

Labels and Masks#

Labeled Mask and Binary Mask Module for PyCAT

This module contains functions for processing labeled masks and binary masks, including operations such as morphological transformations, labeling connected components, and measuring properties of regions. It also provides functions for splitting touching objects in binary images and extending segmentation masks to the image borders.

Author#

Christian Neureuter, GitHub: cneureuter

Date#

4-20-2024

class MeasurementDialog(props_list, parent=None)[source]#

Bases: QDialog

A dialog window that allows users to select which properties to measure from regions within an image. It presents a list of common properties with checkboxes and textboxes for custom naming of measurements. Additional properties can be accessed via a ‘Show More’ button, which expands the dialog to show a scrollable area.

Parameters:

props_list (list) – A list of property names that can be measured.
parent (QWidget, optional) – The parent widget of this dialog. Default is None.

checkboxes#

A list of QCheckBox widgets for selecting properties.

Type:: list

textboxes#

A list of QLineEdit widgets for entering custom names for the selected properties.

Type:: list

toggle_scroll_area(self):: Show or hide the scrollable area containing additional properties.

select_all(self):: Selects all property checkboxes.

deselect_all(self):: Deselects all property checkboxes.

get_selected_props(self):: Returns a list of tuples containing the selected properties and their custom names.

__init__(props_list, parent=None)[source]#

deselect_all()[source]#: Deselects all checkboxes.

get_selected_props()[source]#: Returns a list of tuples for each selected property. Each tuple contains the property name and the custom label from the textbox, if provided; otherwise, it defaults to the property name.

select_all()[source]#: Selects all checkboxes.

toggle_scroll_area()[source]#: Show or hide the scrollable area.

binary_morph_operation(binary_mask_input, iterations=1, element_size=3, element_shape='Disk', mode='Opening', roi_mask=None)[source]#

Performs specified binary morphological operations using various structuring elements on a binary image. This function provides flexibility in image processing applications to manipulate image structures based on the selected morphological technique.

Parameters:

binary_mask_input (numpy.ndarray) – The binary image on which to perform the operation.
iterations (int, optional) – The number of times the operation is applied; more iterations intensify the effect.
element_size (int, optional) – Determines the size of the structuring element used in the operation.
element_shape (str, optional) – The shape of the structuring element, such as ‘Disk’, ‘Square’, ‘Diamond’, ‘Star’, or ‘Cross’.
mode (str, optional) – The type of morphological operation to perform, including ‘Opening’, ‘Closing’, ‘Dilation’, ‘Erosion’, or ‘Fill Holes’.
roi_mask (numpy.ndarray, optional) – A mask that defines the region of interest within the binary image where the operation should be applied.

Returns:

binary_mask – The binary image processed by the specified morphological operation.

Return type:

Notes

The function includes an automatic extension of the mask to the edges of the image to prevent artifacts from operations near the image borders.

custom_binary_closing(binary_mask, structure=None, iterations=1, mask=None)[source]#

Performs a binary closing on a binary image, which is a dilation followed by an erosion. This operation is useful for closing small holes within the foreground objects in an image, enhancing connectivity and coverage.

Parameters:

binary_mask (numpy.ndarray) – The binary image to process.
structure (numpy.ndarray, optional) – The structuring element used for dilation and erosion. If not provided, a default element is used.
iterations (int, optional) – The number of times the dilation and erosion are applied.
mask (numpy.ndarray, optional) – A mask defining where the operation should be applied; if provided, operations are confined to this area.

Returns:

binary_mask – The binary image after applying the closing operation.

Return type:

custom_binary_opening(binary_mask, structure=None, iterations=1, mask=None)[source]#

Performs a binary opening on a binary image, which is an erosion followed by a dilation. This operation is used to remove small objects from the foreground of an image, typically small noise components.

Parameters:

binary_mask (numpy.ndarray) – The binary image to process.
structure (numpy.ndarray, optional) – The structuring element used for erosion and dilation. If not provided, a default element is used.
iterations (int, optional) – The number of times the erosion and dilation are applied.
mask (numpy.ndarray, optional) – A mask defining where the operation should be applied; if provided, operations are confined to this area.

Returns:

binary_mask – The binary image after applying the opening operation.

Return type:

extend_mask_to_edges(mask, size_to_extend=1)[source]#

Extend a segmentation mask outwards to the edges of an image, ensuring coverage up to the image borders. This function is particularly useful for segmentation methods that might not reach the image borders, leaving unsegmented spaces.

This method copies the mask values from inside the border (specified by the extension size) to the actual borders, effectively extending the mask.

Parameters:

mask (numpy.ndarray) – The segmentation mask array, which may be binary or labeled.
size_to_extend (int, optional) – The number of pixels by which to extend the mask into the image borders. Defaults to 1.

Returns:

mask – The extended mask, adjusted to cover up to the image borders.

Return type:

Notes

If size_to_extend is less than or equal to 0, the function prints a warning and returns the unmodified mask.

generate_cross_structuring_element(radius)[source]#

Generates a cross-shaped structuring element with a specified radius for use in morphological operations on binary images.

Parameters:: radius (int) – The radius of the cross. This value defines the reach of the arms of the cross from the center. The overall size of the structuring element will be (2*radius + 1, 2*radius + 1), forming a square array.
Returns:: structuring_element – A 2D numpy array representing the structuring element. The array contains 1s along the arms of the cross and 0s elsewhere.
Return type:: numpy.ndarray

measure_region_props(labeled_mask, image, selected_props)[source]#

Measures specified properties of labeled regions within an image. It maps the selected properties to their corresponding measurements for each region and returns these measurements as a DataFrame.

Parameters:

labeled_mask (numpy.ndarray) – A labeled mask of the image, where each unique label corresponds to a different region.
image (numpy.ndarray) – The original image corresponding to the labeled mask.
selected_props (list of tuples) – Each tuple contains the name of a property to measure and its custom name (if provided by the user).

Returns:

measurement_df – A pandas DataFrame containing the measurements for the specified properties of each labeled region.

Return type:

opencv_contour_func(input_mask, min_area=1, max_area=1048576, border_size=3)[source]#

Extracts and draws contours from a binary input mask based on specified area thresholds. This function converts the input mask to uint8, pads it to detect contours at the edges, and then filters the detected contours by area before drawing them onto a new mask.

Parameters:

input_mask (numpy.ndarray) – A binary mask where the contours are to be detected and drawn. The mask should be in a format compatible with OpenCV (usually a binary image).
min_area (int, optional) – The minimum area threshold for a contour to be considered valid. Contours with an area less than this value are ignored. Defaults to 1.
max_area (int, optional) – The maximum area threshold for a contour to be considered valid. Contours with an area greater than this value are ignored. Defaults to 1024^2, accommodating very large contours.
border_size (int, optional) – The size of the border added around the input mask to ensure contours at the edges are detected. Defaults to 3.

Returns:

output_mask – A mask of the same shape as input_mask, with valid contours filled in. The type of the mask is uint8, suitable for further processing or visualization with OpenCV.

Return type:

Notes

The function initially pads the input mask with a black border to facilitate the detection of contours that reach the edges of the image. It then utilizes cv2.findContours to detect contours and cv2.drawContours to draw them based on the specified area thresholds. The padding is removed from the final output, ensuring the output mask matches the size of the original input mask.

run_binary_morph_operation(roi_mask_layer, iter_input, elem_size_input, elem_shape_dropdown, mode_dropdown, viewer)[source]#

Facilitates the interactive execution of binary morphological operations within the Napari viewer, allowing users to adjust parameters through the UI and apply changes dynamically to the image data.

Parameters:

roi_mask_layer (napari.layers.Labels) – The Napari Labels layer that serves as a mask defining the region of interest where the operation is applied.
iter_input (int) – The number of iterations for the morphological operation.
elem_size_input (int) – The size parameter for the structuring element used in the operation.
elem_shape_dropdown (str) – The shape of the structuring element; options include ‘disk’, ‘square’, ‘diamond’, ‘star’, ‘cross’.
mode_dropdown (str) – The type of morphological operation to perform; options include ‘opening’, ‘closing’, ‘dilation’, ‘erosion’, ‘fill holes’.
viewer (napari.Viewer) – The Napari viewer instance used for visualizing the changes.

Raises:

ValueError – If the active layer is not a labels layer, or if the binary mask and ROI mask have different shapes.

Notes

This function dynamically updates the viewer based on user input, providing real-time visual feedback. It checks for the type of the active layer and raises an error if the layer is not suitable for the operation.

run_convert_labels_to_mask(labels_layer, viewer)[source]#

Converts a labeled image layer to a binary mask and displays the resulting mask in the viewer. Each unique integer label in the labeled image is treated as a distinct object, and all objects are represented collectively in a single binary mask, where pixels of objects are set to 1, and the background remains 0.

Parameters:

labels_layer (napari.layers.Labels) – The layer containing the labeled image to be converted. Each distinct label represents a different object.
viewer (napari.Viewer) – The viewer object where the resulting binary mask will be added and displayed.

Notes

The function creates a binary mask where all non-zero labels are set to 1, effectively differentiating objects from the background without distinguishing between individual objects.
The new mask layer is named using the original labels layer’s name for easy identification.

run_label_binary_mask(mask_layer, viewer)[source]#

Labels connected components in a binary mask and displays the result in the viewer as a new layer. This process involves assigning a unique label to each connected group of ‘1’s in the binary mask, facilitating the identification and analysis of individual components.

Parameters:

mask_layer (napari.layers.Labels) – The layer containing the binary mask. This mask should only contain values of 0 (background) and 1 (foreground).
viewer (napari.Viewer) – The viewer object in which the resulting labeled mask will be displayed.

Notes

The function first checks to ensure that the input mask contains only 0 and 1 values. If any other values are present, it issues a warning and exits without performing the labeling.
The labeled mask is then added to the viewer under a new layer named ‘Labeled <original_layer_name>’, making it easy to distinguish from the original binary mask.

run_measure_binary_mask(mask_layer, image_layer, data_instance)[source]#

Measures various intensity and area-based properties of regions defined by a binary mask within a corresponding image, then appends the results to a Pandas DataFrame stored within a data instance object. This allows for further analysis or reporting.

Parameters:

mask_layer (napari.layers.Labels) – The layer containing the binary mask which indicates regions of interest. This mask should be a boolean array.
image_layer (napari.layers.Image) – The layer containing the image from which properties are to be measured. Must have the same dimensions as the mask layer.
data_instance (object) – An object containing a Pandas DataFrame (data_instance.binary_mask_stats_df) to append the results. This object should also contain a ‘microns_per_pixel_sq’ attribute within data_instance.data_repository for micron area calculations.

Returns:

Modifies the DataFrame within data_instance.binary_mask_stats_df directly by appending new measurements. If no such DataFrame exists, it creates a new one.

Return type:

None

Raises:

ValueError – If the mask and image layers have different dimensions.

Notes

The function checks that the mask and image have the same dimensions.
It calculates the mean, median, standard deviation, minimum, maximum, and total intensity; relative intensity; area; micron area; and relative area.
Results are rounded to four decimal places and either appended to an existing DataFrame or used to create a new DataFrame.
A dialog is shown with the updated DataFrame upon completion, if applicable.

run_measure_region_props(mask_layer, image_layer, data_instance)[source]#

Coordinates the measurement of region properties within an image. It handles the preparation of the labeled mask and the image, user selection of properties through a dialog, and the storage of measurement results in a data repository.

Parameters:

mask_layer (napari.layers.Labels) – The mask layer containing labeled regions for measurement.
image_layer (napari.layers.Image) – The image layer corresponding to the mask layer.
data_instance (object) – An instance containing a data repository where measurement results are stored.

Raises:

ValueError – If the mask and image layers have different shapes.

Notes

This function integrates with napari UI elements and custom dialogs to provide a user-friendly interface for selecting and measuring region properties. It ensures that the mask and image have the same shape and that there are at least two labels in the mask before proceeding with measurements.

run_update_labels(new_label_input, increment_mode, viewer)[source]#

Updates label values in the active label layer of a viewer based on user input. The operation performed depends on the operation mode selected: either incrementing all label values by a specified value or changing a specific label to a new value. The viewer is refreshed to display the updated labels.

Parameters:

viewer (napari.Viewer) – The viewer object that contains the label layer to be updated.
new_label_input (UI component (e.g., a text input field)) – An input widget or field that provides the new label value or the increment value. Expected to be convertible to an integer.
increment_mode (bool) – A boolean value or a widget (e.g., a checkbox) indicating the operation mode. If True, all label values in the layer are incremented by the value from new_label_input. If False, the specified label is changed to the new value provided.

Notes

Assumes new_label_input.text() returns a string convertible to an integer.
Validates the active layer as a labels layer before performing updates.
If changing a specific label to a new value, ensures the new value does not duplicate existing label values, alerting the user for manual intervention (such as undo) if duplication occurs.

split_touching_objects(binary_mask, sigma=3.5)[source]#

Splits touching objects in a binary image using a watershed algorithm. The function applies morphological closing to connect close objects, followed by a distance transform and Gaussian filtering. Peak local maxima are identified in the filtered distance transform as markers for the watershed algorithm, which segments the image into individual objects. This method is useful for separating connected objects such as cell nuclei in binary images.

Parameters:

binary_mask (numpy.ndarray) – A binary image where the objects to be split are marked as True (or 1) and the background as False (or 0).
sigma (float, optional) – The standard deviation for Gaussian filter applied to the distance transform of the binary image. A higher value results in more smoothing, which can be useful for separating objects that are very close to each other. Default is 3.5.

Returns:

refined_split_mask – A binary image where the originally connected objects have been split based on the watershed segmentation results.

Return type: