ApertureStats#

class photutils.aperture.ApertureStats(data, aperture, *, error=None, mask=None, wcs=None, sigma_clip=None, sum_method='exact', subpixels=5, ddof=0, local_bkg=None, segmentation_image=None, labels=None, mask_method='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 pixel weights (the fraction of the pixel area covered by the aperture). 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. The following methods are available:

'exact' (default): Calculates the exact geometric overlap area. Weights are continuous in the range [0, 1].
'center': Binary weighting based on the pixel center. Weights are either 0 or 1. A pixel is included only if its center lies strictly inside the aperture; pixel centers lying exactly on the aperture boundary are excluded (weight 0).
'subpixel': Approximates the overlap by averaging binary samples on a subgrid. The number of samples is set by the subpixels parameter. Weights are discrete in the range [0, 1]. A subpixel is included only if its center lies strictly inside the aperture; subpixel centers lying exactly on the aperture boundary are excluded (weight 0).

subpixelsint, optional

The subsampling factor per axis used when method='subpixel'. Each pixel is divided into a grid of subpixels**2 subpixels to approximate the overlap. This parameter is ignored for other methods.

ddofint, optional

The delta degrees of freedom used when computing the var and std properties. The divisor used in the calculation is N - ddof, where N is the number of unmasked pixels within the aperture. The default is ddof=0, which gives the population variance and standard deviation. Use ddof=1 to obtain the sample (unbiased) variance and standard deviation. This keyword affects only the var and std properties. All other properties are unaffected, including the mean_err and median_err standard errors, which are always computed using the sample standard deviation. Apertures with N <= ddof unmasked pixels have an undefined var and std and are set to NaN.

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.

segmentation_imageSegmentationImage, 2D array_like, or None, optional

A 2D segmentation image with the same shape as data, where background pixels have a value of 0 and sources are labeled with positive integers. If input, neighboring sources can be masked or corrected within each aperture according to the mask_method keyword. This keyword is required if mask_method is not 'none'. When segmentation_image is input, the labels keyword must also be provided to ensure the correct target source is used for each aperture. If segmentation_image is None, then the mask_method keyword is ignored and no neighboring source masking or correction is performed.

labelsint, 1D array_like, or None, optional

The source label(s) in segmentation_image associated with the aperture position(s). labels is required if segmentation_image is input and mask_method is not 'none'. labels must have the same length as the number of aperture positions.

mask_method{‘none’, ‘mask’, ‘source_only’, ‘correct’}, optional

The method used to handle neighboring sources within each aperture using the segmentation_image:

'none' (default): The segmentation_image is ignored and all pixels within the aperture are included.
'mask': Pixels belonging to neighboring sources (i.e., labeled but not the target source) are excluded.
'source_only': Only pixels belonging to the target source are included; both neighboring sources and background pixels are excluded.
'correct': Pixels belonging to neighboring sources are replaced by the values of the pixels mirrored across the aperture center. If a mirror pixel is unavailable, the pixel is excluded.

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.

All properties other than the sum-related ones described below are calculated using the “center” aperture-mask method, which assigns aperture weights of either 0 or 1, so the data pixel values are used directly and without weighting. This choice reflects a fundamental limitation because, unlike the mean or variance, order statistics (min, max, median) and robust estimators (mad_std, biweight_location, biweight_midvariance) have no standard, unambiguous definition for pixels with fractional (partial) aperture weights. Accordingly, these quantities cannot be rigorously computed from a weighted aperture footprint.

The input sum_method and subpixels keywords are used to determine the aperture-mask method only for the sum-related properties: sum, sum_err, sum_aper_area, data_sum_cutout, and error_sum_cutout (also listed in the SUM_FOOTPRINT_PROPERTIES class attribute). All other properties, including mean, median, std, and the morphological properties, always use the “center” aperture-mask method regardless of sum_method. The default is sum_method='exact', which produces exact aperture-weighted photometry.

The sum-related properties have their own separate sum_flags quality flags, distinct from the flags property used by all other properties. To check for any quality issue across both footprints, combine the two flag columns with a bitwise OR, e.g., aperstats.flags | aperstats.sum_flags.

The calculated statistics are always float64, regardless of the input data dtype (Quantity values with float64 dtype if the input data has units).

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

`SUM_FOOTPRINT_PROPERTIES`
`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`.
`flags`	The bitwise quality flags for the value statistics.
`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`
`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.
`mean_err`	The standard error of the `mean`.
`median`	The median of the unmasked pixel values within the aperture.
`median_err`	The standard error of the `median`.
`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.
`sum_flags`	The bitwise quality flags for the sum properties.
`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.
`decode_flags`(*[, column, return_bit_values])	Decode the source quality flags into individual components.
`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

SUM_FOOTPRINT_PROPERTIES = ('sum', 'sum_err', 'sum_aper_area', 'data_sum_cutout', 'error_sum_cutout', 'sum_flags')#

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.

The tuning constant is fixed at c=6, the default value used by astropy.stats.biweight_location.

biweight_midvariance#

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

The tuning constant is fixed at c=9, the default value used by 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).

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

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

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.

