AperturePhotometry#

class photutils.aperture.AperturePhotometry(data, apertures, *, error=None, mask=None, wcs=None, method='exact', subpixels=5, segmentation_image=None, labels=None, mask_method='none')[source]#

Bases: object

Class to perform aperture photometry on 2D data.

This class sums the (weighted) input data values within the given aperture(s) and provides the aperture fluxes, uncertainties, unmasked overlap areas, and bitwise quality flags as lazily-computed attributes. Use to_table to obtain the results as an QTable.

Note that this class 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 class.

Parameters:

dataarray_like, Quantity, NDData

The 2D array on which to perform photometry. data should be background-subtracted. If data is a Quantity array, then error (if input) must also be a Quantity array with the same units. Non-finite data values (NaN and inf) are automatically masked. See the Notes section below for more information about NDData input.

aperturesAperture, supported regions.Region, list of Aperture or regions.Region

The aperture(s) to use for the photometry. If apertures is a list of Aperture or regions.Region, then they all must have the same position(s). If apertures contains a SkyAperture or SkyRegion object, then a WCS must be input using the wcs 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 (see calc_total_error). error must have the same shape as the input data. If a Quantity array, then data must also be a Quantity array with the same units.

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. Masked data are excluded from all calculations. Non-finite values (NaN and inf) in the input data are automatically masked.

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). If provided, the sky_center attribute and the 'sky_center' column of to_table will contain the sky coordinates of the input aperture center(s). This keyword is required if the input apertures contains a SkyAperture or SkyRegion.

method{‘exact’, ‘center’, ‘subpixel’}, optional

The method used to determine the pixel weights (the fraction of the pixel area covered by the aperture):

'exact' (default): Calculates the exact geometric overlap area. Weights are continuous in the range [0, 1].
'center': Binary weighting based on the pixel center. Weights are either 0 or 1. A pixel is included only if its center lies strictly inside the aperture; pixel centers lying exactly on the aperture boundary are excluded (weight 0).
'subpixel': Approximates the overlap by averaging binary samples on a subgrid. The number of samples is set by the subpixels parameter. Weights are discrete in the range [0, 1]. A subpixel is included only if its center lies strictly inside the aperture; subpixel centers lying exactly on the aperture boundary are excluded (weight 0).

subpixelsint, optional

The subsampling factor per axis used when method='subpixel'. Each pixel is divided into a grid of subpixels**2 subpixels to approximate the overlap. This parameter is ignored for other methods.

segmentation_imageSegmentationImage, 2D array_like, or None, optional

A 2D segmentation image with the same shape as data, where background pixels have a value of 0 and sources are labeled with positive integers. If input, neighboring sources can be masked or corrected within each aperture according to the mask_method keyword. This keyword is required if mask_method is not 'none'. When segmentation_image is input, the labels keyword must also be provided to ensure the correct target source is used for each aperture. If segmentation_image is None, then the mask_method keyword is ignored and no neighboring source masking or correction is performed.

labelsint, 1D array_like, or None, optional

The source label(s) in segmentation_image associated with the aperture position(s). labels is required if segmentation_image is input and mask_method is not 'none'. labels must have the same length as the number of aperture positions.

mask_method{‘none’, ‘mask’, ‘source_only’, ‘correct’}, optional

The method used to handle neighboring sources within each aperture using the segmentation_image:

'none' (default): The segmentation_image is ignored and all pixels within the aperture are included.
'mask': Pixels belonging to neighboring sources (i.e., labeled but not the target source) are excluded.
'source_only': Only pixels belonging to the target source are included; both neighboring sources and background pixels are excluded.
'correct': Pixels belonging to neighboring sources are replaced by the values of the pixels mirrored across the aperture center. If a mirror pixel is unavailable, the pixel is excluded.

See also

photutils.aperture.ApertureStats: Per-source statistics (e.g., centroid, min, max, median, standard deviation, and morphological properties) of the pixels within an aperture.

Notes

Region objects are converted to Aperture objects using the region_to_aperture() function.

If the input data is a NDData instance, then the error, mask, and wcs keyword inputs are ignored. Instead, these values should be defined as attributes in the NDData object. In the case of error, it must be defined in the uncertainty attribute with a StdDevUncertainty instance.

