Cellori API

Cellori Class

Cellori supports both GUI and command line options for nuclei segmentation.

class cellori.cellori.Cellori(image, **kwargs)

Bases: object

Cellori class object that takes the path to an image file or an image array.

Parameters

  • image (str or numpy.ndarray) – The path to an ND2 or TIFF file or a numpy.ndarray of an image that has already been loaded.

  • nd2_overlap (float, optional, default 0.1) – The overlap percentage used by StitchWell for ND2 stitching. If None, the value will be determined by automatic overlap calculation. This value is ignored if image is not the path to an ND2 file.

  • nuclei_channel (int, optional, default 0) – The index of the channel containing the nuclei for segmentation. This value is ignored if image has a single channel.

Raises

  • ValueError – If image is an invalid image path or array.

  • ValueError – If nuclei_channel is not specified for an image with multiple channels.

  • ValueError – If image has invalid dimensions.

gui(estimate_parameters=True)

Initiates the Cellori GUI.

Parameters

estimate_parameters (bool, optional, default True) – Whether or not to run automatic parameter detection.

Returns

  • masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N. The most recent segmentation result is returned, if any.

  • coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei. The most recent segmentation result is returned, if any.

  • image (numpy.ndarray) – Array of the image for use in post-processing. The most recent segmentation result is returned, if any.

segment(segmentation_mode='combined', threshold_locality=0.5, sigma=None, nuclei_diameter=None, coordinate_format='indices')

Segments the image using the Cellori algorithm.

Parameters

  • segmentation_mode ({'combined', 'intensity', 'morphology'}, optional, default 'combined') –

    • ‘combined’: Use a combined maxima metric that incorporates both intensity and morphology.

    • ‘intensity’: Use an intensity-only maxima metric.

    • ‘morphology’: Use a morphology-only maxima metric.

  • threshold_locality (float, optional, default 0.5) – Fractional weight on local intensity used in thresholding. The value must be between 0 (global thresholding) and 1 (local thresholding).

  • sigma (float, optional, default 1.5) – Gaussian sigma used for denoising. If None, the value will be determined by automatic parameter detection.

  • nuclei_diameter (int, optional, default None) – Estimated lower bound of nuclei diameters. Any objects smaller than this threshold will not be considered for segmentation. If None, the value will be determined by automatic parameter detection.

  • coordinate_format ({'xy', 'indices'}, optional, default 'indices') –

    • ‘xy’: Format coordinates for plotting on standard XY axes.

    • ‘indices’: Format coordinates as indices of the original image array.

Returns

  • masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

  • coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei.

  • image (numpy.ndarray) – Array of the image for use in post-processing.

Raises

  • ValueError – If segmentation_mode is an invalid segmentation mode.

  • ValueError – If coordinate_format is an invalid coordinate format.

_segment(image, watershed_labeled, segmentation_mode, threshold_locality, sigma, nuclei_diameter, origin=None)

(For internal use) Get masks and nuclei coordinates using the Cellori algorithm.

Parameters

  • image (numpy.ndarray) – Array of the image to be segmented.

  • watershed_labeled (numpy.ndarray) – Array of labeled watershed regions.

  • segmentation_mode ({'combined', 'intensity', 'morphology'}) –

    • ‘combined’: Use a combined maxima metric that incorporates both intensity and morphology.

    • ‘intensity’: Use an intensity-only maxima metric.

    • ‘morphology’: Use a morphology-only maxima metric.

  • threshold_locality (float) – Fractional weight on local intensity used in thresholding. The value must be between 0 (global thresholding) and 1 (local thresholding).

  • sigma (float) – Gaussian sigma used for denoising. If None, the value will be determined by automatic parameter detection.

  • nuclei_diameter (int) – Estimated lower bound of nuclei diameters. Any objects smaller than this threshold will not be considered for segmentation. If None, the value will be determined by automatic parameter detection.

  • origin (tuple, optional, default None) – Origin coordinates of the GUI preview region.

Returns

  • masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

  • coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei.

_find_nuclei(image, watershed_labeled, segmentation_mode, sigma, threshold_locality, nuclei_diameter, origin)

(For internal use) Find nuclei using the Cellori algorithm.

Parameters

  • image (numpy.ndarray) – Array of the image to be segmented.

  • watershed_labeled (numpy.ndarray) – Array of labeled watershed regions.

  • segmentation_mode ({'combined', 'intensity', 'morphology'}) –

    • ‘combined’: Use a combined maxima metric that incorporates both intensity and morphology.

    • ‘intensity’: Use an intensity-only maxima metric.

    • ‘morphology’: Use a morphology-only maxima metric.

  • threshold_locality (float) – Fractional weight on local intensity used in thresholding. The value must be between 0 (global thresholding) and 1 (local thresholding).

  • sigma (float) – Gaussian sigma used for denoising. If None, the value will be determined by automatic parameter detection.

  • nuclei_diameter (int) – Estimated lower bound of nuclei diameters. Any objects smaller than this threshold will not be considered for segmentation. If None, the value will be determined by automatic parameter detection.

  • origin (tuple) – Origin coordinates of the GUI preview region.

