centroid_quadratic#

photutils.centroids.centroid_quadratic(data, mask=None, fit_boxsize=5, xpeak=None, ypeak=None, search_boxsize=None)[source]#

Calculate the centroid of a 2D array by fitting a 2D quadratic polynomial.

Non-finite values (e.g., NaN or inf) in the data array are automatically masked. The final mask is a logical OR combination of the input mask, the automatically generated mask for non-finite values, and the mask of the input data if it is a MaskedArray. The centroid is calculated using only the unmasked data values.

A second degree 2D polynomial is fit within a small region of the data defined by fit_boxsize to calculate the centroid position. The initial center of the fitting box can be specified using the xpeak and ypeak keywords. If both xpeak and ypeak are None, then the box will be centered at the position of the maximum value in the input data.

If xpeak and ypeak are specified, the search_boxsize optional keyword can be used to further refine the initial center of the fitting box by searching for the position of the maximum pixel within a box of size search_boxsize.

Vakili & Hogg (2016) demonstrate that 2D quadratic centroiding comes very close to saturating the Cramér-Rao lower bound in a wide range of conditions.

Parameters:
data2D array_like

The 2D image data. data can be a MaskedArray. The image should be a background-subtracted cutout image containing a single source.

mask2D bool ndarray, optional

A boolean mask, with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked data are excluded from calculations. If data is a MaskedArray, its mask will be combined (using bitwise OR) with the input mask.

fit_boxsizeint or tuple of int, optional

The size (in pixels) of the box used to define the fitting region. If fit_boxsize has two elements, they must be in (ny, nx) order. If fit_boxsize is a scalar then a square box of size fit_boxsize will be used. fit_boxsize must have odd values for both axes.

xpeak, ypeakfloat or None, optional

The initial guess of the position of the centroid. If either xpeak or ypeak is None then the position of the maximum value in the input data will be used as the initial guess.

Deprecated since version 3.0: The xpeak and ypeak keywords are deprecated and will be removed in a future version. Use centroid_sources to centroid sources at specific positions.

search_boxsizeint or tuple of int, optional

The size (in pixels) of the box used to search for the maximum pixel value if xpeak and ypeak are both specified. If search_boxsize has two elements, they must be in (ny, nx) order. If search_boxsize is a scalar then a square box of size search_boxsize will be used. search_boxsize must have odd values for both axes. This parameter is ignored if either xpeak or ypeak is None. In that case, the entire array is searched for the maximum value.

Deprecated since version 3.0: The search_boxsize keyword is deprecated and will be removed in a future version. Use centroid_sources to centroid sources at specific positions.

Returns:
centroidndarray

The x, y coordinates of the centroid.

Notes

Use fit_boxsize = (3, 3) to match the work of Vakili & Hogg (2016) for their 2D second-order polynomial centroiding method.

Because this centroid is based on fitting data, it can fail for many reasons, returning (np.nan, np.nan):

  • quadratic fit failed

  • quadratic fit does not have a maximum

  • quadratic fit maximum falls outside image

  • not enough unmasked data points (6 are required)

Also note that a fit is not performed if the maximum data value is at the edge of the data. In this case, the position of the maximum pixel will be returned.

References

[1]

Vakili and Hogg 2016, “Do fast stellar centroiding methods saturate the Cramér-Rao lower bound?”, arXiv:1610.05873

Examples

>>> import numpy as np
>>> from photutils.datasets import make_4gaussians_image
>>> from photutils.centroids import centroid_quadratic
>>> data = make_4gaussians_image()
>>> data -= np.median(data[0:30, 0:125])
>>> data = data[40:80, 70:110]
>>> x1, y1 = centroid_quadratic(data)
>>> print(np.array((x1, y1)))
[19.94009505 20.06884997]

(Source code, png, hires.png, pdf, svg)

../_images/photutils-centroids-centroid_quadratic-1.png
On this page