IRAFStarFinder#

class photutils.detection.IRAFStarFinder(threshold, fwhm, sigma_radius=1.5, minsep_fwhm=<deprecated>, sharplo=<deprecated>, sharphi=<deprecated>, roundlo=<deprecated>, roundhi=<deprecated>, exclude_border=False, n_brightest=None, peak_max=None, xycoords=None, min_separation=None, *, sharpness_range=(0.5, 2.0), roundness_range=(0.0, 0.2), min_n_pixels=5)[source]#

Bases: StarFinderBase

Detect stars in an image using IRAF’s “starfind” algorithm.

IRAFStarFinder searches images for local density maxima that have a peak amplitude greater than threshold above the local background and have a PSF full width at half maximum similar to the input fwhm. The objects’ centroid, roundness (ellipticity), and sharpness are calculated using image moments.

The image is convolved with a circular Gaussian kernel that has a positive core and negative wings, and that sums to zero. This convolution is equivalent to a linear least-squares fit, at every pixel, of the amplitude of the Gaussian centered on that pixel plus a constant local background. Each pixel of the convolved image is therefore the height of the best-fitting Gaussian at that position, in the units of the input data. Because the local background is fitted, the convolved image does not depend on the background level. The threshold is applied directly to this fitted height. The local background is fitted using only the pixels within the kernel footprint, so a larger sigma_radius gives a less noisy fitted height.

Parameters:
thresholdfloat or 2D ndarray

The absolute image value above which to select sources. If threshold is a 2D array, it must have the same shape as the input data. If the star finder is run on an image that is a Quantity array, then threshold must have the same units.

fwhmfloat

The full width at half maximum (FWHM) of the 2D circular Gaussian kernel in units of pixels.

sigma_radiusfloat, optional

The truncation radius of the Gaussian kernel in units of sigma (standard deviation) (\(\sigma = \mbox{FWHM} / (2 \sqrt{2 \log(2)})\)).

minsep_fwhmfloat, optional

The separation (in units of fwhm) for detected objects. The minimum separation is calculated as int((fwhm * minsep_fwhm) + 0.5) and is clipped to a minimum value of 2. This value is ignored if min_separation is input. Note that large values may result in long run times.

Deprecated since version 3.0: This keyword is deprecated and will be removed in version 4.0. Use min_separation instead.

sharplofloat, optional

The lower bound on sharpness for object detection.

Deprecated since version 3.0: This keyword is deprecated and will be removed in version 4.0. Use sharpness_range=(lower, upper) instead.

sharphifloat, optional

The upper bound on sharpness for object detection.

Deprecated since version 3.0: This keyword is deprecated and will be removed in version 4.0. Use sharpness_range=(lower, upper) instead.

roundlofloat, optional

The lower bound on roundness for object detection.

Deprecated since version 3.0: This keyword is deprecated and will be removed in version 4.0. Use roundness_range=(lower, upper) instead.

roundhifloat, optional

The upper bound on roundness for object detection.

Deprecated since version 3.0: This keyword is deprecated and will be removed in version 4.0. Use roundness_range=(lower, upper) instead.

exclude_borderbool, optional

Set to True to exclude sources found within half the size of the convolution kernel from the image borders. The default is False, which is the mode used by starfind.

n_brightestint, None, optional

The number of brightest objects to keep after sorting the source list by flux. If n_brightest is set to None, all objects will be selected.

peak_maxfloat, None, optional

The maximum allowed peak pixel value in an object. Objects with peak pixel values greater than peak_max will be rejected. The peak value is measured after the local sky is subtracted. This keyword may be used, for example, to exclude saturated sources. If the star finder is run on an image that is a Quantity array, then peak_max must have the same units. If peak_max is set to None, then no peak pixel value filtering will be performed.

xycoordsNone or Nx2 array_like, optional

The (x, y) pixel coordinates of the approximate centroid positions of identified sources. If xycoords are input, the algorithm will skip the source-finding step, and threshold, min_separation, exclude_border, and the mask input to find_stars are not used to select the sources. The positions are rounded to the nearest pixel and must be within the bounds of the input data.

min_separationNone or float, optional

The minimum separation (in pixels) for detected objects. If None (default) then the minimum separation is calculated as 2.5 * fwhm. If 0, a local peak is required only within the kernel footprint. Note that large values may result in long run times.

