ApertureStats#

class photutils.aperture.ApertureStats(data, aperture, *, error=None, mask=None, wcs=None, sigma_clip=None, sum_method='exact', subpixels=5, local_bkg=None)[source]#

Bases: object

Class to create a catalog of statistics for pixels within an aperture.

Note that this class returns the statistics of the input data values within the aperture. It does not convert data in surface brightness units to flux or counts. Conversion from surface-brightness units should be performed before using this function.

Parameters:

data2D ndarray, Quantity, NDData

The 2D array from which to calculate the source properties. For accurate source properties, data should be background-subtracted. Non-finite data values (NaN and inf) are automatically masked.

apertureAperture or supported Region

The aperture or region to apply to the data. The aperture or region object may contain more than one position. If the input aperture is a SkyAperture or SkyRegion object, then a WCS must be input using the wcs keyword. Region objects are converted to aperture objects.

error2D ndarray or Quantity, optional

The total error array corresponding to the input data array. 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. If data is a Quantity array then error must be a Quantity array (and vice versa) with identical units. Non-finite error values (NaN and +/- inf) are not automatically masked, unless they are at the same position of non-finite values in the input data array. Such pixels can be masked using the mask keyword.

mask2D ndarray (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. Non-finite values (NaN and inf) in the input data are automatically masked.

wcsWCS object or None, optional

A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS, gwcs.wcs.WCS). wcs is required if the input aperture is a SkyAperture or SkyRegion object. If None, then all sky-based properties will be set to None.

sigma_clipNone or astropy.stats.SigmaClip instance, optional

A SigmaClip object that defines the sigma clipping parameters. If None then no sigma clipping will be performed.

sum_method{‘exact’, ‘center’, ‘subpixel’}, optional

The method used to determine the overlap of the aperture on the pixel grid. This method is used only for calculating the sum, sum_error, sum_aper_area, data_sum_cutout, and error_sum_cutout properties. All other properties use the “center” aperture mask method. Not all options are available for all aperture types. 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 sum_method='subpixel'.

local_bkgfloat, ndarray, Quantity, or None

The per-pixel local background values to subtract from the data before performing measurements. If input as an array, the order of local_bkg values corresponds to the order of the input aperture positions. local_bkg must have the same length as the input aperture or must be a scalar value, which will be broadcast to all apertures. If None, then no local background subtraction is performed. If the input data has units, then local_bkg must be a Quantity with the same units.

Notes

data should be background-subtracted for accurate source properties. In addition to global background subtraction, local background subtraction can be performed using the local_bkg keyword values.

Region objects are converted to Aperture objects using the region_to_aperture() function.

The returned statistics are measured for the pixels within the input aperture at its input position. This class does not change the position of the input aperture. This class returns the centroid value of the pixels within the input aperture, but the input aperture is not recentered at the measured centroid position when making the measurements. If desired, you can create a new Aperture object using the measured centroid and then re-run ApertureStats.

Most source properties are calculated using the “center” aperture-mask method, which gives aperture weights of 0 or 1. This avoids the need to compute weighted statistics — the data pixel values are directly used.

The input sum_method and subpixels keywords are used to determine the aperture-mask method when calculating the sum-related properties: sum, sum_error, sum_aper_area, data_sum_cutout, and error_sum_cutout. The default is sum_method='exact', which produces exact aperture-weighted photometry.

Examples

>>> from photutils.datasets import make_4gaussians_image
>>> from photutils.aperture import CircularAperture, ApertureStats

>>> data = make_4gaussians_image()
>>> aper = CircularAperture((150, 25), 8)
>>> aperstats = ApertureStats(data, aper)
>>> print(aperstats.x_centroid)
149.99080259251238
>>> print(aperstats.y_centroid)
24.97484633000507
>>> print(aperstats.centroid)
[149.99080259  24.97484633]

>>> print(aperstats.mean, aperstats.median)
47.76300955780609 31.913789514433084

>>> print(aperstats.std)
39.193655383492974

