processing

utils

sparcscore.processing.utils.plot_image(array, size=(10, 10), save_name='', cmap='magma', **kwargs)

Visualize and optionally save an input array as an image.

This function displays a 2D array using matplotlib and can save the resulting image as a PNG file.

Parameters

array (np.array) – Input 2D numpy array to be plotted.
size (tuple of int, optional) – Figure size in inches, by default (10, 10).
save_name (str, optional) – Name of the output file, without extension. If not provided, image will not be saved, by default “”.
cmap (str, optional) – Color map used to display the array, by default “magma”.
**kwargs (dict) – Additional keyword arguments to be passed to ax.imshow.

Example

>>> array = np.random.rand(10, 10)
>>> plot_image(array, size=(5, 5))

sparcscore.processing.utils.visualize_class(class_ids, seg_map, background, *args, **kwargs)

Visualize specific classes in a segmentation map by highlighting them on top of a background image.

This function takes in class IDs and a segmentation map, and creates an output visualization where the specified classes are highlighted on top of the provided background image.

Parameters

class_ids (array-like) – A list or array of integers representing the class IDs to be highlighted.
seg_map (2D array-like) – A 2D array representing the segmentation map, where each value corresponds to a class ID.
background (2D/3D array-like) – Background image (2D or 3D) on which the classes will be highlighted. Its size should match that of seg_map.
*args (additional positional arguments) – Any additional positional arguments that are passed to the underlying plotting functions.
**kwargs (additional keyword arguments) – Any additional keyword arguments that are passed underlying plotting functions.

Returns

The function will display the highlighted image but does not return any values.

Return type

None

Example

>>> class_ids = [1, 2]
>>> seg_map = np.array([[0, 1, 0], [1, 2, 1], [2, 0, 1]])
>>> background = np.random.random((3, 3)) * 255
>>> visualize_class(class_ids, seg_map, background)

sparcscore.processing.utils.download_testimage(folder)

Download a set of test images to a provided folder path.

Parameters: folder (string) – The path of the folder where the test images will be saved.
Returns: returns – A list containing the local file paths of the downloaded images.
Return type: list

Example

>>> folder = "test_images"
>>> downloaded_images = download_testimage(folder)
Successfully downloaded testimage_dapi.tiff from https://zenodo.org/record/5701474/files/testimage_dapi.tiff?download=1
Successfully downloaded testimage_wga.tiff from https://zenodo.org/record/5701474/files/testimage_wga.tiff?download=1
>>> print(downloaded_images)
['test_images/testimage_dapi.tiff', 'test_images/testimage_wga.tiff']

sparcscore.processing.utils.flatten(l)

Flatten a list of lists into a single list.

This function takes in a list of lists (nested lists) and returns a single list containing all the elements from the input lists.

Parameters: l (list of lists) – A list containing one or more lists as its elements.
Returns: flattened_list – A single list containing all elements from the input lists.
Return type: list

Example

>>> nested_list = [[1, 2, 3], [4, 5], [6, 7, 8, 9]]
>>> flatten(nested_list)
[1, 2, 3, 4, 5, 6, 7, 8, 9]

preprocessing

sparcscore.processing.preprocessing.percentile_normalization(im, lower_percentile=0.001, upper_percentile=0.999)

Normalize an input image channel-wise based on defined percentiles.

The percentiles will be calculated, and the image will be normalized to [0, 1] based on the lower and upper percentile.

Parameters

im (np.array) – Numpy array of shape (height, width) or (channels, height, width).
lower_percentile (float, between [0, 1]) – Lower percentile used for normalization, all lower values will be clipped to 0.
upper_percentile (float, between [0, 1]) – Upper percentile used for normalization, all higher values will be clipped to 1.

Returns

im – Normalized Numpy array.

Return type

np.array

Example

>>> img = np.random.rand(3, 4, 4) # (channels, height, width)
>>> norm_img = percentile_normalization(img, 0.001, 0.999)

sparcscore.processing.preprocessing.rolling_window_mean(array, size, scaling=False)

Compute rolling window mean and normalize the input 2D array.

The function takes an input 2D array and a window size. It calculates the mean within a rolling window of provided size and removes the mean from each element in the window. The modified array is returned. If scaling is set to True, the chunk is normalized by dividing by its standard deviation. Function is numba optimized.

Parameters

array (np.array) – Input 2D numpy array.
size (int) – Size of the rolling window.
scaling (bool, optional) – If True, normalizes the chunk by dividing it by standard deviation, by default False.

Returns

array – Processed 2D numpy array.

Return type

np.array

Example

>>> array = np.random.rand(10, 10)
>>> rolling_array = rolling_window_mean(array, size=5, scaling=False)

sparcscore.processing.preprocessing.origins_from_distance(array)

Compute a list of local peaks (origins) in the input array. The function applies a Gaussian filter to the input array, creates a binary mask using a threshold based on the standard deviation of the filtered data, and performs a distance transform on the mask. It finds the local peaks of the distance-transformed image with a minimum distance between the peaks, and returns the coordinates and a map of the peaks.