Changed in version 3.0: The default min_separation changed from max(2, int(fwhm * 2.5 + 0.5)) to 2.5 * fwhm. To recover the previous behavior, set min_separation=max(2, int(fwhm * 2.5 + 0.5)).

sharpness_rangetuple of 2 floats or None, optional

The (lower, upper) inclusive bounds on sharpness for object detection. Objects with sharpness outside this range will be rejected. If None, no sharpness filtering is performed. The default is (0.5, 2.0).

roundness_rangetuple of 2 floats or None, optional

The (lower, upper) inclusive bounds on roundness for object detection. Objects with roundness outside this range will be rejected. If None, no roundness filtering is performed. The default is (0.0, 0.2).

min_n_pixelsint, optional

The minimum number of positive sky-subtracted pixels within the kernel footprint that a source must have. Sources with fewer such pixels are rejected. The default is 5, which is the default and the minimum value of the npixmin parameter in IRAF’s starfind.

See also

DAOStarFinder

Notes

If the star finder is run on an image that is a Quantity array, then threshold and peak_max must have the same units as the image.

For the convolution step, this routine sets pixels beyond the image borders to 0.0. The equivalent parameters in IRAF’s starfind are boundary='constant' and constant=0.0.

IRAF’s starfind uses hwhmpsf, fradius, and sepmin as input parameters. The equivalent input values for IRAFStarFinder are:

  • fwhm = hwhmpsf * 2

  • sigma_radius = fradius * sqrt(2.0 * log(2.0))

  • min_separation = max(2, int((fwhm * sepmin) + 0.5))

  • min_n_pixels = npixmin

As in IRAF’s starfind, sources whose centroid is outside of the image are rejected.

The main differences between DAOStarFinder and IRAFStarFinder are:

  • IRAFStarFinder always uses a 2D circular Gaussian kernel, while DAOStarFinder can use an elliptical Gaussian kernel.

  • IRAFStarFinder internally calculates a local “sky” background level for each source as the mean of the pixels in the kernel array that lie outside the kernel footprint, and subtracts it before computing the source properties. If the kernel footprint covers the entire kernel array, the sky is the central data value minus the central value of the convolved data.

  • IRAFStarFinder calculates the objects’ centroid, roundness, and sharpness using image moments.

This routine differs from IRAF’s starfind for pixels of the convolved image that have identical values, which are uncommon for floating-point data (a saturated star usually has none). For a positive min_separation, such pixels that are within min_separation of each other give only one source (see find_peaks). IRAF’s starfind keeps every pixel that is tied for the maximum within sepmin, except for those that follow a detected pixel within sepmin along the same image line. With min_separation=0, this routine keeps every pixel that is tied for the maximum within the kernel footprint.

Methods Summary

__call__(data[, mask])

Find stars in an astronomical image.

find_stars(data[, mask])

Find stars in an astronomical image.

Methods Documentation

__call__(data, mask=None)#

Find stars in an astronomical image.

Parameters:
data2D ndarray or Quantity

The 2D image array.

mask2D bool array, optional

A boolean mask with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked pixels are ignored when searching for stars.

Returns:
tableQTable or None

A table of found stars. If no stars are found then None is returned.

find_stars(data, mask=None)[source]#

Find stars in an astronomical image.

Parameters:
data2D ndarray or Quantity

The 2D image array. The image should be background-subtracted.

mask2D bool array, optional

A boolean mask with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked pixels are ignored when searching for stars.

Returns:
tableQTable or None

A table of found stars. None is returned if no stars are found. The table contains the following parameters:

  • id: unique object identification number.

  • x_centroid, y_centroid: object centroid.

  • fwhm: object FWHM.

  • sharpness: object sharpness.

  • roundness: object roundness.

  • orientation: the angle between the x-axis and the major axis of the source, measured counterclockwise, in the range (-90, 90] degrees.

  • n_pixels: the total number of (positive) unmasked pixels.

  • peak: the peak sky-subtracted pixel value of the object within the kernel footprint.

  • flux: the object instrumental flux calculated as the sum of the positive sky-subtracted data values within the kernel footprint.

  • mag: the object instrumental magnitude calculated as -2.5 * log10(flux).