find_peaks

photutils.detection.find_peaks(data, threshold, *, box_size=3, footprint=None, mask=None, border_width=None, n_peaks=inf, min_separation=None, centroid_func=None, error=None, wcs=None)

Find local peaks in an image that are above a specified threshold value.

Peaks are the maxima above the threshold within a local region. The local regions are defined by either the box_size or footprint parameters. box_size defines the local region around each pixel as a square box. footprint is a boolean array where True values specify the region shape.

If multiple pixels within a local region have identical intensities, then the coordinates of all such pixels are returned. Otherwise, there will be only one peak pixel per local region. Thus, the defined region effectively imposes a minimum separation between peaks unless there are identical peaks within the region.

When min_separation is set, a fast algorithm is used that produces results equivalent to using a circular footprint of the given radius for maximum_filter, but is typically ~10-400x faster (depending on the radius). When set, box_size and footprint are not used for peak detection.

If centroid_func is input, then it will be used to calculate a centroid within the defined local region centered on each detected peak pixel. In this case, the centroid will also be returned in the output table.

Parameters:

dataarray_like

The 2D array of the image.

thresholdfloat, scalar Quantity or array_like

The data value or pixel-wise data values to be used for the detection threshold. A peak is detected only if it is strictly greater than the threshold. If data is a Quantity array, then threshold must have the same units as data. A 2D threshold must have the same shape as data. See detect_threshold for one way to create a threshold image.

box_sizescalar or tuple, optional

The size of the local region to search for peaks at every point in data. If box_size is a scalar, then the region shape will be (box_size, box_size). Either box_size or footprint must be defined. If they are both defined, then footprint overrides box_size.

footprintndarray of bools, optional

A boolean array where True values describe the local footprint region within which to search for peaks at every point in data. box_size=(n, m) is equivalent to footprint=np.ones((n, m)). Either box_size or footprint must be defined. If they are both defined, then footprint overrides box_size.

maskarray_like, bool, optional

A boolean mask with the same shape as data, where a True value indicates the corresponding element of data is masked.

border_widthint, array_like of int, or None, optional

The width in pixels to exclude around the border of the data. If border_width is a scalar then border_width will be applied to all sides. If border_width has two elements, they must be in (ny, nx) order. If None, then no border is excluded. The border width values must be non-negative integers.

n_peaksint, optional

The maximum number of peaks to return. When the number of detected peaks exceeds n_peaks, the peaks with the highest peak intensities will be returned.

min_separationfloat or None, optional

The minimum allowed separation (in pixels) between detected peaks, enforced using a circular region of this radius. Each detected peak must be the maximum value (or tied for the maximum) within a circle of this radius. This is equivalent to using a circular footprint of the given radius but uses a fast algorithm that is typically ~10-400x faster (depending on the radius). When set, box_size and footprint are not used for peak detection. If None (default), the peak detection uses box_size or footprint as specified.

centroid_funccallable, optional

A callable object (e.g., function or class) that is used to calculate the centroid of a 2D array. The centroid_func must accept a 2D ndarray, have a mask keyword, and optionally an error keyword. The callable object must return a tuple of two 1D ndarray objects, representing the x and y centroids, respectively.

errorarray_like, optional

The 2D array of the 1-sigma errors of the input data. error is used only if centroid_func is input (the error array is passed directly to the centroid_func). If data is a Quantity array, then error must have the same units as data.

wcsNone or WCS object, optional

A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS, gwcs.wcs.WCS). If None, then the sky coordinates will not be returned in the output Table.

Returns:

outputQTable or None

A table containing the x and y pixel location of the peaks and their values. If centroid_func is input, then the table will also contain the centroid position. If no peaks are found then None is returned.

Notes

By default, the returned pixel coordinates are the integer indices of the maximum pixel value within the input box_size or footprint (i.e., only the peak pixel is identified).

When min_separation is given, peaks are detected using a fast algorithm that is mathematically equivalent to a circular footprint of the given radius for maximum_filter. The algorithm uses two fast O(N) separable box filters (inscribed and circumscribed squares of the circle) to classify most candidates, then verifies only the remaining few against the exact circular region.

A centroiding function can be input via the centroid_func keyword to compute centroid coordinates with subpixel precision within the input box_size or footprint. Note that when min_separation is used, the centroid region size is determined by box_size (default 3), not by min_separation.

The peak detection uses mode='constant' with cval=0.0 for maximum_filter, which means pixels outside the image boundary are treated as zero. For images with all-negative values, this may suppress legitimate peaks near the borders.

Any NaN values in the input data are replaced with the minimum finite value before peak detection, and the corresponding pixels are automatically excluded from the results.

The output column names (x_peak, y_peak, peak_value) differ from the star finder classes (e.g., DAOStarFinder), which use x_centroid, y_centroid, and flux.