RectangularAnnulus¶
- class photutils.aperture.RectangularAnnulus(positions, w_in, w_out, h_out, h_in=None, theta=0.0)[source]¶
Bases:
RectangularMaskMixin
,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:
- w_infloat
The inner full width of the rectangular annulus in pixels. For
theta=0
the width side is along thex
axis.- w_outfloat
The outer full width of the rectangular annulus in pixels. For
theta=0
the width side is along thex
axis.- h_outfloat
The outer full height of the rectangular annulus in pixels.
- h_in
None
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 they
axis.- thetafloat or
Quantity
, optional The rotation angle as an angular quantity (
Quantity
orAngle
) or value in radians (as a float) from the positivex
axis. The rotation angle increases counterclockwise.
- Raises:
- ValueError
ValueError
If inner width (
w_in
) is greater than outer width (w_out
).- ValueError
ValueError
If either the inner width (
w_in
) or the outer height (h_out
) is negative.
- ValueError
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
The exact analytical area of the aperture shape.
The minimal bounding box for the aperture.
The inner full height in pixels.
The outer full height in pixels.
Whether the instance is scalar (i.e., a single position).
The center pixel position(s).
The shape of the instance.
The counterclockwise rotation angle as an angular Quantity or value in radians from the positive x axis.
The inner full width in pixels.
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 an independent (deep) copy.
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¶
- bbox¶
The minimal bounding box for the aperture.
If the aperture is scalar then a single
BoundingBox
is returned, otherwise a list ofBoundingBox
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 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 aTrue
value indicates the corresponding element ofdata
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 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 thesubpixels
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'
.
- dataarray_like or
- Returns:
- areasfloat or array_like
The area (in pixels**2) of overlap between the data and the aperture.
See also
- copy()¶
Make an independent (deep) copy.
- 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 (seecalc_total_error
) .error
must have the same shape as the inputdata
.- 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 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 thesubpixels
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'
.
- dataarray_like or
- Returns:
Notes
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.
- plot(ax=None, origin=(0, 0), **kwargs)¶
Plot the aperture on a matplotlib
Axes
instance.- Parameters:
- ax
matplotlib.axes.Axes
orNone
, optional The matplotlib axes on which to plot. If
None
, then the currentAxes
instance is used.- originarray_like, optional
The
(x, y)
position of the origin of the displayed image.- **kwargs
dict
Any keyword arguments accepted by
matplotlib.patches.Patch
.
- ax
- 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.
- patchlist of
- to_mask(method='exact', subpixels=5)[source]¶
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 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 thesubpixels
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'
.
- Returns:
- mask
ApertureMask
or list ofApertureMask
A mask for the aperture. If the aperture is scalar then a single
ApertureMask
is returned, otherwise a list ofApertureMask
is returned.
- mask
- 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:
- aperture
SkyRectangularAnnulus
object A
SkyRectangularAnnulus
object.
- aperture