SourceCatalog

class photutils.segmentation.SourceCatalog(data, segment_img, *, convolved_data=None, error=None, mask=None, kernel=None, background=None, wcs=None, localbkg_width=0, apermask_method='correct', kron_params=(2.5, 1.0), detection_cat=None)

Bases: object

Class to create a catalog of photometry and morphological properties for sources defined by a segmentation image.

Parameters

data2D ndarray or Quantity, optional

The 2D array from which to calculate the source photometry and properties. If convolved_data (or kernel) is input, then a convolved version of data will be used instead of data to calculate the source centroid and morphological properties. Source photometry is always measured from data. For accurate source properties and photometry, data should be background-subtracted. Non-finite data values (NaN and inf) are automatically masked.

segment_imgSegmentationImage

A SegmentationImage object defining the sources.

convolved_datadata2D ndarray or Quantity, optional

The 2D array used to calculate the source centroid and morphological properties. It is recommended that the user input the convolved data directly instead of using the kernel keyword. If convolved_data is input, then the kernel keyword will be ignored. If both convolved_data and kernel are None, then the unconvolved data will be used instead. Non-finite convolved_data 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.

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. See the Notes section below for details on the error propagation.

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.

kernelarray-like (2D) or Kernel2D, optional

The 2D array of the kernel used to filter the data prior to calculating the source centroid and morphological parameters. The kernel should be the same one used in defining the source segments, i.e., the detection image (e.g., see detect_sources()). If None, then the unfiltered data will be used instead. This keyword is ignored if convolved_data is input (recommended).

backgroundfloat, 2D ndarray or Quantity, optional

The background level that was previously present in the input data. background may either be a scalar value or a 2D image with the same shape as the input data. If data is a Quantity array then background must be a Quantity array (and vice versa) with identical units. Inputing the background merely allows for its properties to be measured within each source segment. The input background does not get subtracted from the input data, which should already be background-subtracted. Non-finite background 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.

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). If None, then all sky-based properties will be set to None.

localbkg_widthint, optional

The width of the rectangular annulus used to compute a local background around each source. If 0.0, then no local background subtraction is performed. The local background affects the min_value, max_value, segment_flux, and kron_flux properties. It does not affect the moment-based morphological properties of the source.

apermask_method{‘correct’, ‘mask’, ‘none’}, optional

The method used to handle neighboring sources when performing aperture photometry (e.g., circular apertures or elliptical Kron apertures). This parameter also affects the Kron radius.

• ‘correct’: replace pixels assigned to neighboring sources by replacing them with pixels on the opposite side of the source center (equivalent to MASK_TYPE=CORRECT in SourceExtractor).

• ‘mask’: mask pixels assigned to neighboring sources (equivalent to MASK_TYPE=BLANK in SourceExtractor).

• ‘none’: do not mask any pixels (equivalent to MASK_TYPE=NONE in SourceExtractor).

kron_paramslist of 2 floats, optional

A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius and the second item represents the minimum circular radius. If the Kron radius times sqrt(semimajor_sigma * semiminor_sigma) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.

detection_catSourceCatalog, optional

A SourceCatalog object for the detection image. The source labels in detection_cat must correspond to the labels in the input segment_img. If input, this detection catalog will be used to define the source centroids for all aperture-based photometry (e.g., local background aperture, circular aperture, Kron aperture). It will also be used to define the object elliptical shape parameters when calculating the Kron radius. This keyword affects the local-background value, circular aperture photometry, Kron radius, and Kron photometry.

Notes

data should be background-subtracted for accurate source photometry and properties. The previously-subtracted background can be passed into this class to calculate properties of the background for each source.

SourceExtractor’s centroid and morphological parameters are always calculated from a convolved, or filtered, “detection” image (convolved_data), i.e., the image used to define the segmentation image. The usual downside of the filtering is the sources will be made more circular than they actually are. If you wish to reproduce SourceExtractor centroid and morphology results, then input the convolved_data (or kernel, but not both). If convolved_data and kernel are both None, then the unfiltered data will be used for the source centroid and morphological parameters.