Returns

  • coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei.

  • binary (numpy.ndarray) – Binarized array of the same size as the original image.

static _get_masks(binary, coords)

(For internal use) Get masks using the watershed algorithm.

Parameters

  • binary (numpy.ndarray) – Binarized array of the same size as the original image.

  • coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei.

Returns

masks – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

Return type

numpy.ndarray

_merge_correct(masks)

(For internal use) Correct for oversegmentation via rule-based region merging.

Parameters

masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

Returns

masks – Labeled array of the image after region merging corrections.

Return type

numpy.ndarray

static _conditional_local_threshold(image, mask, global_binary, block_size, k_max, c)

(For internal use) Calculate conditional local threshold.

Parameters

  • image (numpy.ndarray) – Array of the image to be thresholded.

  • mask (numpy.ndarray) – Array marking the region to be thresholding.

  • global_binary (numpy.ndarray) – Binarized array of the image using global thresholding.

  • block_size (int) – Odd size of pixel neighborhood which is used for local thresholding (e.g., 3, 5, 7, …, 21).

  • k_max (float) – Maximum fractional weight on local intensity used in thresholding. The value must be between 0 (global thresholding) and 1 (local thresholding).

  • c (float) – Global constant subtracted from local threshold array.

Returns

threshold – Array of local threshold values. All pixels in the input image higher than the corresponding pixel in the threshold array are considered foreground.

Return type

numpy.ndarray

_estimate_parameters()

(For internal use) Estimate parameters for segmentation.

_indices_to_xy(coords)

(For internal use) Convert array indices to XY coordinates.

Parameters

coords (numpy.ndarray) – Array of size (N, 2) with the coordinates of cell nuclei formatted as indices of the original image array.

Returns

coords – Array of size (N, 2) with the coordinates of cell nuclei formatted for plotting on standard XY axes.

Return type

numpy.ndarray

static _calculate_edge_indices(indices, image)

(For internal use) Calculate indices for slicing near the edges of an array.

Parameters

indices (list) – Indices for array slicing.

Returns

outlines – Adjusted indices for array slicing near the edges.

Return type

list

static _normalize(array)

(For internal use) Normalize an array.

Parameters

array (numpy.ndarray) – Array to be normalized.

Returns

array_normalized – Normalized array.

Return type

numpy.ndarray

Helper Functions

cellori.utils.overlay_segmentation(image, masks, overlay_mode='both', mask_alpha=0.5, mask_ncolors=5, sinebow_theta=1, outline_color=None, contrast_z=5, gamma=1)

Overlay segmentation results on the original image.

Parameters

  • image (numpy.ndarray) – Array of the image segmented by the Cellori algorithm.

  • masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

  • overlay_mode ({'both', 'masks', 'outlines'}, optional, default 'both') –

    • ‘both’: Overlay both masks and outlines.

    • ‘masks’: Overlay masks only.

    • ‘outlines’: Overlay outlines only.

  • mask_alpha (float, optional, default 0.5) – Alpha value of the mask overlay. The value must be between 0 (transparent) and 1 (opaque).

  • mask_ncolors (int, optional, default 5) – Number of colors used for coloring the mask overlay.

  • sinebow_theta (float, optional, default 1) – Phase factor in radians for color generation using sinebow.

  • outline_color (tuple, optional, default None) – Color of outlines in RGB, formatted as (r,g,b).

  • contrast_z (float, optional, default 5) – Number of standard deviations from the mean used for intensity rescaling.

  • gamma (float, optional, default 1) – Gamma value used for brightness adjustment.

Returns

image – Array of the same size as the original image with overlayed segmentation results.

Return type

numpy.ndarray

cellori.utils._masks_to_rgb(masks, ncolors, theta)

(For internal use) Convert masks to RGB image.

Parameters

masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

Returns

masks – Relabeled mask array with consecutive integer assignments for clustered regions.

Return type

numpy.ndarray

cellori.utils._masks_to_outlines(masks)

(For internal use) Convert masks to outlines for displaying GUI segmentation results.

Parameters

masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

Returns

outlines – Array of the same size as the original image with outlines around each cell.

Return type

numpy.ndarray

cellori.utils._relabel(masks, color_label)

(For internal use) Relabel mask array by assigning consecutive integers to clustered regions.

Parameters

masks (numpy.ndarray) – Labeled array of the same size as the original image with background pixels as 0 and cells as 1, 2, 3, …, N.

Returns

masks – Relabeled mask array with consecutive integer assignments for clustered regions.

Return type

numpy.ndarray

cellori.utils._sinebow(ncolors, theta)

(For internal use) Generate n-color dictionary using the sinebow algorithm.

Parameters

  • ncolors (int) – Number of colors to generate.

  • theta (float) – Phase factor in radians for color generation.

Returns

color_dict – Color dictionary.

Return type

dict

cellori.utils._vector_map(array, array_map)

(For internal use) Vectorized implementation for applying a map to an array.

Parameters

  • array (numpy.ndarray) – Array input.

  • array_map (dict) – Map to be applied on the array.

Returns

array – Array output.

Return type

numpy.ndarray