>>> print(aperstats.sum)
9286.709206410273

>>> print(aperstats.sum_aper_area)
201.0619298297468 pix2

>>> # More than one aperture position
>>> aper2 = CircularAperture(((150, 25), (90, 60)), 10)
>>> aperstats2 = ApertureStats(data, aper2)
>>> print(aperstats2.x_centroid)
[149.98470724  89.97893946]
>>> print(aperstats2.sum)
[10177.62548482 36653.97704059]

Attributes Summary

`bbox`	The `BoundingBox` of the aperture.
`bbox_xmax`	The maximum `x`-pixel index of the bounding box.
`bbox_xmin`	The minimum `x`-pixel index of the bounding box.
`bbox_ymax`	The maximum `y`-pixel index of the bounding box.
`bbox_ymin`	The minimum `y`-pixel index of the bounding box.
`biweight_location`	The biweight location of the unmasked pixel values within the aperture.
`biweight_midvariance`	The biweight midvariance of the unmasked pixel values within the aperture.
`center_aper_area`	The total area of the unmasked pixels within the aperture using the "center" aperture mask method.
`centroid`	The `(x, y)` coordinate of the centroid.
`covariance`	The covariance matrix of the 2D Gaussian function that has the same second-order moments as the source.
`covariance_eigvals`	The two eigenvalues of the `covariance` matrix in decreasing order.
`covariance_xx`	The `(0, 0)` element of the `covariance` matrix, representing \(\sigma_x^2\), in units of pixel**2.
`covariance_xy`	The `(0, 1)` and `(1, 0)` elements of the `covariance` matrix, representing \(\sigma_x \sigma_y\), in units of pixel**2.
`covariance_yy`	The `(1, 1)` element of the `covariance` matrix, representing \(\sigma_y^2\), in units of pixel**2.
`cutout_centroid`	The `(x, y)` coordinate, relative to the cutout data, of the centroid within the aperture.
`data_cutout`	A 2D aperture-weighted cutout from the data using the aperture mask with the "center" method as a `MaskedArray`.
`data_sum_cutout`	A 2D aperture-weighted cutout from the data using the aperture mask with the input `sum_method` method as a `MaskedArray`.
`eccentricity`	The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.
`ellipse_cxx`	Coefficient for `x2` in the generalized ellipse equation in units of pixel(-2).
`ellipse_cxy`	Coefficient for `x * y` in the generalized ellipse equation in units of pixel**(-2).
`ellipse_cyy`	Coefficient for `y2` in the generalized ellipse equation in units of pixel(-2).
`ellipticity`	1.0 minus the ratio of the lengths of the semimajor and semiminor axes (or 1.0 minus the `elongation`).
`elongation`	The ratio of the lengths of the semimajor and semiminor axes.
`error_sum_cutout`	A 2D aperture-weighted error cutout using the aperture mask with the input `sum_method` method as a `MaskedArray`.
`fwhm`	The circularized full width at half maximum (FWHM) of the 2D Gaussian function that has the same second-order central moments as the source.
`gini`	The Gini coefficient of the unmasked pixel values within the aperture.
`id`	The aperture identification number(s).
`ids`	The aperture identification number(s), always as an iterable `ndarray`.
`inertia_tensor`	The inertia tensor of the source for the rotation around its center of mass.
`isscalar`	Whether the instance is scalar (e.g., a single aperture position).
`mad_std`	The standard deviation calculated using the median absolute deviation (MAD).
`max`	The maximum of the unmasked pixel values within the aperture.
`mean`	The mean of the unmasked pixel values within the aperture.
`median`	The median of the unmasked pixel values within the aperture.
`min`	The minimum of the unmasked pixel values within the aperture.
`mode`	The mode of the unmasked pixel values within the aperture.
`moments`	Spatial moments up to 3rd order of the source.
`moments_central`	Central moments (translation invariant) of the source up to 3rd order.
`n_apertures`	The number of positions for the input aperture.
`orientation`	The angle between the `x` axis and the major axis of the 2D Gaussian function that has the same second-order moments as the source.
`properties`	A sorted list of the built-in source properties.
`semimajor_axis`	The 1-sigma standard deviation along the semimajor axis of the 2D Gaussian function that has the same second-order central moments as the source.
`semiminor_axis`	The 1-sigma standard deviation along the semiminor axis of the 2D Gaussian function that has the same second-order central moments as the source.
`sky_centroid`	The sky coordinate of the centroid of the unmasked pixels within the aperture, returned as a `SkyCoord` object.
`sky_centroid_icrs`	The sky coordinate in the International Celestial Reference System (ICRS) frame of the centroid of the unmasked pixels within the aperture, returned as a `SkyCoord` object.
`std`	The standard deviation of the unmasked pixel values within the aperture.
`sum`	The sum of the unmasked `data` values within the aperture.
`sum_aper_area`	The total area of the unmasked pixels within the aperture using the input `sum_method` aperture mask method.
`sum_err`	The uncertainty of `sum`, propagated from the input `error` array.
`var`	The variance of the unmasked pixel values within the aperture.
`x_centroid`	The `x` coordinate of the centroid.
`y_centroid`	The `y` coordinate of the centroid.