Negative data values within the source segment are set to zero when calculating morphological properties based on image moments. Negative values could occur, for example, if the segmentation image was defined from a different image (e.g., different bandpass) or if the background was oversubtracted. However, segment_flux always includes the contribution of negative data values.

The input error array is assumed to include all sources of error, including the Poisson error of the sources. segment_fluxerr is simply the quadrature sum of the pixel-wise total errors over the unmasked pixels within the source segment:

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

where \(\Delta F\) is segment_fluxerr, \(S\) are the unmasked pixels in the source segment, and \(\sigma_{\mathrm{tot}, i}\) is the input error array.

Custom errors for source segments can be calculated using the error_ma and background_ma properties, which are 2D MaskedArray cutout versions of the input error and background arrays. The mask is True for pixels outside of the source segment, masked pixels from the mask input, or any non-finite data values (NaN and inf).

Attributes Summary

area	The total unmasked area of the source segment in units of pixels**2.
background	A 2D ndarray cutout from the background array using the minimal bounding box of the source.
background_centroid	The value of the per-pixel background at the position of the source centroid.
background_ma	A 2D MaskedArray cutout from the background array.
background_mean	The mean of background values within the source segment.
background_sum	The sum of background values within the source segment.
bbox	The BoundingBox of the minimal rectangular region containing the source segment.
bbox_xmax	The maximum x pixel index within the minimal bounding box containing the source segment.
bbox_xmin	The minimum x pixel index within the minimal bounding box containing the source segment.
bbox_ymax	The maximum y pixel index within the minimal bounding box containing the source segment.
bbox_ymin	The minimum y pixel index within the minimal bounding box containing the source segment.
centroid	The (x, y) coordinate of the centroid within the source segment.
convdata	A 2D ndarray cutout from the convolved data using the minimal bounding box of the source.
convdata_ma	A 2D MaskedArray cutout from the convolved data using the minimal bounding box of the source.
covar_sigx2	The (0, 0) element of the covariance matrix, representing \(\sigma_x^2\), in units of pixel**2.
covar_sigxy	The (0, 1) and (1, 0) elements of the covariance matrix, representing \(\sigma_x \sigma_y\), in units of pixel**2.
covar_sigy2	The (1, 1) element of the covariance matrix, representing \(\sigma_y^2\), in units of pixel**2.
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.
cutout_centroid	The (x, y) coordinate, relative to the cutout data, of the centroid within the source segment.
cutout_maxval_index	The (y, x) coordinate, relative to the cutout data, of the maximum pixel value of the data within the source segment.
cutout_minval_index	The (y, x) coordinate, relative to the cutout data, of the minimum pixel value of the data within the source segment.
cxx	SourceExtractor's CXX ellipse parameter in units of pixel**(-2).
cxy	SourceExtractor's CXY ellipse parameter in units of pixel**(-2).
cyy	SourceExtractor's CYY ellipse parameter in units of pixel**(-2).
data	A 2D ndarray cutout from the data using the minimal bounding box of the source.
data_ma	A 2D MaskedArray cutout from the data using the minimal bounding box of the source.
eccentricity	The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.
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.
equivalent_radius	The radius of a circle with the same area as the source segment.
error	A 2D ndarray cutout from the error array using the minimal bounding box of the source.
error_ma	A 2D MaskedArray cutout from the error array using the minimal bounding box of the source.
extra_properties	A list of the user-defined source properties.
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 source.
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 source).
kron_aperture	The elliptical Kron aperture.
kron_flux	The flux in the Kron aperture.
kron_fluxerr	The flux error in the Kron aperture.
kron_radius	The unscaled first-moment Kron radius.
label	The source label number(s).
labels	The source label number(s), always as an iterable ndarray.
local_background	The local background value estimated using a rectangular annulus aperture around the source.
local_background_aperture	The RectangularAnnulus aperture used to estimate the local background.
max_value	The maximum pixel value of the data within the source segment.
maxval_index	The (y, x) coordinate of the maximum pixel value of the data within the source segment.
maxval_xindex	The x coordinate of the maximum pixel value of the data within the source segment.
maxval_yindex	The y coordinate of the maximum pixel value of the data within the source segment.
min_value	The minimum pixel value of the data within the source segment.
minval_index	The (y, x) coordinate of the minimum pixel value of the data within the source segment.
minval_xindex	The x coordinate of the minimum pixel value of the data within the source segment.
minval_yindex	The y coordinate of the minimum pixel value of the data within the source segment.
moments	Spatial moments up to 3rd order of the source.
moments_central	Central moments (translation invariant) of the source up to 3rd order.
nlabels	The number of source labels.
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.
perimeter	The perimeter of the source segment, approximated as the total length of lines connecting the centers of the border pixels defined by a 4-pixel connectivity.
properties	A list of built-in source properties.
segment	A 2D ndarray cutout of the segmentation image using the minimal bounding box of the source.
segment_flux	The sum of the unmasked data values within the source segment.
segment_fluxerr	The uncertainty of segment_flux , propagated from the input error array.
segment_ma	A 2D MaskedArray cutout of the segmentation image using the minimal bounding box of the source.
semimajor_sigma	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_sigma	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_bbox_ll	The sky coordinates of the lower-left corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.
sky_bbox_lr	The sky coordinates of the lower-right corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.
sky_bbox_ul	The sky coordinates of the upper-left corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.
sky_bbox_ur	The sky coordinates of the upper-right corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.
sky_centroid	The sky coordinate of the centroid within the source segment, returned as a SkyCoord object.
sky_centroid_icrs	The sky coordinate in the International Celestial Reference System (ICRS) frame of the centroid within the source segment, returned as a SkyCoord object.
slices	A tuple of slice objects defining the minimal bounding box of the source.
xcentroid	The x coordinate of the centroid within the source segment.
ycentroid	The y coordinate of the centroid within the source segment.

