CircularAperture#

class photutils.aperture.CircularAperture(positions, r)[source]#

Bases: PixelAperture

A circular aperture defined in pixel coordinates.

The aperture has a single fixed size/shape, but it can have multiple positions (see the positions input).

Parameters:

positionsarray_like

The pixel coordinates of the aperture center(s) in one of the following formats:

single (x, y) pair as a tuple, list, or ndarray
tuple, list, or ndarray of (x, y) pairs

rfloat

The radius of the circle in pixels.

Raises:

ValueErrorValueError: If the input radius, r, is negative.

Examples

>>> from photutils.aperture import CircularAperture
>>> aper = CircularAperture([10.0, 20.0], 3.0)
>>> aper = CircularAperture((10.0, 20.0), 3.0)

>>> pos1 = (10.0, 20.0)  # (x, y)
>>> pos2 = (30.0, 40.0)
>>> pos3 = (50.0, 60.0)
>>> aper = CircularAperture([pos1, pos2, pos3], 3.0)
>>> aper = CircularAperture((pos1, pos2, pos3), 3.0)

Attributes Summary

`area`	The exact geometric area of the aperture shape.
`bbox`	The minimal bounding box for the aperture.
`isscalar`	Whether the instance is scalar (i.e., a single position).
`positions`	The center pixel position(s).
`r`	The radius in pixels.
`shape`	The shape of the instance.

Methods Summary

`area_overlap`(data, *[, mask, method, subpixels])	Return the area of overlap between the data and the aperture.
`copy`()	Make a deep copy of this object.
`do_photometry`(data[, error, mask, method, ...])	Perform aperture photometry on the input data.
`plot`([ax, origin])	Plot the aperture on a matplotlib `Axes` instance.
`to_mask`([method, subpixels])	Return a mask for the aperture.
`to_polygon`(*[, n_vertices])	Return a `PolygonAperture` that approximates this circular aperture.
`to_sky`(wcs)	Convert the aperture to a `SkyCircularAperture` object defined in celestial coordinates.

Attributes Documentation

area#: The exact geometric area of the aperture shape.

bbox#

The minimal bounding box for the aperture.

If the aperture is scalar then a single BoundingBox is returned, otherwise a list of BoundingBox is returned.

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

positions#: The center pixel position(s).

r#: The radius in pixels.

shape#: The shape of the instance.

Methods Documentation

area_overlap(data, *, mask=None, method='exact', subpixels=5)#

Return the area of overlap between the data and the aperture.

This method takes into account the aperture mask method, masked data pixels (mask keyword), and partial/no overlap of the aperture with the data. In other words, it returns the area that used to compute the aperture sum (assuming identical inputs).

Use the area method to calculate the exact analytical area of the aperture shape.

Parameters:

dataarray_like or Quantity

A 2D array.

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 the area overlap.

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.

Returns:

areasfloat or array_like: The area (in pixels**2) of overlap between the data and the aperture.

See also

area

copy()#

Make a deep copy of this object.

Returns:

resultAperture: A deep copy of the Aperture object.

do_photometry(data, error=None, mask=None, method='exact', subpixels=5, *, segmentation_image=None, labels=None, mask_method='none')#

Perform aperture photometry on the input data.

Parameters:

dataarray_like or Quantity instance

The 2D array on which to perform photometry. data should be background subtracted.

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.

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.

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'.

labelsint, 1D array_like, or None, optional

The source label(s) in segmentation_image associated with the aperture position(s). If input, labels must have the same length as the number of aperture positions. If None (default), the label for each aperture is determined by sampling segmentation_image at the aperture center (rounded to the nearest pixel). An aperture whose center falls on a background pixel (label 0) has its masking behavior disabled.

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.

Returns:

aperture_sumsndarray or Quantity: The sum within each aperture. The values are always float64, regardless of the input data dtype.
aperture_sum_errsndarray or Quantity: The errors on the sum within each aperture. The values are always float64, regardless of the input error dtype.

plot(ax=None, origin=(0, 0), **kwargs)#

Plot the aperture on a matplotlib Axes instance.

Parameters:

axmatplotlib.axes.Axes or None, optional: The matplotlib axes on which to plot. If None, then the current Axes instance is used.
originarray_like, optional: The (x, y) position of the origin of the displayed image.
**kwargsdict, optional: Any keyword arguments accepted by matplotlib.patches.Patch.

Returns:

patchlist of Patch: A list of matplotlib patches for the plotted aperture. The patches can be used, for example, when adding a plot legend.

to_mask(method='exact', subpixels=5)#

Return a mask for the aperture.

Parameters:

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.

Returns:

maskApertureMask or list of ApertureMask: A mask for the aperture. If the aperture is scalar then a single ApertureMask is returned, otherwise a list of ApertureMask is returned.

to_polygon(*, n_vertices=100)[source]#

Return a PolygonAperture that approximates this circular aperture.

Parameters:

n_verticesint, optional: The number of polygon vertices used to approximate the circle. Must be at least 3. Default is 100.

Returns:

aperturePolygonAperture: A polygon aperture that approximates the circle.

to_sky(wcs)[source]#

Convert the aperture to a SkyCircularAperture object defined in celestial coordinates.

Parameters:

wcsWCS object: A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS, gwcs.wcs.WCS).

Returns:

apertureSkyCircularAperture object: A SkyCircularAperture object.

Notes

The aperture shape parameters are converted using the local WCS pixel scale evaluated at the first aperture position. Because aperture objects require scalar shape parameters, only a single reference position is used for the conversion. For apertures with multiple positions used with a WCS that has spatially-varying distortions, this may produce inaccurate results for positions far from the first position.