Methods Summary

`copy`()	Return a deep copy of this object.
`select_id`(id_num)	Return a new `ApertureStats` object for the input ID number only.
`select_ids`(id_nums)	Return a new `ApertureStats` object for the input ID numbers only.
`to_table`(*[, columns])	Create a `QTable` of source properties.

Attributes Documentation

bbox#

The BoundingBox of the aperture.

Note that the aperture bounding box is calculated using the exact size of the aperture, which may be slightly larger than the aperture mask calculated using the “center” method.

bbox_xmax#

The maximum x-pixel index of the bounding box.

Note that this value is inclusive, unlike numpy slice indices.

bbox_xmin#: The minimum x-pixel index of the bounding box.

bbox_ymax#

The maximum y-pixel index of the bounding box.

Note that this value is inclusive, unlike numpy slice indices.

bbox_ymin#: The minimum y-pixel index of the bounding box.

biweight_location#

The biweight location of the unmasked pixel values within the aperture.

See astropy.stats.biweight_location.

biweight_midvariance#

The biweight midvariance of the unmasked pixel values within the aperture.

See astropy.stats.biweight_midvariance

center_aper_area#: The total area of the unmasked pixels within the aperture using the “center” aperture mask method.

centroid#

The (x, y) coordinate of the centroid.

The centroid is computed as the center of mass of the unmasked pixels within the aperture.

covariance#: The covariance matrix of the 2D Gaussian function that has the same second-order moments as the source.

covariance_eigvals#: The two eigenvalues of the covariance matrix in decreasing order.

covariance_xx#: The (0, 0) element of the covariance matrix, representing \(\sigma_x^2\), in units of pixel**2.

covariance_xy#: The (0, 1) and (1, 0) elements of the covariance matrix, representing \(\sigma_x \sigma_y\), in units of pixel**2.

covariance_yy#: The (1, 1) element of the covariance matrix, representing \(\sigma_y^2\), in units of pixel**2.

cutout_centroid#

The (x, y) coordinate, relative to the cutout data, of the centroid within the aperture.

The centroid is computed as the center of mass of the unmasked pixels within the aperture.

data_cutout#

A 2D aperture-weighted cutout from the data using the aperture mask with the “center” method as a MaskedArray.

The cutout does not have units due to current limitations of masked quantity arrays.

The mask is True for pixels from the input mask, non-finite data values (NaN and inf), sigma-clipped pixels within the aperture, and pixels where the aperture mask has zero weight.

data_sum_cutout#

A 2D aperture-weighted cutout from the data using the aperture mask with the input sum_method method as a MaskedArray.

The cutout does not have units due to current limitations of masked quantity arrays.

The mask is True for pixels from the input mask, non-finite data values (NaN and inf), sigma-clipped pixels within the aperture, and pixels where the aperture mask has zero weight.