Methods Summary

add_extra_property(name, value[, overwrite])	Add a user-defined extra property as a new attribute.
circular_aperture(radius)	Deprecated since version 1.3.
circular_photometry(radius[, name, overwrite])	Perform aperture photometry for each source using a circular aperture of the specified radius centered at the source centroid position.
copy()	Return a deep copy of this SourceCatalog.
fluxfrac_radius(fluxfrac[, name, overwrite])	Calculate the circular radius that encloses the specified fraction of the Kron flux.
get_label(label)	Return a new SourceCatalog object for the input label only.
get_labels(labels)	Return a new SourceCatalog object for the input labels only.
kron_photometry(kron_params[, name, overwrite])	Perform photometry for each source using an elliptical Kron aperture.
make_circular_apertures(radius)	Return a list of circular apertures with the specified radius centered at the source centroid position.
make_kron_apertures(kron_params)	Return a list of Kron elliptical apertures with the specified scaling and centered at the source centroid position.
plot_circular_apertures(radius[, axes, origin])	Plot circular apertures on a matplotlib Axes instance.
plot_kron_apertures(kron_params[, axes, origin])	Plot Kron elliptical apertures on a matplotlib Axes instance.
remove_extra_properties(names)	Remove user-defined extra properties.
remove_extra_property(name)	Remove a user-defined extra property.
rename_extra_property(name, new_name)	Rename a user-defined extra property.
to_table([columns])	Create a QTable of source properties.

Attributes Documentation

area

The total unmasked area of the source segment in units of pixels**2.

Note that the source area may be smaller than its segment area if a mask is input to SourceCatalog or if the data within the segment contains invalid values (NaN and inf).

background

A 2D ndarray cutout from the background array using the minimal bounding box of the source.

background_centroid

The value of the per-pixel background at the position of the source centroid.