The measured flux, flux_err, area, and flags attributes (as well as id, x_center, y_center, and sky_center) are scalars if a single scalar aperture position is input (e.g., CircularAperture((10, 20), r=5)). They are 1D arrays with one element per position if multiple positions are input (e.g., CircularAperture([(10, 20)], r=5) or CircularAperture([(10, 20), (30, 40)], r=5)). If a list of apertures is input, the flux, flux_err, area, and flags attributes gain a trailing aperture axis, giving shape (n_apertures,) for a single scalar position and (n_positions, n_apertures) otherwise.

Non-finite data values (NaN and inf) are automatically masked. Such pixels are excluded from the flux, flux_err, and area calculations and are indicated by the non_finite_data quality flag (see decode_aperture_flags).

This class should be treated as immutable after initialization (aside from the internal compute-once lazyproperty cache), so a single instance can be safely shared across threads. Do not reassign its attributes after construction.

Examples

>>> import numpy as np
>>> from photutils.datasets import make_4gaussians_image
>>> from photutils.aperture import AperturePhotometry, CircularAperture
>>> data = make_4gaussians_image()
>>> error = 0.1 * np.ones(data.shape)  # simple background-only error
>>> aper = CircularAperture([(25, 40), (90, 60), (150, 25)], r=8)
>>> phot = AperturePhotometry(data, aper, error=error)
>>> print(phot.flux)
[ 5853.59627292 28440.27461471  9286.70920641]
>>> print(phot.flux_err)
[1.41796308 1.41796308 1.41796308]
>>> phot.to_table(columns=['id', 'flux', 'flux_err'])
<QTable length=3>
  id         flux             flux_err
int64      float64            float64
----- ------------------ -----------------
    1  5853.596272924398 1.417963080724414
    2 28440.274614708058 1.417963080724414
    3  9286.709206410273 1.417963080724414

Attributes Summary

`area`	The total unmasked overlap area of the aperture(s) (in `pix**2`).
`flags`	The bitwise quality flags for the aperture(s).
`flux`	The sum of the (weighted) values within the aperture(s).
`flux_err`	The uncertainty in the `flux` values.
`id`	The aperture identification number(s).
`isscalar`	Whether the instance is scalar (i.e., a single aperture position).
`n_positions`	The number of aperture positions.
`sky_center`	The sky coordinates of the aperture center(s), or `None` if no `wcs` was input.
`x_center`	The `x` pixel coordinate(s) of the aperture center(s).
`y_center`	The `y` pixel coordinate(s) of the aperture center(s).

Methods Summary

`decode_flags`(*[, return_bit_values])	Decode the aperture quality flags into individual components.
`to_table`(*[, columns])	Create a `QTable` of the aperture photometry results.

Attributes Documentation

area#

The total unmasked overlap area of the aperture(s) (in pix**2).

This takes into account the aperture mask method, masked data pixels (mask keyword), segmentation masking, and partial/no overlap of the aperture with the data. The value is NaN where an aperture does not overlap the data.

flags#

The bitwise quality flags for the aperture(s).

See decode_aperture_flags for decoding flag values.

flux#

The sum of the (weighted) values within the aperture(s).

The values are always float64, regardless of the input data dtype (a Quantity if data has units).

flux_err#

The uncertainty in the flux values.

The values are always float64, regardless of the input error dtype (a Quantity if data has units). If the input error is None, this is filled with NaN values.

id#: The aperture identification number(s).

isscalar#: Whether the instance is scalar (i.e., a single aperture position).

n_positions#: The number of aperture positions.

sky_center#: The sky coordinates of the aperture center(s), or None if no wcs was input.

x_center#: The x pixel coordinate(s) of the aperture center(s).

y_center#: The y pixel coordinate(s) of the aperture center(s).

Methods Documentation

decode_flags(*, return_bit_values=False)[source]#

Decode the aperture quality flags into individual components.

This is a convenience method that calls decode_aperture_flags with the flags attribute.

Parameters:

return_bit_valuesbool, optional: If True, return the decoded bit flags (integers) instead of the flag names (strings).

Returns:

decodedlist of list of str or list of list of int: A list of the active flag names (or bit values) for each aperture. If a list of apertures was input (2D flags), the result is a nested list with the same (n_positions, n_apertures) shape as flags, so decoded[i][j] gives the active flags for position i and aperture j.