Automated spot detection
Functions used to detect spots in a 2D or 3D image. Detection is performed in three steps:
Image is denoised and spots are enhanced by using a Laplacian of Gaussian (LoG) filter.
Peaks are detected in the filtered image with a local maximum detection algorithm.
An intensity threshold is applied to discriminate actual spots from noisy background.
Detect spots
The main function for spot detection is:
It is also possible to perform the main steps of the spot detection separately:
See an example of application here.
- bigfish.detection.detect_spots(images, threshold=None, remove_duplicate=True, return_threshold=False, voxel_size=None, spot_radius=None, log_kernel_size=None, minimum_distance=None)
Apply LoG filter followed by a Local Maximum algorithm to detect spots in a 2-d or 3-d image.
We smooth the image with a LoG filter.
We apply a multidimensional maximum filter.
A pixel which has the same value in the original and filtered images is a local maximum.
We remove local peaks under a threshold.
We keep only one pixel coordinate per detected spot.
- Parameters:
- imagesList[np.ndarray] or np.ndarray
Image (or list of images) with shape (z, y, x) or (y, x). If several images are provided, the same threshold is applied.
- thresholdint, float or None
A threshold to discriminate relevant spots from noisy blobs. If None, optimal threshold is selected automatically. If several images are provided, one optimal threshold is selected for all the images.
- remove_duplicatebool
Remove potential duplicate coordinates for the same spots. Slow the running.
- return_thresholdbool
Return the threshold used to detect spots.
- voxel_sizeint, float, Tuple(int, float), List(int, float) or None
Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- spot_radiusint, float, Tuple(int, float), List(int, float) or None
Radius of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same radius is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- log_kernel_sizeint, float, Tuple(int, float), List(int, float) or None
Size of the LoG kernel. It equals the standard deviation (in pixels) used for the gaussian kernel (one for each dimension). One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same standard deviation is applied to every dimensions. If None, we estimate it with the voxel size and spot radius.
- minimum_distanceint, float, Tuple(int, float), List(int, float) or None
Minimum distance (in pixels) between two spots we want to be able to detect separately. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same distance is applied to every dimensions. If None, we estimate it with the voxel size and spot radius.
- Returns:
- spotsList[np.ndarray] or np.ndarray, np.int64
Coordinates (or list of coordinates) of the spots with shape (nb_spots, 3) or (nb_spots, 2), for 3-d or 2-d images respectively.
- thresholdint or float
Threshold used to discriminate spots from noisy blobs.
- bigfish.detection.local_maximum_detection(image, min_distance)
Compute a mask to keep only local maximum, in 2-d and 3-d.
We apply a multidimensional maximum filter.
A pixel which has the same value in the original and filtered images is a local maximum.
Several connected pixels can have the same value. In such a case, the local maximum is not unique.
In order to make the detection robust, it should be applied to a filtered image (using
bigfish.stack.log_filter()for example).- Parameters:
- imagenp.ndarray
Image to process with shape (z, y, x) or (y, x).
- min_distanceint, float, Tuple(int, float), List(int, float)
Minimum distance (in pixels) between two spots we want to be able to detect separately. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same distance is applied to every dimensions.
- Returns:
- masknp.ndarray, bool
Mask with shape (z, y, x) or (y, x) indicating the local peaks.
- bigfish.detection.spots_thresholding(image, mask_local_max, threshold, remove_duplicate=True)
Filter detected spots and get coordinates of the remaining spots.
In order to make the thresholding robust, it should be applied to a filtered image (using
bigfish.stack.log_filter()for example). If the local maximum is not unique (it can happen if connected pixels have the same value), a connected component algorithm is applied to keep only one coordinate per spot.- Parameters:
- imagenp.ndarray
Image with shape (z, y, x) or (y, x).
- mask_local_maxnp.ndarray, bool
Mask with shape (z, y, x) or (y, x) indicating the local peaks.
- thresholdfloat, int or None
A threshold to discriminate relevant spots from noisy blobs. If None, detection is aborted with a warning.
- remove_duplicatebool
Remove potential duplicate coordinates for the same spots. Slow the running.
- Returns:
- spotsnp.ndarray, np.int64
Coordinate of the local peaks with shape (nb_peaks, 3) or (nb_peaks, 2) for 3-d or 2-d images respectively.
- masknp.ndarray, bool
Mask with shape (z, y, x) or (y, x) indicating the spots.
Find a threshold (automatically)
The need to set an appropriate threshold for each image is a real bottleneck that limits the possibility to scale a spot detection. Our method includes a heuristic function to to automatically set this threshold:
- bigfish.detection.automated_threshold_setting(image, mask_local_max)
Automatically set the optimal threshold to detect spots.
In order to make the thresholding robust, it should be applied to a filtered image (using
bigfish.stack.log_filter()for example). The optimal threshold is selected based on the spots distribution. The latter should have an elbow curve discriminating a fast decreasing stage from a more stable one (a plateau).- Parameters:
- imagenp.ndarray
Image with shape (z, y, x) or (y, x).
- mask_local_maxnp.ndarray, bool
Mask with shape (z, y, x) or (y, x) indicating the local peaks.
- Returns:
- optimal_thresholdint
Optimal threshold to discriminate spots from noisy blobs.
- bigfish.detection.get_breaking_point(x, y)
Select the x-axis value where a L-curve has a kink.
Assuming a L-curve from A to B, the ‘breaking_point’ is the more distant point to the segment [A, B].
- Parameters:
- xnp.array
X-axis values.
- ynp.array
Y-axis values.
- Returns:
- breaking_pointfloat
X-axis value at the kink location.
- xnp.array
X-axis values.
- ynp.array
Y-axis values.
- bigfish.detection.get_elbow_values(images, voxel_size=None, spot_radius=None, log_kernel_size=None, minimum_distance=None)
Get values to plot the elbow curve used to automatically set the threshold to detect spots.
- Parameters:
- imagesList[np.ndarray] or np.ndarray
Image (or list of images) with shape (z, y, x) or (y, x). If several images are provided, the same threshold is applied.
- voxel_sizeint, float, Tuple(int, float), List(int, float) or None
Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- spot_radiusint, float, Tuple(int, float), List(int, float) or None
Radius of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same radius is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- log_kernel_sizeint, float, Tuple(int, float), List(int, float) or None
Size of the LoG kernel. It equals the standard deviation (in pixels) used for the gaussian kernel (one for each dimension). One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same standard deviation is applied to every dimensions. If None, we estimate it with the voxel size and spot radius.
- minimum_distanceint, float, Tuple(int, float), List(int, float) or None
Minimum distance (in pixels) between two spots we want to be able to detect separately. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same distance is applied to every dimensions. If None, we estimate it with the voxel size and spot radius.
- Returns:
- thresholdsnp.ndarray, np.float64
Candidate threshold values.
- count_spotsnp.ndarray, np.float64
Spots count (log scale).
- thresholdfloat or None
Threshold automatically set.
Compute signal-to-noise ratio
Compute a signal-to-noise ratio (SNR) for the image, based on the detected spots:
- bigfish.detection.compute_snr_spots(image, spots, voxel_size, spot_radius)
Compute signal-to-noise ratio (SNR) based on spot coordinates.
\[\mbox{SNR} = \frac{\mbox{max(spot signal)} - \mbox{mean(background)}}{\mbox{std(background)}}\]Background is a region twice larger surrounding the spot region. Only the y and x dimensions are taking into account to compute the SNR.
- Parameters:
- imagenp.ndarray
Image with shape (z, y, x) or (y, x).
- spotsnp.ndarray
Coordinate of the spots, with shape (nb_spots, 3) or (nb_spots, 2). One coordinate per dimension (zyx or yx coordinates).
- voxel_sizeint, float, Tuple(int, float), List(int, float) or None
Size of a voxel, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same value is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- spot_radiusint, float, Tuple(int, float), List(int, float) or None
Radius of the spot, in nanometer. One value per spatial dimension (zyx or yx dimensions). If it’s a scalar, the same radius is applied to every dimensions. Not used if ‘log_kernel_size’ and ‘minimum_distance’ are provided.
- Returns:
- snrfloat
Median signal-to-noise ratio computed for every spots.