flags[source]#

The bitwise quality flags for the value statistics.

The flags are evaluated on the “center”-method footprint used by the value statistics (e.g., mean, median, std). The sum properties (sum, sum_err, and sum_aper_area) have their own separate sum_flags. The 'sigma_clipped', 'all_clipped', and 'too_few_pixels' flags are evaluated on this footprint. To check for any quality issue across both footprints, combine the two flag columns with a bitwise OR (e.g., flags | sum_flags).

The 'singular_covariance' bit is special. It reports whether a source’s covariance matrix is singular or nearly singular, a condition that is only knowable once a covariance-derived shape property (e.g., semimajor_axis, orientation, eccentricity) has been computed. To avoid forcing that computation, the bit is included only if such a property has already been evaluated on this object; otherwise it is omitted. This means the value of flags reflects the measurements requested so far, so accessing a shape property and then re-reading flags may set additional bits. The default to_table always evaluates the shape properties, so its flags column always reflects the 'singular_covariance' bit.

See decode_aperture_flags for decoding flag values. The flags are:

0 : No flags set.
1 ('no_overlap') : The aperture is fully outside the data array: no pixel with nonzero aperture weight falls inside the data.
2 ('partial_overlap') : The aperture is partially outside the data array: one or more pixels with nonzero aperture weight fall outside the data.
4 ('no_pixels') : The aperture contains zero pixels with nonzero weight inside the data, e.g., a fully off-image aperture or a tiny aperture that contains no pixel (or subpixel) centers with the “center” or “subpixel” methods.
8 ('masked_pixels') : One or more input-masked pixels (mask keyword) have nonzero aperture weight.
16 ('all_masked') : The aperture contains pixels, but none are valid: every nonzero-weight pixel inside the data is masked, non-finite, or excluded by segmentation masking.
32 ('non_finite_data') : One or more unmasked data values (NaN or inf) with nonzero aperture weight are non-finite.
64 ('non_finite_error') : One or more unmasked error values (NaN or inf) with nonzero aperture weight are non-finite.
128 ('neighbor_pixels') : One or more pixels within the aperture were excluded, restricted, or corrected due to neighboring sources in the segmentation image.
256 ('uncorrected_pixels') : With mask_method="correct", one or more neighbor-source pixels could not be corrected (the mirror pixel was unavailable) and were excluded instead.
512 ('sigma_clipped') : One or more pixels within the aperture were rejected by sigma clipping.
1024 ('all_clipped') : All valid pixels within the aperture were rejected by sigma clipping.
2048 ('too_few_pixels') : There are too few valid pixels within the aperture to compute a requested statistic (e.g., the variance and standard deviation are undefined when the number of valid pixels is not larger than ddof).
4096 ('singular_covariance') : The source covariance matrix is singular or nearly singular (the minor-axis variance is below 1/12, the variance of a uniform distribution across a single pixel), so covariance-derived shape properties (e.g., semimajor_axis, orientation, eccentricity) are ill-defined and have been regularized or set to NaN. This is a stats-only flag that is set only when a covariance-derived property has been computed.

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#: Deprecated since version 3.1: This function was deprecated in version 3.1 and will be removed in version 4.0. Use the ‘id’ attribute instead.

The aperture identification number(s).

Deprecated since version 3.1: Use the id attribute instead.

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.

mean_err#

The standard error of the mean.

mean_err is the standard deviation of the sampling distribution of the mean:

\[\sigma_{\bar{x}} = \frac{s}{\sqrt{N}}\]