Parameters

array (np.array) – Input 2D numpy array to be processed.

Returns

peak_list (np.array) – List of peak coordinates, shape (num_peaks, 2).
peak_map (np.array) – Binary map of peaks, same shape as input array.

Example

>>> array = np.random.rand(10, 10)
>>> peak_list, peak_map = origins_from_distance(array)

sparcscore.processing.preprocessing.MinMax(inarr)

Perform Min-Max normalization on the input array. The function scales the input array values to the range [0, 1] using Min-Max normalization. If the range of the input array (i.e., max - min) is zero, the original array is returned unchanged.

Parameters: inarr (np.array) – Input numpy array to be normalized.
Returns: Min-Max normalized numpy array.
Return type: np.array

Example

>>> array = np.random.rand(10, 10)
>>> normalized_array = MinMax(array)

segmentation

sparcscore.processing.segmentation.global_otsu(image)

Calculate the optimal global threshold for an input grayscale image using Otsu’s method.

Otsu’s method maximizes the between-class variance and minimizes the within-class variance.

Parameters: image (numpy.ndarray) – Input grayscale image.
Returns: Optimal threshold value calculated using Otsu’s method.
Return type: float

Example

>>> import numpy as np
>>> from skimage import data
>>> image = data.coins()
>>> threshold = global_otsu(image)
>>> print(threshold)

sparcscore.processing.segmentation.segment_global_threshold(image, dilation=4, min_distance=10, peak_footprint=7, speckle_kernel=4, debug=False)

Segments an image based on a global threshold determined using Otsu’s method, followed by peak detection using distance transforms and watershed segmentation.

Parameters

image (numpy.ndarray) – Input grayscale image.
dilation (int, optional) – Size of the structuring element for the dilation operation (default is 4).
min_distance (int, optional) – Minimum number of pixels separating peaks (default is 10).
peak_footprint (int, optional) – Size of the structuring element used for finding local maxima (default is 7).
speckle_kernel (int, optional) – Size of the structuring element used for speckle removal (default is 4).
debug (bool, optional) – If True, intermediate results are plotted (default is False).

Returns

Labeled array, where each unique feature in the input image has a unique label.

Return type

numpy.ndarray

Examples

>>> import matplotlib.pyplot as plt
>>> from skimage import data
>>> from segment import segment_global_threshold
>>> coins = data.coins()
>>> labels = segment_global_threshold(coins, dilation=5, min_distance=20, peak_footprint=7, speckle_kernel=3, debug=True)
>>> plt.imshow(labels, cmap='jet')
>>> plt.colorbar()
>>> plt.show()

sparcscore.processing.segmentation.segment_local_threshold(image, dilation=4, thr=0.01, median_block=51, min_distance=10, peak_footprint=7, speckle_kernel=4, median_step=1, debug=False)

This function takes a unprocessed image with low background noise and extracts and segments approximately round foreground objects based on intensity. The image is segmented using the local (adaptive) threshold method. It first applies a local threshold based on the median value of a block of pixels, followed by peak detection using distance transforms and watershed segmentation.

Parameters

image (numpy.ndarray) – Input grayscale image.
dilation (int, optional) – Size of the structuring element for the dilation operation (default is 4).
thr (float, optional) – The value added to the median of the block of pixels when calculating the local threshold (default is 0.01).
median_block (int, optional) – Size of the block of pixels used to compute the local threshold (default is 51).
min_distance (int, optional) – Minimum number of pixels separating peaks (default is 10).
peak_footprint (int, optional) – Size of the structuring element used for finding local maxima (default is 7).
speckle_kernel (int, optional) – Size of the structuring element used for speckle removal (default is 4).
median_step (int, optional) – The step size for downsampling the image before applying the local threshold (default is 1).
debug (bool, optional) – If True, intermediate results are plotted (default is False).

Returns

Labeled array, where each unique feature in the input image has a unique label.

Return type

numpy.ndarray

Example

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from skimage import data
>>> image = data.coins()
>>> labels = segment_local_threshold(image, dilation=4, thr=0.01, median_block=51, min_distance=10, peak_footprint=7, speckle_kernel=4, debug=False)
>>> plt.imshow(labels, cmap=‘jet’)
>>> plt.colorbar()
>>> plt.show()

sparcscore.processing.segmentation.shift_labels(input_map, shift, return_shifted_labels=False)

Shift the labels of a given labeled map (2D or 3D numpy array) by a specific value. Return the shifted map and the labels that are in contact with the edges of the canvas. All labels but the background are incremented and all classes in contact with the edges of the canvas are returned.

Parameters

input_map (numpy.ndarray) – Input segmentation as a 2D or 3D numpy array of integers.
shift (int) – Value to increment the labels by.
return_shifted_labels (bool, optional) – If True, return the edge labels after shifting (default is False). If False will return the edge labels before shifting.

Returns