eccentricity#

The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.

The eccentricity is the fraction of the distance along the semimajor axis at which the focus lies.

\[e = \sqrt{1 - \frac{b^2}{a^2}}\]

where \(a\) and \(b\) are the lengths of the semimajor and semiminor axes, respectively.

ellipse_cxx#

Coefficient for x**2 in the generalized ellipse equation in units of pixel**(-2).

The ellipse is defined as

\[cxx (x - \bar{x})^2 + cxy (x - \bar{x}) (y - \bar{y}) + cyy (y - \bar{y})^2 = R^2\]

where \(R\) is a parameter which scales the ellipse (in units of the axes lengths).

SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

ellipse_cxy#

Coefficient for x * y in the generalized ellipse equation in units of pixel**(-2).

The ellipse is defined as

\[cxx (x - \bar{x})^2 + cxy (x - \bar{x}) (y - \bar{y}) + cyy (y - \bar{y})^2 = R^2\]

where \(R\) is a parameter which scales the ellipse (in units of the axes lengths).

SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

ellipse_cyy#

Coefficient for y**2 in the generalized ellipse equation in units of pixel**(-2).

The ellipse is defined as

\[cxx (x - \bar{x})^2 + cxy (x - \bar{x}) (y - \bar{y}) + cyy (y - \bar{y})^2 = R^2\]

where \(R\) is a parameter which scales the ellipse (in units of the axes lengths).

SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

ellipticity#

1.0 minus the ratio of the lengths of the semimajor and semiminor axes (or 1.0 minus the elongation).

\[\mathrm{ellipticity} = 1 - \frac{b}{a}\]

where \(a\) and \(b\) are the lengths of the semimajor and semiminor axes, respectively.

elongation#

The ratio of the lengths of the semimajor and semiminor axes.

\[\mathrm{elongation} = \frac{a}{b}\]

where \(a\) and \(b\) are the lengths of the semimajor and semiminor axes, respectively.

error_sum_cutout#

A 2D aperture-weighted error cutout using the aperture mask with the input sum_method method as a MaskedArray.

The cutout does not have units due to current limitations of masked quantity arrays.

The mask is True for pixels from the input mask, non-finite data values (NaN and inf), sigma-clipped pixels within the aperture, and pixels where the aperture mask has zero weight.

fwhm#

The circularized full width at half maximum (FWHM) of the 2D Gaussian function that has the same second-order central moments as the source.

\[\begin{split}\mathrm{FWHM} & = 2 \sqrt{2 \ln(2)} \sqrt{0.5 (a^2 + b^2)} \\ & = 2 \sqrt{\ln(2) \ (a^2 + b^2)}\end{split}\]

where \(a\) and \(b\) are the 1-sigma lengths of the semimajor (semimajor_axis) and semiminor (semiminor_axis) axes, respectively.

gini#

The Gini coefficient of the unmasked pixel values within the aperture.

The Gini coefficient of the distribution of absolute flux values is calculated using the prescription from Lotz et al. 2004 (Eq. 6) as:

\[G = \frac{1}{\overline{|x|} \, n \, (n - 1)} \sum^{n}_{i} (2i - n - 1) \left | x_i \right |\]

where \(\overline{|x|}\) is the mean of the absolute value of all pixel values \(x_i\). If the sum of all pixel values is zero, the Gini coefficient is zero.

Negative pixel values are used via their absolute value. Invalid values (NaN and inf) in the input are automatically excluded from the calculation. If only a single finite pixel remains after filtering, the Gini coefficient is 0.0.

id#: The aperture identification number(s).

ids#: The aperture identification number(s), always as an iterable ndarray.

inertia_tensor#: The inertia tensor of the source for the rotation around its center of mass.

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

mad_std#

The standard deviation calculated using the median absolute deviation (MAD).

The standard deviation estimator is given by:

\[\sigma \approx \frac{\textrm{MAD}}{\Phi^{-1}(3/4)} \approx 1.4826 \ \textrm{MAD}\]