The background value at fractional position values are determined using bilinear interpolation.

background_ma

A 2D MaskedArray cutout from the background array. using the minimal bounding box of the source.

The mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and inf).

background_mean

The mean of background values within the source segment.

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 background array.

background_sum

The sum of background values within the source segment.

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 background array.

bbox

The BoundingBox of the minimal rectangular region containing the source segment.

bbox_xmax

The maximum x pixel index within the minimal bounding box containing the source segment.

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

bbox_xmin

The minimum x pixel index within the minimal bounding box containing the source segment.

bbox_ymax

The maximum y pixel index within the minimal bounding box containing the source segment.

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

bbox_ymin

The minimum y pixel index within the minimal bounding box containing the source segment.

centroid

The (x, y) coordinate of the centroid within the source segment.

convdata

A 2D ndarray cutout from the convolved data using the minimal bounding box of the source.

convdata_ma

A 2D MaskedArray cutout from the convolved data using the minimal bounding box of the source.

The mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and inf).

covar_sigx2

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

covar_sigxy

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

covar_sigy2

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

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.

cutout_centroid

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

cutout_maxval_index

The (y, x) coordinate, relative to the cutout data, of the maximum pixel value of the data within the source segment.

If there are multiple occurrences of the maximum value, only the first occurrence is returned.

cutout_minval_index

The (y, x) coordinate, relative to the cutout data, of the minimum pixel value of the data within the source segment.

If there are multiple occurrences of the minimum value, only the first occurrence is returned.

cxx

SourceExtractor’s CXX ellipse parameter 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\).

cxy

SourceExtractor’s CXY ellipse parameter 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\).

cyy

SourceExtractor’s CYY ellipse parameter 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\).

data

A 2D ndarray cutout from the data using the minimal bounding box of the source.

data_ma

A 2D MaskedArray cutout from the data using the minimal bounding box of the source.

The mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and inf).

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.

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.

equivalent_radius

The radius of a circle with the same area as the source segment.

error

A 2D ndarray cutout from the error array using the minimal bounding box of the source.

error_ma

A 2D MaskedArray cutout from the error array using the minimal bounding box of the source.

The mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and inf).

extra_properties

A list of the user-defined source properties.

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_sigma) and semiminor (semiminor_sigma) axes, respectively.

gini

The Gini coefficient of the source.

The Gini coefficient is calculated using the prescription from Lotz et al. 2004 as:

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

where \(\bar{x}\) is the mean over pixel values \(x_i\) within the source segment.

The Gini coefficient is a way of measuring the inequality in a given set of values. In the context of galaxy morphology, it measures how the light of a galaxy image is distributed among its pixels. A Gini coefficient value of 0 corresponds to a galaxy image with the light evenly distributed over all pixels while a Gini coefficient value of 1 represents a galaxy image with all its light concentrated in just one pixel.

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

kron_aperture

The elliptical Kron aperture.

For sources where

\[k_r \ \sqrt{a \cdot b} < rc_{min}\]

where \(k_r\) is the kron_radius, \(a\) and \(b\) are the semimajor (semimajor_sigma) and semiminor (semiminor_sigma) axes, respectively, and \(rc_{min}\) is the minimum circular radius defined by kron_params[1] (see SourceCatalog), then a circular aperture with a radius equal to kron_params[1] will be returned. If kron_params[1] <= 0, then the Kron aperture will be None.

If kron_radius = np.nan then a circular aperture with a radius equal to kron_params[1] will be returned if the source is not completely masked, otherwise None will be returned.

Note that if the Kron aperture is None, the Kron flux will be np.nan.

kron_flux

The flux in the Kron aperture.

See the SourceCatalog apermask_method keyword for options to mask neighboring sources.

If the Kron aperture is None, then np.nan will be returned.

kron_fluxerr

The flux error in the Kron aperture.

See the SourceCatalog apermask_method keyword for options to mask neighboring sources.

If the Kron aperture is None, then np.nan will be returned.

kron_radius

