Utilities¶

cellector.utils.broadcastable(x: ndarray, y: ndarray) → bool[source]¶

Check if two numpy arrays are broadcastable.

Parameters:

x (np.ndarray) – Two numpy arrays to check for broadcast compatibility.
y (np.ndarray) – Two numpy arrays to check for broadcast compatibility.

Returns:

True if the arrays are broadcastable, False otherwise.

Return type:

bool

cellector.utils.deprecated(reason: str, version: str | None = None)[source]¶

Decorator to mark functions as deprecated.

Parameters:

reason (str) – Reason why the function is being deprecated and what to use instead.
version (str, optional) – Version the function will be removed in.

cellector.utils.transpose(sequence: Sequence) → List[source]¶

Return a transpose of a sequence of elements in a list or tuple.

This function helps manage transposing the order of elements in a list or tuple. For example, if you have a list of lists, this will return a list of lists where the first element of each sublist in the input becomes the elements of the first sublist of the output (and second elements in each list will make up the second sublist).

Parameters:: sequence (Sequence) – A sequence of elements to transpose. Can be a list or tuple, but each should have the same number of elements.
Return type:: map of lists

Examples

To transpose a list of lists:

>>> transpose([[1, 2, 3], [4, 5, 6]])
[[1, 4], [2, 5], [3, 6]]

If you perform a function that outputs tuples in a list comprehension, but want to organize the results by the elements of the tuple rather than the iterable on the list comprehension:

>>> def func(x):
...     return x, x ** 2
>>> results = [func(i) for i in range(3)]
[(0, 0), (1, 1), (2, 4)]
>>> transpose(results)
[(0, 1, 2), (0, 1, 4)]

cellector.utils.cat_planes(list_of_sequences: List[Sequence | ndarray]) → List[Sequence | ndarray][source]¶

Concatenate a sequence of sequences into a single sequence.

Parameters:: list_of_sequences (List[Union[Sequence, np.ndarray]]) – A list of sequences to concatenate.
Returns:: A single list containing all elements from the input sequences. If all the input sequences are numpy arrays, the output will be a single numpy array.
Return type:: list or numpy.ndarray

Notes

This function is used to concatenate list of ROI data from across planes because we can optimize operations by performing them on all ROIs at once rather than performing them on each plane separately. To return to lists of each plane independently, use the split_planes function. Note that cat_planes and split_planes are not inverse operations unless the ROIs start in order of planes.

cellector.utils.split_planes(array: ndarray, plane_idx: ndarray) → List[ndarray][source]¶

Split a numpy array into a list of numpy arrays based on the plane index.

Parameters:

array (np.ndarray) – A single numpy array to split into multiple numpy arrays.
plane_idx (np.ndarray) – An array of integers indicating the plane index for each element in the sequence.

Returns:

A list of numpy arrays, each containing the elements for a single plane.

Return type:

list

Notes

This function is used to split concatenated ROI data back into separate lists for each plane after operations have been performed on all ROIs at once using the cat_planes function. It is not the inverse of cat_planes, because ROIs need not be contiguous but cat_planes will just concatenate them!

cellector.utils.flatten_roi_data(lam: List[ndarray], ypix: List[ndarray], xpix: List[ndarray], zpix: List[ndarray] | None = None) → Dict[str, ndarray][source]¶

Get flattened ROI data for use in parallel processing.

Returns flattened arrays for intensity values, y-coordinates, x-coordinates in which the data is concatenated across ROIs such that each is a single numpy array. The ROI index is also returned as a single numpy array with the same length as the other arrays to indicate which ROI each value belongs to.

Parameters:

lam (list of np.ndarrays) – Intensity values for each pixel in each ROI.
zpix (list of Union[np.ndarrays, np.ndarray]) – Z-coordinates for each ROI. If 2D data, this should be a single np.ndarray of the z-plane. If volumetric data, this should be a list of np.ndarrays, one for each ROI.
ypix (list of np.ndarrays) – Y-coordinates of pixels in each ROI.
xpix (list of np.ndarrays) – X-coordinates of pixels in each ROI.

Returns:

A dictionary containing the flattened arrays for intensity values, z-coordinates, y-coordinates, x-coordinates, and ROI index associated with each lam/z/y/x value. If zpix is not provided, then it will not be included in the output dictionary.

Return type:

dict

cellector.utils.get_roi_centroid(lam: ndarray, zpix: ndarray | int, ypix: ndarray, xpix: ndarray, method: str = 'weightedmean', asint: bool = True) → Tuple[int, int][source]¶

Calculate the centroid coordinates of an ROI.

Parameters:

lam (np.ndarray) – Intensity values for each pixel in the ROI.
zpix (Union[np.ndarray, int]) – Z-coordinates of pixels in the ROI for volumetric data, or just the z-plane for 2D data.
ypix (np.ndarray) – Y-coordinates of pixels in the ROI.
xpix (np.ndarray) – X-coordinates of pixels in the ROI.
method ({'weightedmean', 'median'}, optional) – Method to calculate the centroid: - ‘weightedmean’: weighted average using pixel intensities (default) - ‘median’: median position of pixels (independent for y & x pixels)
asint (bool, optional) – Whether to return the centroid as an integer (default). If set to False, will return a float when method=”weightedmean”.

Returns:

zc, yc, xc – Z, Y, and X coordinates of the centroid. Returns as integers by default, but will return floats if asint=False and method=”weightedmean”.

Return type:

tuple of int or float

cellector.utils.get_roi_centroids(lam: List[ndarray], zpix: ndarray | List[ndarray], ypix: List[ndarray], xpix: List[ndarray], method: str = 'weightedmean', asint: bool = True) → Tuple[ndarray, ndarray][source]¶

Get the centroid of each ROI in a list of ROIs.

Parameters:

lam (list of np.ndarrays) – Intensity values for each pixel in each ROI.
zpix (Union[np.ndarray, List[np.ndarray]]) – Z-coordinates of each ROI – if volumetric data this is a list of np.ndarrays for each ROI, if not volumetric this is a single np.ndarray of the z-plane for each ROI.
ypix (list of np.ndarrays) – Y-coordinates of pixels in each ROI.
xpix (list of np.ndarrays) – X-coordinates of pixels in each ROI.
method ({'weightedmean', 'median'}, optional) – Method to calculate the centroid: - ‘weightedmean’: weighted average using pixel intensities (default) - ‘median’: median position of pixels (independent for y & x pixels)
asint (bool, optional) – Whether to return the centroid as an integer (default). If set to False, will return a float when method=”weightedmean”.

Returns:

zc, yc, xc – Z, Y, and X coordinates of each ROI centroid. Returns as integers by default, but will return floats if asint=False and method=”weightedmean”.

Return type:

tuple of np.ndarrays of int or float