shifted_map (numpy.ndarray) – The labeled map with incremented labels.
edge_labels (list) – List of unique labels in contact with the edges of the canvas.

Example

>>> import numpy as np
>>> input_map = np.array([[1, 0, 0],
                          [0, 2, 0],
                          [0, 0, 3]])
>>> shift = 10
>>> shifted_map, edge_labels = shift_labels(input_map, shift)
>>> print(shifted_map)
array([[11,  0,  0],
       [ 0, 12,  0],
       [ 0,  0, 13]])
>>> print(edge_labels)
[11, 13]

sparcscore.processing.segmentation.remove_classes(label_in, to_remove, background=0, reindex=False)

Wrapper function for the numba optimized _remove_classes function.

Parameters

label_in (numpy.ndarray) – Input labeled array.
to_remove (list or array-like) – List of label classes to remove.
background (int, optional) – Value used to represent the background class (default is 0).
reindex (bool, optional) – If True, reindex the remaining classes after removal (default is False).

Returns

label – Labeled array with specified classes removed or reindexed.

Return type

numpy.ndarray

Example

>>> import numpy as np
>>> label_in = np.array([[1, 2, 1], [1, 0, 2], [0, 2, 3]])
>>> to_remove = [1, 3]
>>> remove_classes(label_in, to_remove)
array([[0, 2, 0],
       [0, 0, 2],
       [0, 2, 0]])

sparcscore.processing.segmentation.contact_filter_lambda(label, background=0)

Calculate the contact proportion of classes in the labeled array.

This function calculates the surrounding background and non-background elements for each class in the label array and returns the proportion of background elements to total surrounding elements for each class.

Parameters

label (numpy.ndarray) – Input labeled array.
background (int, optional) – Value used to represent the background class (default is 0).

Returns

pop – Array containing the contact proportion for each class.

Return type

numpy.ndarray

Example

>>> import numpy as np
>>> label = np.array([[0, 1, 1],
                  [0, 2, 1],
                  [0, 0, 2]])
>>> contact_filter_lambda(label)
array([1.        , 1.,  0.6 ])

sparcscore.processing.segmentation.contact_filter(inarr, threshold=1, reindex=False, background=0)

Filter the input labeled array based on its contact with background pixels.

This function filters an input labeled array by removing classes with a background contact proportion less than the given threshold.

Parameters

inarr (numpy.ndarray) – Input labeled array.
threshold (int, optional) – Specifies the minimum background contact proportion for class retention (default is 1).
reindex (bool, optional) – If True, reindexes the remaining classes after removal (default is False).
background (int, optional) – Value used to represent the background class (default is 0).

Returns

label – Filtered labeled array.

Return type

numpy.ndarray

Example

>>> import numpy as np
>>> inarr = np.array([[0, 1, 1],
                  [0, 2, 1],
                  [0, 0, 2]])
>>> contact_filter(inarr, threshold=0.5)
array([[0, 1, 1],
       [0, 0, 1],
       [0, 0, 0]])

sparcscore.processing.segmentation.size_filter(label, limits=[0, 100000], background=0, reindex=False)

Filter classes in a labeled array based on their size (number of pixels).

This function filters classes in the input labeled array by removing classes that have a size (number of pixels) outside the provided limits. Optionally, it can reindex the remaining classes.

Parameters

label (numpy.ndarray) – Input labeled array.
limits (list, optional) – List containing the minimum and maximum allowed class size (number of pixels) (default is [0, 100000]).
background (int, optional) – Value used to represent the background class (default is 0).
reindex (bool, optional) – If True, reindexes the remaining classes after removal (default is False).

Returns

label – Filtered labeled array.

Return type

numpy.ndarray

Example

>>> import numpy as np
>>> label = np.array([[0, 1, 1],
                      [0, 2, 1],
                      [0, 0, 2]])
>>> size_filter(label, limits=[1, 2])
array([[0, 0, 0],
       [0, 2, 0],
       [0, 0, 2]])

sparcscore.processing.segmentation.numba_mask_centroid(mask, debug=False, skip_background=True)

Calculate the centroids of classes in a given mask.

This function calculates the centroids of each class in the mask and returns an array with the (y, x) coordinates of the centroids, the number of pixels associated with each class, and the id number of each class.

Parameters

mask (numpy.ndarray) – Input mask containing classes.
debug (bool, optional) – Debug flag (default is False).
skip_background (bool, optional) – If True, skip background class (default is True).

Returns

center (numpy.ndarray) – Array containing the (y, x) coordinates of the centroids of each class.
points_class (numpy.ndarray) – Array containing the number of pixels associated with each class.
ids (numpy.ndarray) – Array containing the id number of each class.

Example

>>> import numpy as np
>>> mask = np.array([[0, 1, 1], [0, 2, 1], [0, 0, 2]])
>>> numba_mask_centroid(mask)
(array([[0.33333333, 1.66666667],
        [1.5       , 1.5       ]]),
array([3, 2], dtype=uint32),
array([1, 2], dtype=int32))