The unscaled first-moment Kron radius.

The unscaled first-moment Kron radius is given by:

\[k_r = \frac{\sum_{i \in A} \ r_i I_i}{\sum_{i \in A} I_i}\]

where \(I_i\) are the data values and the sum is over pixels in an elliptical aperture whose axes are defined by six times the semimajor (semimajor_sigma) and semiminor axes (semiminor_sigma) at the calculated orientation (all properties derived from the central image moments of the source). \(r_i\) is the elliptical “radius” to the pixel given by:

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

where \(\bar{x}\) and \(\bar{y}\) represent the source centroid and the coefficients are based on image moments (cxx, cxy, and cyy).

The scaling parameter of the kron_radius is defined using the SourceCatalog kron_params keyword.

See the SourceCatalog apermask_method keyword for options to mask neighboring sources.

If either the numerator or denominator above is less than or equal to 0, then np.nan will be returned for both the Kron radius and Kron flux.

If the source is completely masked, then np.nan will be returned for both the Kron radius and Kron flux.

If the SourceCatalog detection_cat was provided, then its kron_radius will be returned if the source is not completely masked.

label

The source label number(s).

This label number corresponds to the assigned pixel value in the SegmentationImage.

labels

The source label number(s), always as an iterable ndarray.

This label number corresponds to the assigned pixel value in the SegmentationImage.

local_background

The local background value estimated using a rectangular annulus aperture around the source.

local_background_aperture

The RectangularAnnulus aperture used to estimate the local background.

max_value

The maximum pixel value of the data within the source segment.

maxval_index

The (y, x) coordinate of the maximum pixel value of the data within the source segment.

If there are multiple occurrences of the maximum value, only the first occurrence is returned.

maxval_xindex

The x coordinate of the maximum pixel value of the data within the source segment.

If there are multiple occurrences of the maximum value, only the first occurrence is returned.

maxval_yindex

The y coordinate of the maximum pixel value of the data within the source segment.

If there are multiple occurrences of the maximum value, only the first occurrence is returned.

min_value

The minimum pixel value of the data within the source segment.

minval_index

The (y, x) coordinate of the minimum pixel value of the data within the source segment.

If there are multiple occurrences of the minimum value, only the first occurrence is returned.

minval_xindex

The x coordinate of the minimum pixel value of the data within the source segment.

If there are multiple occurrences of the minimum value, only the first occurrence is returned.

minval_yindex

The y coordinate of the minimum pixel value of the data within the source segment.

If there are multiple occurrences of the minimum value, only the first occurrence is returned.

moments

Spatial moments up to 3rd order of the source.

moments_central

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

nlabels

The number of source labels.

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.

perimeter

The perimeter of the source segment, approximated as the total length of lines connecting the centers of the border pixels defined by a 4-pixel connectivity.

If any masked pixels make holes within the source segment, then the perimeter around the inner hole (e.g., an annulus) will also contribute to the total perimeter.

References

1

K. Benkrid, D. Crookes, and A. Benkrid. “Design and FPGA Implementation of a Perimeter Estimator”. Proceedings of the Irish Machine Vision and Image Processing Conference, pp. 51-57 (2000). http://www.cs.qub.ac.uk/~d.crookes/webpubs/papers/perimeter.doc

properties

A list of built-in source properties.

segment

A 2D ndarray cutout of the segmentation image using the minimal bounding box of the source.

segment_flux

The sum of the unmasked data values within the source segment.

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

where \(F\) is segment_flux, \(I_i\) is the background-subtracted data, and \(S\) are the unmasked pixels in the source segment.

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

segment_fluxerr

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

segment_fluxerr is the quadrature sum of the total errors over the unmasked pixels within the source segment:

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

where \(\Delta F\) is the segment_flux, \(\sigma_{\mathrm{tot, i}}\) are the pixel-wise total errors (error), and \(S\) are the unmasked pixels in the source segment.

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.

segment_ma