where \(\Phi^{-1}(P)\) is the normal inverse cumulative distribution function evaluated at probability \(P = 3/4\).

max#: The maximum of the unmasked pixel values within the aperture.

mean#: The mean of the unmasked pixel values within the aperture.

median#: The median of the unmasked pixel values within the aperture.

min#: The minimum of the unmasked pixel values within the aperture.

mode#

The mode of the unmasked pixel values within the aperture.

The mode is estimated as (3 * median) - (2 * mean).

moments#: Spatial moments up to 3rd order of the source.

moments_central#: Central moments (translation invariant) of the source up to 3rd order.

n_apertures#: The number of positions for the input aperture.

orientation#

The angle between the x axis and the major axis of the 2D Gaussian function that has the same second-order moments as the source.

The angle increases in the counter-clockwise direction.

properties#: A sorted list of the built-in source properties.

semimajor_axis#: The 1-sigma standard deviation along the semimajor axis of the 2D Gaussian function that has the same second-order central moments as the source.

semiminor_axis#: The 1-sigma standard deviation along the semiminor axis of the 2D Gaussian function that has the same second-order central moments as the source.

sky_centroid#

The sky coordinate of the centroid of the unmasked pixels within the aperture, returned as a SkyCoord object.

The output coordinate frame is the same as the input wcs.

None if wcs is not input.

sky_centroid_icrs#

The sky coordinate in the International Celestial Reference System (ICRS) frame of the centroid of the unmasked pixels within the aperture, returned as a SkyCoord object.

None if wcs is not input.

std#: The standard deviation of the unmasked pixel values within the aperture.

sum#

The sum of the unmasked data values within the aperture.

\[F = \sum_{i \in A} I_i\]

where \(F\) is sum, \(I_i\) is the background-subtracted data, and \(A\) are the unmasked pixels in the aperture.

Non-finite pixel values (NaN and inf) are excluded (automatically masked).

sum_aper_area#: The total area of the unmasked pixels within the aperture using the input sum_method aperture mask method.

sum_err#

The uncertainty of sum, propagated from the input error array.

sum_err is the quadrature sum of the total errors over the unmasked pixels within the aperture:

\[\Delta F = \sqrt{\sum_{i \in A} \sigma_{\mathrm{tot}, i}^2}\]

where \(\Delta F\) is the sum_err, \(\sigma_{\mathrm{tot, i}}\) are the pixel-wise total errors (error), and \(A\) are the unmasked pixels in the aperture.

Pixel values that are masked in the input data, including any non-finite pixel values (NaN and inf) that are automatically masked, are also masked in the error array.

var#: The variance of the unmasked pixel values within the aperture.

x_centroid#

The x coordinate of the centroid.

The centroid is computed as the center of mass of the unmasked pixels within the aperture.

y_centroid#

The y coordinate of the centroid.

The centroid is computed as the center of mass of the unmasked pixels within the aperture.

Methods Documentation

copy()[source]#

Return a deep copy of this object.

Returns:

resultApertureStats: A deep copy of this object.

select_id(id_num)[source]#

Return a new ApertureStats object for the input ID number only.

Parameters:

id_numint: The aperture ID number.

Returns:

resultApertureStats: A new ApertureStats object containing only the source with the input ID number.

select_ids(id_nums)[source]#

Return a new ApertureStats object for the input ID numbers only.

Parameters:

id_numslist, tuple, or ndarray of int: The aperture ID number(s).

Returns:

resultApertureStats: A new ApertureStats object containing only the sources with the input ID numbers.

to_table(*, columns=None)[source]#

Create a QTable of source properties.

Parameters:

columnsstr, list of str, None, optional: Names of columns, in order, to include in the output QTable. The allowed column names are any of the ApertureStats properties. If columns is None, then a default list of scalar-valued properties (as defined by the default_columns attribute) will be used.

Returns:

tableQTable: A table of sources properties with one row per source.