pycat.utils#
General Utilities#
General Utilities Module for PyCAT
This module contains utility functions for image processing and data manipulation tasks in the PyCAT application. The functions include image data type conversion, cropping images to bounding boxes defined by masks, checking image contrast, and creating overlay images with red masks. These utilities are designed to facilitate common image processing operations and enhance the user experience in the application.
Date#
4-20-2024
- check_contrast_func(image)[source]#
Check if the input image has sufficient contrast, specifically after conversion to 16-bit depth.
This function converts the input image to uint16 format using dtype_conversion_func. It calculates the minimum and maximum pixel values to assess contrast. If the min and max values differ by 2 or less, it indicates a lack of sufficient contrast, typically implying the image or cell is blank, and is useful for deciding whether to exclude such images from further processing.
- Parameters:
image (numpy.ndarray) – The input image array.
- Returns:
False if there is sufficient contrast in the image; True if there is insufficient contrast.
- Return type:
Notes
The return value is True for error conditions (no contrast), which might seem counterintuitive but follows a specific pattern where checking functions return True to indicate the presence of the condition they check for.
- create_overlay_image(green_channel, overlay_mask, alpha=0.65)[source]#
Create an image showing the green channel of an input image next to the same image with a red overlay on specified areas.
This function normalizes the green channel data to 8-bit, creates an RGB representation of it, and overlays a red mask on specified areas defined by the overlay_mask. The resulting images are shown side by side for comparison purposes.
- Parameters:
green_channel (numpy.ndarray) – A 2D array representing the green channel of an image.
overlay_mask (numpy.ndarray) – A 2D boolean or binary array where true/non-zero values indicate areas to apply a red overlay.
alpha (float, optional) – Transparency level for the red overlay, ranging from 0 (transparent) to 1 (opaque). Default is 0.65.
- Returns:
side_by_side_image – An array containing the original RGB image and the modified image with a red overlay side by side.
- Return type:
Notes
Both green_channel and overlay_mask must have the same dimensions. This function assumes that the input green channel values are normalized (i.e., within a 0 to 1 range) or will normalize them internally for the purpose of image processing.
- crop_bounding_box(image, roi_mask)[source]#
Crops an image and its corresponding region of interest (ROI) mask to the bounding box defined by the ROI mask, then applies the cropped mask to the cropped image to generate a masked image.
- Parameters:
image (numpy.ndarray) – The input image to be cropped, which can be a 2D (grayscale) or 3D (color) numpy array.
roi_mask (numpy.ndarray) – A binary mask indicating the region of interest within the image. The mask should be of the same height and width as the image and contain non-zero values (typically 1) in the region of interest and 0 elsewhere.
- Returns:
masked_img (numpy.ndarray) – The cropped image with the ROI mask applied, setting pixels outside the ROI to zero.
cropped_mask (numpy.ndarray) – The cropped ROI mask.
cropped_img (numpy.ndarray) – The cropped image without the mask applied.
Notes
This function identifies non-zero values in the ROI mask to determine the bounding box for cropping. The cropped image and mask are then used to create a masked image where only the region of interest is visible.
- dtype_conversion_func(image, output_bit_depth='uint16')[source]#
Converts the data type of an image to a specified bit depth using skimage’s utility functions. This conversion facilitates the optimization of images for various image processing tasks by ensuring compatibility with algorithm requirements and enhancing performance.
- Parameters:
image (numpy.ndarray) – The input image to be converted, which can be of any data type supported by skimage.
output_bit_depth (str, optional) – The desired output bit depth as a string. Valid options include ‘uint8’, ‘uint16’, ‘int16’, ‘float32’, and ‘float64’, defaulting to ‘uint16’.
- Returns:
converted_image – The image converted to the specified bit depth.
- Return type:
- Raises:
ValueError – If an unsupported output bit depth is specified.
Notes
This function uses a mapping of bit depth strings to corresponding skimage functions to perform the conversion.
- get_default_intensity_range(dtype_str)[source]#
Retrieves the default intensity range for a specified image data type. This range is important for tasks such as image normalization and processing, where specific data types may impact computations.
- Parameters:
dtype_str (str) – A string representing the data type for which the intensity range is sought. Supported data types include ‘uint8’, ‘uint16’, ‘int16’, ‘float32’, and ‘float64’.
- Returns:
A tuple containing two numbers that represent the minimum and maximum intensity values for the given data type.
- Return type:
- Raises:
ValueError – If the provided data type string is not supported, raises a ValueError indicating the unsupported data type.
Notes
This function serves as a helper for intensity rescaling functions to determine the appropriate ranges based on the input data type.
Mathematical Utilities#
Math Utilities Module for PyCAT
This module contains utility functions for mathematical operations that are used in the PyCAT application. The functions include outlier removal, R squared calculation, and Gaussian kernel generation. These functions are used in various parts of the application for data processing and analysis.
Author#
Christian Neureuter, GitHub: cneureuter
Date#
4-20-2024
- calculate_r_squared(actual, predicted)[source]#
Calculate the coefficient of determination (R squared), which assesses the goodness of fit between actual and predicted values from a regression model.
R squared quantifies the proportion of variance in the dependent variable that is predictable from the independent variables. A value of 1 indicates a perfect fit, a value of 0 indicates that the model predicts none of the variability of the response data around its mean.
- Parameters:
actual (numpy.array) – The actual values observed; the dependent variable.
predicted (numpy.array) – The values predicted by a regression model; the independent variable predictions.
- Returns:
r_squared – The R squared value, a statistic that ranges from 0 to 1, where higher values indicate a better fit.
- Return type:
- create_2d_gaussian_kernel(kernel_size, sigma=None)[source]#
Generate a 2D Gaussian kernel, which is commonly used as a Point Spread Function (PSF) in image processing applications, particularly for simulating a Gaussian blur effect.
The kernel is a square matrix with dimensions defined by kernel_size, centered on the Gaussian peak. The sum of all elements in the kernel is normalized to 1, ensuring no change in the overall image brightness after convolution.
- Parameters:
- Returns:
kernel – A 2D numpy array representing the Gaussian kernel. The kernel values follow a Gaussian distribution, centered in the matrix, and normalized such that the sum equals 1.
- Return type:
numpy.array
Notes
A default sigma is calculated if not provided, using a formula that balances between spread and central peak intensity based on the kernel size.
- remove_outliers_iqr(data)[source]#
Remove outliers from a dataset using the Interquartile Range (IQR) method. This method calculates the IQR as the difference between the 75th and 25th percentiles of the data. Data points outside 1.5 times the IQR from the quartiles are considered outliers and are removed. This technique is robust to extreme values that could skew the data distribution.
- Parameters:
data (numpy.ndarray) – A numpy array containing the dataset from which outliers will be removed. The array can be of any shape but will be flattened for processing.
- Returns:
filtered_data – A numpy array containing the data after outlier removal. The shape of filtered_data might be smaller than data if outliers were found and removed. The data is returned in the same shape it was input.
- Return type:
Notes
The IQR method is often preferred over z-score or standard deviation methods for outlier removal in cases where the data may not follow a normal distribution. This approach is based on quartile measurements, thus it is less sensitive to extreme values.
The bounds for outlier detection are calculated as 1.5 times the IQR below the 25th percentile and 1.5 times the IQR above the 75th percentile. This method assumes that the data distribution is approximately symmetric around the median.
Examples
>>> data = np.array([1, 2, 3, 4, 5, 6, 100]) >>> filtered_data = remove_outliers_iqr(data) >>> print(filtered_data) [1 2 3 4 5 6]