aperture_photometry#
- photutils.aperture.aperture_photometry(data, apertures, error=None, mask=None, method='exact', subpixels=5, wcs=None)[source]#
Perform aperture photometry on the input data by summing the flux within the given aperture(s).
Note that this function returns the sum of the (weighted) input
data
values within the aperture. It does not convert data in surface brightness units to flux or counts. Conversion from surface-brightness units should be performed before using this function.- Parameters:
- dataarray_like,
Quantity
,NDData
The 2D array on which to perform photometry.
data
should be background-subtracted. Ifdata
is aQuantity
array, thenerror
(if input) must also be aQuantity
array with the same units. See the Notes section below for more information aboutNDData
input.- apertures
Aperture
, supportedregions.Region
, list ofAperture
orregions.Region
The aperture(s) to use for the photometry. If
apertures
is a list ofAperture
orregions.Region
, then then they all must have the same position(s). Ifapertures
contains aSkyAperture
orSkyRegion
object, then a WCS must be input using thewcs
keyword. Region objects are converted to aperture objects.- errorarray_like or
Quantity
, optional The pixel-wise Gaussian 1-sigma errors of the input
data
.error
is assumed to include all sources of error, including the Poisson error of the sources (seecalc_total_error
) .error
must have the same shape as the inputdata
. If aQuantity
array, thendata
must also be aQuantity
array with the same units.- maskarray_like (bool), optional
A boolean mask with the same shape as
data
where aTrue
value indicates the corresponding element ofdata
is masked. Masked data are excluded from all calculations.- method{‘exact’, ‘center’, ‘subpixel’}, optional
The method used to determine the overlap of the aperture on the pixel grid. Not all options are available for all aperture types. Note that the more precise methods are generally slower. The following methods are available:
'exact'
(default):The exact fractional overlap of the aperture and each pixel is calculated. The aperture weights will contain values between 0 and 1.
'center'
:A pixel is considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. The aperture weights will contain values only of 0 (out) and 1 (in).
'subpixel'
:A pixel is divided into subpixels (see the
subpixels
keyword), each of which are considered to be entirely in or out of the aperture depending on whether its center is in or out of the aperture. Ifsubpixels=1
, this method is equivalent to'center'
. The aperture weights will contain values between 0 and 1.
- subpixelsint, optional
For the
'subpixel'
method, resample pixels by this factor in each dimension. That is, each pixel is divided intosubpixels**2
subpixels. This keyword is ignored unlessmethod='subpixel'
.- wcsWCS object, optional
A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g.,
astropy.wcs.WCS
,gwcs.wcs.WCS
). Used only if the inputapertures
contains aSkyAperture
orSkyRegion
object.
- dataarray_like,
- Returns:
- table
QTable
A table of the photometry with the following columns:
'id'
: The source ID.'xcenter'
,'ycenter'
: Thex
andy
pixel coordinates of the input aperture center(s).'sky_center'
: The sky coordinates of the input aperture center(s). Returned only if the inputapertures
is aSkyAperture
object.'aperture_sum'
: The sum of the values within the aperture.'aperture_sum_err'
: The corresponding uncertainty in the'aperture_sum'
values. Returned only if the inputerror
is notNone
.
The table metadata includes the Astropy and Photutils version numbers and the
aperture_photometry
calling arguments.
- table
Notes
Region
objects are converted toAperture
objects using theregion_to_aperture()
function.RectangularAperture
andRectangularAnnulus
photometry with the “exact” method uses a subpixel approximation by subdividing each data pixel by a factor of 1024 (subpixels = 32
). For rectangular aperture widths and heights in the range from 2 to 100 pixels, this subpixel approximation gives results typically within 0.001 percent or better of the exact value. The differences can be larger for smaller apertures (e.g., aperture sizes of one pixel or smaller). For such small sizes, it is recommend to setmethod='subpixel'
with a largersubpixels
size.If the input
data
is aNDData
instance, then theerror
,mask
, andwcs
keyword inputs are ignored. Instead, these values should be defined as attributes in theNDData
object. In the case oferror
, it must be defined in theuncertainty
attribute with aStdDevUncertainty
instance.