CircularAnnulus¶
- class photutils.aperture.CircularAnnulus(positions, r_in, r_out)[source]¶
Bases:
CircularMaskMixin
,PixelAperture
A circular 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:
- r_infloat
The inner radius of the circular annulus in pixels.
- r_outfloat
The outer radius of the circular annulus in pixels.
- Raises:
- ValueError
ValueError
If inner radius (
r_in
) is greater than outer radius (r_out
).- ValueError
ValueError
If inner radius (
r_in
) is negative.
- ValueError
Examples
>>> from photutils.aperture import CircularAnnulus >>> aper = CircularAnnulus([10.0, 20.0], 3.0, 5.0) >>> aper = CircularAnnulus((10.0, 20.0), 3.0, 5.0)
>>> pos1 = (10.0, 20.0) # (x, y) >>> pos2 = (30.0, 40.0) >>> pos3 = (50.0, 60.0) >>> aper = CircularAnnulus([pos1, pos2, pos3], 3.0, 5.0) >>> aper = CircularAnnulus((pos1, pos2, pos3), 3.0, 5.0)
Attributes Summary
The exact analytical area of the aperture shape.
The minimal bounding box for the aperture.
Whether the instance is scalar (i.e., a single position).
The center pixel position(s).
The inner radius in pixels.
The outer radius in pixels.
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 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
SkyCircularAnnulus
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.
- isscalar¶
Whether the instance is scalar (i.e., a single position).
- positions¶
The center pixel position(s).
- r_in¶
The inner radius in pixels.
- r_out¶
The outer 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 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
SkyCircularAnnulus
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
SkyCircularAnnulus
object A
SkyCircularAnnulus
object.
- aperture