A 2D MaskedArray cutout of the segmentation image using the minimal bounding box of the source.

The mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and inf).

semimajor_sigma

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_sigma

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_bbox_ll

The sky coordinates of the lower-left corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.

The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.

None if wcs is not input.

sky_bbox_lr

The sky coordinates of the lower-right corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.

The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.

None if wcs is not input.

sky_bbox_ul

The sky coordinates of the upper-left corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.

The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.

None if wcs is not input.

sky_bbox_ur

The sky coordinates of the upper-right corner vertex of the minimal bounding box of the source segment, returned as a SkyCoord object.

The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.

None if wcs is not input.

sky_centroid

The sky coordinate of the centroid within the source segment, 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 within the source segment, returned as a SkyCoord object.

None if wcs is not input.

slices

A tuple of slice objects defining the minimal bounding box of the source.

xcentroid

The x coordinate of the centroid within the source segment.

ycentroid

The y coordinate of the centroid within the source segment.

Methods Documentation

add_extra_property(name, value, overwrite=False)

Add a user-defined extra property as a new attribute.

For example, the property name can then be included in the to_table columns keyword list to output the results in the table.

The complete list of user-defined extra properties is stored in the extra_properties attribute.

Parameters

namestr

The name of property. The name must not conflict with any of the built-in property names or attributes.

valuearray-like or float

The value to assign.

overwritebool, option

If True, will overwrite the existing property name.

circular_aperture(radius)

Deprecated since version 1.3: The circular_aperture function is deprecated and may be removed in a future version. Use make_circular_apertures instead.

Return a list of circular apertures with the specified radius centered at the source centroid position.

Parameters

radiusfloat

The radius of the circle in pixels.

Returns

resultlist of CircularAperture

A list of CircularAperture instances. The aperture will be None where the source centroid position is not finite or where the source is completely masked.

circular_photometry(radius, name=None, overwrite=False)

Perform aperture photometry for each source using a circular aperture of the specified radius centered at the source centroid position.

See the SourceCatalog apermask_method keyword for options to mask neighboring sources.

Parameters

radiusfloat

The radius of the circle in pixels.

namestr or None, optional

The prefix name which will be used to define attribute names for the flux and flux error. The attribute names [name]_flux and [name]_fluxerr will store the photometry results. For example, these names can then be included in the to_table columns keyword list to output the results in the table.

overwritebool, optional

If True, overwrite the attribute name if it exists.

Returns

flux, fluxerrndarray of floats, floats, or Quantity

The aperture fluxes and flux errors. NaN will be returned where the circular aperture is None (e.g., where the source centroid position is not finite).

copy()

Return a deep copy of this SourceCatalog.

fluxfrac_radius(fluxfrac, name=None, overwrite=False)

Calculate the circular radius that encloses the specified fraction of the Kron flux.

To estimate the half-light radius, use fluxfrac = 0.5.

Parameters

fluxfracfloat

The fraction of the Kron flux at which to find the circular radius.

namestr or None, optional

The attribute name which will be assigned to the value of the output array. For example, this name can then be included in the to_table columns keyword list to output the results in the table.

overwritebool, optional

If True, overwrite the attribute name if it exists.

Returns

radius1D ndarray

The circular radius that encloses the specified fraction of the Kron flux. NaN is returned where no solution was found or if the Kron flux is zero.

get_label(label)

Return a new SourceCatalog object for the input label only.

Parameters

labelint

The source label.

Returns

catSourceCatalog

A new SourceCatalog object containing only the source with the input label.

get_labels(labels)

Return a new SourceCatalog object for the input labels only.

Parameters

labelslist, tuple, or ndarray of int

The source label(s).

Returns

catSourceCatalog

A new SourceCatalog object containing only the sources with the input labels.

kron_photometry(kron_params, name=None, overwrite=False)

Perform photometry for each source using an elliptical Kron aperture.

This method can be used to calculate the Kron photometry using different scalings of the Kron radius (kron_radius).

