PixelAperture

class photutils.aperture.PixelAperture[source]

Bases: photutils.Aperture

Abstract base class for apertures defined in pixel coordinates.

Attributes Summary

bounding_boxes A list of minimal bounding boxes (BoundingBox), one for each position, for the aperture.

Methods Summary

area() Return the exact area of the aperture shape.
do_photometry(data[, error, mask, method, …]) Perform aperture photometry on the input data.
mask_area([method, subpixels]) Return the area of the aperture(s) mask.
plot([origin, indices, ax, fill]) Plot the aperture(s) on a matplotlib Axes instance.
to_mask([method, subpixels]) Return a list of ApertureMask objects, one for each aperture position.
to_sky(wcs[, mode]) Convert the aperture to a SkyAperture object defined in celestial coordinates.

Attributes Documentation

bounding_boxes

A list of minimal bounding boxes (BoundingBox), one for each position, for the aperture.

Methods Documentation

area()[source]

Return the exact area of the aperture shape.

Returns:
area : float

The aperture area.

do_photometry(data, error=None, mask=None, method='exact', subpixels=5, unit=None)[source]

Perform aperture photometry on the input data.

Parameters:
data : array_like or Quantity instance

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

error : array_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.

mask : array_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 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 the exact fractional overlap of the aperture and each pixel is calculated. The returned mask 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 returned mask 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. If subpixels=1, this method is equivalent to 'center'. The returned mask will contain values between 0 and 1.
subpixels : int, optional

For the 'subpixel' method, resample pixels by this factor in each dimension. That is, each pixel is divided into subpixels ** 2 subpixels.

unit : UnitBase object or str, optional

An object that represents the unit associated with the input data and error arrays. Must be a UnitBase object or a string parseable by the units package. If data or error already have a different unit, the input unit will not be used and a warning will be raised.

Returns:
aperture_sums : ndarray or Quantity

The sums within each aperture.

aperture_sum_errs : ndarray or Quantity

The errors on the sums within each aperture.

mask_area(method='exact', subpixels=5)[source]

Return the area of the aperture(s) mask.

For method other than 'exact', this area will be less than the exact analytical area (e.g. the area method). Note that for these methods, the values can also differ because of fractional pixel positions.

Parameters:
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 the exact fractional overlap of the aperture and each pixel is calculated. The returned mask 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 returned mask 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. If subpixels=1, this method is equivalent to 'center'. The returned mask will contain values between 0 and 1.
subpixels : int, optional

For the 'subpixel' method, resample pixels by this factor in each dimension. That is, each pixel is divided into subpixels ** 2 subpixels.

Returns:
area : float

A list of the mask area of the aperture(s).

plot(origin=(0, 0), indices=None, ax=None, fill=False, **kwargs)[source]

Plot the aperture(s) on a matplotlib Axes instance.

Parameters:
origin : array_like, optional

The (x, y) position of the origin of the displayed image.

indices : int or array of int, optional

The indices of the aperture(s) to plot.

ax : matplotlib.axes.Axes instance, optional

If None, then the current Axes instance is used.

fill : bool, optional

Set whether to fill the aperture patch. The default is False.

kwargs

Any keyword arguments accepted by matplotlib.patches.Patch.

to_mask(method='exact', subpixels=5)[source]

Return a list of ApertureMask objects, one for each aperture position.

Parameters:
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 the exact fractional overlap of the aperture and each pixel is calculated. The returned mask 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 returned mask 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. If subpixels=1, this method is equivalent to 'center'. The returned mask will contain values between 0 and 1.
subpixels : int, optional

For the 'subpixel' method, resample pixels by this factor in each dimension. That is, each pixel is divided into subpixels ** 2 subpixels.

Returns:
mask : list of ApertureMask

A list of aperture mask objects.

to_sky(wcs, mode='all')[source]

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

Parameters:
wcs : WCS object

The world coordinate system (WCS) transformation to use.

mode : {‘all’, ‘wcs’}, optional

Whether to do the transformation including distortions ('all'; default) or including only the core WCS transformation ('wcs').

Returns:
aperture : SkyAperture object

A SkyAperture object.