channel#

This module allows to compare signal between different channels

The basic idea is to exploit the data of:

  • a binary mask per channel

  • a dataframe with a representative point per connected component, given in pixel coords with possibly extra measurement information for the nucleus in the respective channel, eg some intensity measurement.

The idea is to be able to determine if two detected nuclei in distinct channels correspond indeed to the same nucleus.

Note

We have to rely on well aligned channel images for this module to work.

The simplest method is to break symmetry and have a reference channel that marks all nuclei of the studied cell category (e.g. all cell type or neurons)

Then, for each reference channel detected nucleus, decide if it is to be considered positive for the the other channels.

This can be made relying on the following capabilities, given two channels - Compute the overlap of each connected component of a given channel with the other channel, component-wise or globally or, more generally - compute a matching score based on the information we have

Ideally, all of this is to be made efficiently both with quick sequential code and parallelization techniques.

Warning

The current version of this module deals only with 3d images. See shape_detection.label_pixels_from_centers commented version for a 2d version.

class Channel(binary_img: ndarray, dataframe: DataFrame, coord_names=('x', 'y', 'z'), voxel_dims=None, physical_origin=None, channel_name='', clean_image: bool = False, already_clean: bool = False)[source]#

Bases: object

In our context a channel is represented by a binary mask and some voxel coordinates in a dataframe. The voxel coordinates should be a set of representatives for the partition of the True voxels in the binary mask in connected components for the 1-connectivity (also termed as 6 connectivity in 3d). We admit the situation where not all connected components have a representative but the points must belong to distinct components.

blobwise_overlaps(other_channel: Channel) → ndarray[source]#

Return the matrix of overlaps.

Parameters:

other_channel (Channel) – The channel to compare with self.

Returns

np.ndarray

The matrix M such that M[i,j] is the overlap count in voxels for blob of index i for self and the blob of index j for other_channel.

bounding_box(i) → tuple[slice, ...][source]#

Return the bounding box of the ith nucleus.

Parameters:

i (int) – the index of the considered nucleus.

Returns

tuple[slice,…]

the tuple of slices (slice_0, slice_1, slice_2,…) that defines the bounding box

center(i) → tuple[int, ...][source]#

Return the center of the bounding box of the ith nucleus.

Parameters:

i (int) – the index of the considered nucleus.

Returns

tuple[int,…]

the tuple of coords for the central voxel

centers()[source]#
centers_df(description='center of bounding box')[source]#
centers_distances(other_channel: Channel) → ndarray[source]#

Return array of distances between centers across the two channels.

Parameters:

other_channel (Channel) – Channel to compare with self

Returns

np.ndarray

distance matrix A: A[index_1,index_2] is the distance between the centers of the nucleus indexed by index_1 in self.dataframe and the nucleus indexed by index_2 in other_channel.dataframe.

closest_center_distances(other_channel: Channel, return_min_indices=True) → ndarray | tuple[ndarray, ndarray][source]#

Return the distances to the closest centers in other_channel for each center in self.

Parameters:

  • other_channel (Channel) – _description_

  • return_min_indices (bool, optional.) – Defaults to True.

Returns

similar to max_blobwise_overlap

compare(other_channel: Channel, blob_diameter: int, size_min: int, size_max: int, processes: int | None = None) → DataFrame[source]#

Return a final colocalization report

Parameters:

  • other_channel (Channel) – _description_

  • blob_diameter (int) – an upper bound for the sought blobs diameters, in PHYSICAL units

  • size_min (int) – min size in voxels for a block dimension

  • size_max (int) – max size in voxels for a block dimension

  • processes (int | None, optional) – positive integer or None, the number of processes to use for block processing. Defaults to None, if None the number of processes will equal the computer’s number of processors.

Returns

pd.DataFrame

A colocalization report in pandas dataframe format

labels()[source]#

Return the labeled image from the binary mask

masked_sizes(mask)[source]#

Return the list of the sizes of the non-masked part of each nucleus

Returns

list[int]

The list of counts of True pixels in mask for each nucleus, in the order of our dataframe.

max_blobwise_overlap_rates(other_channel: Channel, return_max_indices: bool = True) → ndarray | tuple[ndarray, ndarray][source]#
For each nucleus of self, compute the max overlap rate with a single nucleus of other_channel.

if return_max_indices is True, nuclei indices that realize the max are also returned.

Parameters:

  • other_channel (Channel) – channel to compare with self

  • return_max_indices (bool) –

    Whether to return the indices of the nuclei of other_channel that realize the maxima (i.e. argmax).

    (default True)

Returns

np.ndarray

the max overlap rate for each nucleus in the order of self.dataframe

np.ndarray

the array of nucleus indices of other_channel that realize the maxima.

