EllipticalAnnulus¶
- class photutils.aperture.EllipticalAnnulus(positions, a_in, a_out, b_out, b_in=None, theta=0.0)[source]¶
Bases:
EllipticalMaskMixin
,PixelAperture
An elliptical 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:
- a_infloat
The inner semimajor axis of the elliptical annulus in pixels.
- a_outfloat
The outer semimajor axis of the elliptical annulus in pixels.
- b_outfloat
The outer semiminor axis of the elliptical annulus in pixels.
- b_in
None
or float, optional The inner semiminor axis of the elliptical annulus in pixels. If
None
, then the the inner semiminor axis is calculated as:\[b_{in} = b_{out} \left(\frac{a_{in}}{a_{out}}\right)\]- 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 semimajor axis (
a_in
) is greater than outer semimajor axis (a_out
).- ValueError
ValueError
If either the inner semimajor axis (
a_in
) or the outer semiminor axis (b_out
) is negative.
- ValueError
Examples
>>> from astropy.coordinates import Angle >>> from photutils.aperture import EllipticalAnnulus
>>> theta = Angle(80, 'deg') >>> aper = EllipticalAnnulus([10.0, 20.0], 3.0, 8.0, 5.0) >>> aper = EllipticalAnnulus((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 = EllipticalAnnulus([pos1, pos2, pos3], 3.0, 8.0, 5.0) >>> aper = EllipticalAnnulus((pos1, pos2, pos3), 3.0, 8.0, 5.0, ... theta=theta)
Attributes Summary
The inner semimajor axis in pixels.
The outer semimajor axis in pixels.
The exact analytical area of the aperture shape.
The inner semiminor axis in pixels.
The outer semiminor axis in pixels.
The minimal bounding box for the aperture.
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.
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
SkyEllipticalAnnulus
object defined in celestial coordinates.Attributes Documentation
- a_in¶
The inner semimajor axis in pixels.
- a_out¶
The outer semimajor axis in pixels.
- area¶
- b_in¶
The inner semiminor axis in pixels.
- b_out¶
The outer semiminor axis in pixels.
- 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).
- shape¶
The shape of the instance.
- theta¶
The counterclockwise rotation angle as an angular Quantity or value in radians from the positive x axis.
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
SkyEllipticalAnnulus
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
SkyEllipticalAnnulus
object A
SkyEllipticalAnnulus
object.
- aperture