RectangularAnnulus#

class photutils.aperture.RectangularAnnulus(positions, w_in, w_out, h_out, h_in=None, theta=0.0)[source]#

Bases: PixelAperture

A rectangular annulus 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

w_infloat

The inner full width of the rectangular annulus in pixels. For theta=0 the width side is along the x axis.

w_outfloat

The outer full width of the rectangular annulus in pixels. For theta=0 the width side is along the x axis.

h_outfloat

The outer full height of the rectangular annulus in pixels.

h_inNone or float

The inner full height of the rectangular annulus in pixels. If None, then the inner full height is calculated as:

\[h_{in} = h_{out} \left(\frac{w_{in}}{w_{out}}\right)\]

For theta=0 the height side is along the y axis.

thetafloat or Quantity, optional

The rotation angle as an angular quantity (Quantity or Angle) or value in radians (as a float) from the positive x axis. The rotation angle increases counterclockwise.

Raises:

ValueErrorValueError: If inner width (w_in) is greater than outer width (w_out).
ValueErrorValueError: If either the inner width (w_in) or the outer height (h_out) is negative.

Examples

>>> from astropy.coordinates import Angle
>>> from photutils.aperture import RectangularAnnulus

>>> theta = Angle(80, 'deg')
>>> aper = RectangularAnnulus([10.0, 20.0], 3.0, 8.0, 5.0)
>>> aper = RectangularAnnulus((10.0, 20.0), 3.0, 8.0, 5.0, theta=theta)

>>> pos1 = (10.0, 20.0)  # (x, y)
>>> pos2 = (30.0, 40.0)
>>> pos3 = (50.0, 60.0)
>>> aper = RectangularAnnulus([pos1, pos2, pos3], 3.0, 8.0, 5.0)
>>> aper = RectangularAnnulus((pos1, pos2, pos3), 3.0, 8.0, 5.0,
...                           theta=theta)

Attributes Summary

`area`	The exact geometric area of the aperture shape.
`bbox`	The minimal bounding box for the aperture.
`h_in`	The inner full height in pixels.
`h_out`	The outer full height in pixels.
`isscalar`	Whether the instance is scalar (i.e., a single position).
`positions`	The center pixel position(s).
`shape`	The shape of the instance.
`theta`	The counterclockwise rotation angle as an angular Quantity or a value in radians from the positive x axis.
`w_in`	The inner full width in pixels.
`w_out`	The outer full width in pixels.

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_sky`(wcs)	Convert the aperture to a `SkyRectangularAnnulus` 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.

h_in#: The inner full height in pixels.

h_out#: The outer full height in pixels.

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

positions#: The center pixel position(s).

shape#: The shape of the instance.

theta#: The counterclockwise rotation angle as an angular Quantity or a value in radians from the positive x axis.

w_in#: The inner full width in pixels.

w_out#: The outer full width in pixels.

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 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. If subpixels=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 into subpixels**2 subpixels. This keyword is ignored unless method='subpixel'.

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)#

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 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. If subpixels=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 into subpixels**2 subpixels. This keyword is ignored unless method='subpixel'.

Returns:

aperture_sumsndarray or Quantity: The sum within each aperture.
aperture_sum_errsndarray or Quantity: The errors on the sum within each aperture.

Notes

RectangularAperture and RectangularAnnulus 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 recommended to set method='subpixel' with a larger subpixels size.

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 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. If subpixels=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 into subpixels**2 subpixels. This keyword is ignored unless method='subpixel'.

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_sky(wcs)[source]#

Convert the aperture to a SkyRectangularAnnulus 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:

apertureSkyRectangularAnnulus object: A SkyRectangularAnnulus object.

Notes

The aperture shape parameters are converted using the local WCS properties (pixel scale, rotation angle) 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.