where \(s\) is the sample standard deviation (computed with N - 1 in the denominator) and \(N\) is the number of unmasked pixels within the aperture (center_aper_area).

Apertures with fewer than two unmasked pixels have an undefined standard error and are set to NaN.

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

median_err#

The standard error of the median.

median_err is the large-sample approximation of the standard error of the median:

\[\sigma_{\mathrm{med}} \approx \sqrt{\frac{\pi}{2}} \ \frac{s}{\sqrt{N}}\]

where \(s\) is the sample standard deviation (computed with N - 1 in the denominator) and \(N\) is the number of unmasked pixels within the aperture (center_aper_area).

This approximation assumes that the pixel values are approximately normally distributed. Apertures with fewer than two unmasked pixels have an undefined standard error and are set to NaN.

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 and is in the range (-90, 90] degrees.

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.

The divisor used in the calculation is N - ddof, where N is the number of unmasked pixels within the aperture and ddof is the value of the ddof keyword (default 0).

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.

sum_flags#

The bitwise quality flags for the sum properties.

The flags are evaluated on the sum_method footprint used by the sum properties (sum, sum_err, and sum_aper_area). The value statistics have their own separate flags. The 'non_finite_error' flag is evaluated on this footprint. The 'sigma_clipped', 'all_clipped', and 'too_few_pixels' flags apply only to the value statistics and are never set here. To check for any quality issue across both footprints, combine the two flag columns with a bitwise OR (e.g., flags | sum_flags).

See decode_aperture_flags for decoding flag values. The flags are:

0 : No flags set.
1 ('no_overlap') : The aperture is fully outside the data array: no pixel with nonzero aperture weight falls inside the data.
2 ('partial_overlap') : The aperture is partially outside the data array: one or more pixels with nonzero aperture weight fall outside the data.
4 ('no_pixels') : The aperture contains zero pixels with nonzero weight inside the data, e.g., a fully off-image aperture or a tiny aperture that contains no pixel (or subpixel) centers with the “center” or “subpixel” methods.
8 ('masked_pixels') : One or more input-masked pixels (mask keyword) have nonzero aperture weight.
16 ('all_masked') : The aperture contains pixels, but none are valid: every nonzero-weight pixel inside the data is masked, non-finite, or excluded by segmentation masking.
32 ('non_finite_data') : One or more unmasked data values (NaN or inf) with nonzero aperture weight are non-finite.
64 ('non_finite_error') : One or more unmasked error values (NaN or inf) with nonzero aperture weight are non-finite.
128 ('neighbor_pixels') : One or more pixels within the aperture were excluded, restricted, or corrected due to neighboring sources in the segmentation image.
256 ('uncorrected_pixels') : With mask_method="correct", one or more neighbor-source pixels could not be corrected (the mirror pixel was unavailable) and were excluded instead.
512 ('sigma_clipped') : One or more pixels within the aperture were rejected by sigma clipping.
1024 ('all_clipped') : All valid pixels within the aperture were rejected by sigma clipping.
2048 ('too_few_pixels') : There are too few valid pixels within the aperture to compute a requested statistic (e.g., the variance and standard deviation are undefined when the number of valid pixels is not larger than ddof).
4096 ('singular_covariance') : The source covariance matrix is singular or nearly singular (the minor-axis variance is below 1/12, the variance of a uniform distribution across a single pixel), so covariance-derived shape properties (e.g., semimajor_axis, orientation, eccentricity) are ill-defined and have been regularized or set to NaN. This is a stats-only flag that is set only when a covariance-derived property has been computed.

var#

The variance of the unmasked pixel values within the aperture.

The divisor used in the calculation is N - ddof, where N is the number of unmasked pixels within the aperture and ddof is the value of the ddof keyword (default 0).

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.

decode_flags(*, column='flags', return_bit_values=False)[source]#

Decode the source quality flags into individual components.

This is a convenience method that calls decode_aperture_flags with the flags or sum_flags property.

Parameters:

column{‘flags’, ‘sum_flags’}, optional: Which quality flags to decode: 'flags' for the value statistics (default) or 'sum_flags' for the sum properties.
return_bit_valuesbool, optional: If True, return the decoded bit flags (integers) instead of the flag names (strings).

Returns:

decodedlist of list of str or list of list of int: A list of the active flag names (or bit values) for each source.