max_blobwise_overlaps(other_channel: Channel, return_max_indices: bool = True) → ndarray | tuple[ndarray, ndarray][source]#
For each nucleus of self, compute the max overlap with a single nucleus of other_channel.

if return_max_indices is True, nuclei indices that realize the max are also returned.

Parameters:

  • other_channel (Channel) – channel to compare with self

  • return_max_indices (bool) –

    whether to return the indices of the nuclei of other_channel that realize the maxima (i.e. argmax).

    (default True)

Returns

np.ndarray

the max overlap (in voxels) for each nucleus in the order of self.dataframe

np.ndarray

the array of nucleus indices of other_channel that realize the maxima.

nucleus(index)[source]#

Return the nucleus associated to a given index, as a mask.

Parameters:

  • index (int)

  • self.dataframe (index for the chosen representative point in)

overlap_rates(other_channel: Channel)[source]#

Return the rate of positive pixels for other_channel in each nucleus

Parameters:

other_channel (Channel) – The Channel to compare with self

Returns

np.array

The array of rates, in the order of self.dataframe

channel_count = 0#
channel_names = []#
property index_label_correspondence: array#

Return the labels of nuclei in the nuclei index order

Returns

np.array

the flat array of the labels in the nuclei index order

property label_index_correspondence#
property representative_points#
property sizes#

Return the list of the sizes of nuclei in the order of our dataframe.

Returns

np.ndarray

The 1D array of sizes of nuclei (ints) in the order of our dataframe.

bilabel_bincount(labels_1: array, labels_2: array) → array[source]#

Count the number of occurrences for all the conjunctions of labels.

Parameters:

  • labels_1 (np.array) – an array of labels

  • labels_2 (np.array) – another array of labels, with the same shape as labels_1

Returns

np.array

The array counts such that counts[i,j] == np.count_nonzero((labels_1==i) * (labels_2==j)).

cleanup(binary_img: ndarray, df: DataFrame, coord_names: List[str], as_memmap: bool = False)[source]#

Return the labeled image giving exactly the connected components of binary_img that correspond to a representative in dataframe. This saves a lot of memory and time by not labeling the whole image. To further save memory, use the as_memmap argument to store the result and temporary results in a memmap

Parameters:

  • binary_img (np.ndarray) – The source binary image

  • df (pd.DataFrame) – The dataframe containing the coordinates of the representatives

  • coord_names (List[str]) – The names of the columns in the dataframe that contain the coordinates

  • as_memmap (bool) – If True, the result will be a memmap object, otherwise a numpy array.

Returns

np.ndarray | MemmapSource

The labeled image, with the same shape as binary_img.

compress_dtype(arr, signed)[source]#
contiguous_labels(labels)[source]#
distances(points_1: ndarray, points_2: ndarray) → ndarray[source]#

Compute the distances between the points in points_1 and those of points_2.

Parameters:

  • points_1 (np.ndarray) – array of points of shape (n_points_1,dim)

  • points_2 (np.ndarray) – array of points of shape (n_points_2,dim)

Returns

np.ndarray

distance matrix A: A[i,j] is the distance between the ith point in points_1 and the jth point in points_2.

get_minimum_dtype(max_val, signed=True)[source]#
random_channel(shape, num_points, min_radius, max_radius)[source]#

Return a random Channel of given shape. The underlying image is obtained by successive attempts of blob additions. If the candidate blob would be connected with existing blobs, it is rejected.

Parameters:

  • shape (tuple) – 3d shape for the Channel binary_image attribute

  • num_points (int) – number of attempts to add a blob

  • min_radius (_type_) – min radius for candidate blob, if on the boundary the resulting blob could have smaller radius

  • max_radius (_type_) – max radius for any blob in the final Channel, as detected as 1-connected components

watershed_label(binary_img: ndarray, representatives: tuple[ndarray, ...], label_values: ndarray, connectivity=1, dtype=None)[source]#

Label the connected components of binary image, assigning the values for a set of representatives.

Any connected component without a reprenstative is labeled 0.

Parameters:

  • binary_img (np.ndaray) – n-dimensional binary image (0= background,1=foreground)

  • representatives (tuple[np.ndarray,...]) – n-tuple of flat integer arrays of the same size, say k. They give the n coordinates of the k representatives.

  • label_values (np.ndarray) – flat size k array specifying the sought label for each representative in the output

  • connectivity (int | np.ndarray optional) – a specification of the connectivity notion, as in skimage label or watershed

  • dtype (_type_, optional) – dtype of the output. must be a uint or float dtype if specified. Defaults to None. If None, the smallest suitable uint dtype is used.

Returns

np.ndarray :

The labeling of binary_img with the specified labels, where all the connected components without any element in repesentatives ares erased.

Raises:

ValueError – An error is raised if negative label_values are passed.