See the SourceCatalog apermask_method keyword for options to mask neighboring sources.

Parameters

kron_paramslist of 2 floats, optional

A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (kron_radius) and the second item represents the minimum circular radius. If the Kron radius times sqrt( semimajor_sigma * semiminor_sigma) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.

namestr or None, optional

The prefix name which will be used to define attribute names for the Kron flux and flux error. The attribute names [name]_flux and [name]_fluxerr will store the photometry results. For example, these names can then be included in the to_table columns keyword list to output the results in the table.

overwritebool, optional

If True, overwrite the attribute name if it exists.

Returns

flux, fluxerrndarray of floats, floats, or Quantity

The aperture fluxes and flux errors. NaN will be returned where the circular aperture is None (e.g., where the source centroid position is not finite).

make_circular_apertures(radius)

Return a list of circular apertures with the specified radius centered at the source centroid position.

If provided, the SourceCatalog detection_cat will be used for the source centroids.

Parameters

radiusfloat

The radius of the circle in pixels.

Returns

resultlist of CircularAperture

A list of CircularAperture instances. The aperture will be None where the source centroid position is not finite or where the source is completely masked.

make_kron_apertures(kron_params)

Return a list of Kron elliptical apertures with the specified scaling and centered at the source centroid position.

If provided, the SourceCatalog detection_cat will be used for the source centroids and elliptical shape parameters.

Parameters

kron_paramslist of 2 floats, optional

A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (kron_radius) and the second item represents the minimum circular radius. If the Kron radius times sqrt( semimajor_sigma * semiminor_sigma) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.

Returns

resultlist of PixelAperture

A list of EllipticalAperture or CircularAperture instances. The aperture will be None where the source centroid position is not finite or where the source is completely masked.

plot_circular_apertures(radius, axes=None, origin=(0, 0), **kwargs)

Plot circular apertures on a matplotlib Axes instance.

The apertures are defined by the specified radius and are centered at the source centroid position.

If provided, the SourceCatalog detection_cat will be used for the source centroids.

Parameters

radiusfloat

The radius of the circle in pixels.

axesmatplotlib.axes.Axes or None, optional

The matplotlib axes on which to plot. If None, then the current Axes instance is used.

originarray_like, optional

The (x, y) position of the origin of the displayed image.

**kwargsdict

Any keyword arguments accepted by matplotlib.patches.Patch.

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.

plot_kron_apertures(kron_params, axes=None, origin=(0, 0), **kwargs)

Plot Kron elliptical apertures on a matplotlib Axes instance.

The apertures are defined by the specified radius and are centered at the source centroid position.

If provided, the SourceCatalog detection_cat will be used for the source centroids and elliptical shape parameters.

Parameters

kron_paramslist of 2 floats, optional

A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (kron_radius) and the second item represents the minimum circular radius. If the Kron radius times sqrt( semimajor_sigma * semiminor_sigma) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.

axesmatplotlib.axes.Axes or None, optional

The matplotlib axes on which to plot. If None, then the current Axes instance is used.

originarray_like, optional

The (x, y) position of the origin of the displayed image.

**kwargsdict

Any keyword arguments accepted by matplotlib.patches.Patch.

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.

remove_extra_properties(names)

Remove user-defined extra properties.

The properties must have been defined using add_extra_property. The complete list of user-defined extra properties is stored in the extra_properties attribute.

Parameters

namelist of str

The names of the properties to remove.

remove_extra_property(name)

Remove a user-defined extra property.

The property must have been defined using add_extra_property. The complete list of user-defined extra properties is stored in the extra_properties attribute.

Parameters

namestr

The name of the property to remove.

rename_extra_property(name, new_name)

Rename a user-defined extra property.

The renamed property will remain at the same index in the extra_properties list.

Parameters

namestr

The old attribute name.

new_namestr

The new attribute name.

to_table(columns=None)

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 SourceCatalog properties or custom properties added using add_extra_property. 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.