SourceCatalog#

class photutils.segmentation.SourceCatalog(data, segmentation_image, *, convolved_data=None, error=None, mask=None, background=None, wcs=None, local_bkg_width=0, aperture_mask_method='correct', kron_params=(2.5, 1.4, 0.0), detection_catalog=None, progress_bar=False)[source]#

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

segmentation_imageSegmentationImage

A SegmentationImage object defining the sources.

convolved_data2D ndarray or Quantity, optional

The 2D array used to calculate the source centroid and morphological properties. Typically, convolved_data should be the input data array convolved by the same smoothing kernel that was applied to the detection image when deriving the source segments (e.g., see detect_sources()). If convolved_data is 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.

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. This keyword will be ignored if detection_catalog is input.

local_bkg_widthint, optional

The width of the rectangular annulus used to compute a local background around each source. If zero, then no local background subtraction is performed. The local background affects the min_value, max_value, segment_flux, kron_flux, and flux_radius properties. It is also used when calculating circular and Kron aperture photometry (i.e., circular_photometry and kron_photometry). It does not affect the moment-based morphological properties of the source.

aperture_mask_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. The options are:

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

This keyword will be ignored if detection_catalog is input. In that case, the aperture_mask_method set in the detection_catalog will be used.

kron_paramstuple of 2 or 3 floats, optional

A list of parameters used to determine the Kron aperture. The first item is the scaling parameter of the unscaled Kron radius and the second item represents the minimum value for the unscaled Kron radius in pixels. The optional third item is the minimum circular radius in pixels. If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to this radius, then the Kron aperture will be a circle with this minimum radius. This keyword will be ignored if detection_catalog is input.

detection_catalogSourceCatalog, optional

A SourceCatalog object for the detection image. The segmentation image used to create the detection catalog must be the same one input to segmentation_image. If input, then the detection catalog source centroids and morphological/shape properties will be returned instead of calculating them from the input data. The detection catalog centroids and shape properties will also be used to perform aperture photometry (i.e., circular and Kron). If detection_catalog is input, then the input wcs, aperture_mask_method, and kron_params keywords will be ignored. This keyword affects circular_photometry (including returned apertures), all Kron parameters (Kron radius, flux, flux errors, apertures, and custom kron_photometry), and flux_radius (which is based on the Kron flux).

progress_barbool, optional

Whether to display a progress bar when calculating some properties (e.g., kron_radius, kron_flux, flux_radius, circular_photometry, centroid_win, centroid_quad). The progress bar requires that the tqdm optional dependency be installed.

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.

Note that this class does not convert input data in surface-brightness units to flux or counts. Conversion from surface-brightness units should be performed before using this class.

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. If convolved_data is 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_flux_err 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_flux_err, \(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_cutout_masked and background_cutout_masked properties, which are 2D MaskedArray cutout versions of the input error and background arrays. The mask is True for pixels outside the source segment, masked pixels from the mask input, or any non-finite data values (NaN and inf).

Scalar vs. Multi-source Catalogs

A SourceCatalog can represent a single source or multiple sources. Most properties adapt their return type accordingly: for a multi-source catalog, properties return arrays or lists (one element per source); for a single-source (scalar) catalog, the same properties return a scalar value or a single object. For example, kron_aperture returns a list of aperture objects for a multi-source catalog, but a single aperture object for a scalar catalog. Similarly, data_cutout returns a list of 2D cutout arrays for a multi-source catalog, but a single 2D array for a scalar catalog. A scalar catalog is created when the a multi-source catalog is indexed to select a single source.

Attributes Summary

`area`	The total unmasked area of the source in units of pixels**2.
`background_centroid`	The value of the per-pixel `background` at the position of the isophotal (center-of-mass) `centroid`.
`background_cutout`	A 2D `ndarray` cutout from the background array using the minimal bounding box of the source.
`background_cutout_masked`	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 isophotal source segment.
`centroid_quad`	The `(x, y)` centroid coordinate, calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.
`centroid_win`	The `(x, y)` coordinate of the "windowed" centroid.
`conv_data_cutout`	A 2D `ndarray` cutout from the convolved data using the minimal bounding box of the source.
`conv_data_cutout_masked`	A 2D `MaskedArray` cutout from the convolved data using the minimal bounding box of the source.
`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.
`custom_properties`	A list of the user-defined source properties.
`cutout_centroid`	The `(x, y)` coordinate, relative to the cutout data, of the centroid within the isophotal source segment.
`cutout_centroid_quad`	The `(x, y)` centroid coordinate, relative to the cutout data, calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.
`cutout_centroid_win`	The `(x, y)` coordinate, relative to the cutout data, of the "windowed" centroid.
`cutout_max_value_index`	The `(y, x)` coordinate, relative to the cutout data, of the maximum pixel value of the `data` within the source segment.
`cutout_min_value_index`	The `(y, x)` coordinate, relative to the cutout data, of the minimum pixel value of the `data` within the source segment.
`data_cutout`	A 2D `ndarray` cutout from the data using the minimal bounding box of the source.
`data_cutout_masked`	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.
`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.
`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_cutout`	A 2D `ndarray` cutout from the error array using the minimal bounding box of the source.
`error_cutout_masked`	A 2D `MaskedArray` cutout from the error array using the minimal bounding box of the source.
`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 (or circular) Kron aperture.
`kron_flux`	The flux in the Kron aperture.
`kron_flux_err`	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 (per pixel) 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.
`max_value_index`	The `(y, x)` coordinate of the maximum pixel value of the `data` within the source segment.
`max_value_xindex`	The `x` coordinate of the maximum pixel value of the `data` within the source segment.
`max_value_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.
`min_value_index`	The `(y, x)` coordinate of the minimum pixel value of the `data` within the source segment.
`min_value_xindex`	The `x` coordinate of the minimum pixel value of the `data` within the source segment.
`min_value_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.
`n_labels`	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_area`	The total area of the source segment in units of pixels**2.
`segment_cutout`	A 2D `ndarray` cutout of the segmentation image using the minimal bounding box of the source.
`segment_cutout_masked`	A 2D `MaskedArray` 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_flux_err`	The uncertainty of `segment_flux`, propagated from the input `error` array.
`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_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.
`sky_centroid_quad`	The sky coordinate of the centroid (`centroid_quad`), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.
`sky_centroid_win`	The sky coordinate of the "windowed" centroid (`centroid_win`) within the source segment, returned as a `SkyCoord` object.
`slices`	A tuple of slice objects defining the minimal bounding box of the source.
`x_centroid`	The `x` coordinate of the `centroid` within the source segment.
`x_centroid_quad`	The `x` coordinate of the centroid (`centroid_quad`), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.
`x_centroid_win`	The `x` coordinate of the "windowed" centroid (`centroid_win`).
`y_centroid`	The `y` coordinate of the `centroid` within the source segment.
`y_centroid_quad`	The `y` coordinate of the centroid (`centroid_quad`), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.
`y_centroid_win`	The `y` coordinate of the "windowed" centroid (`centroid_win`).

Methods Summary

`add_property`(name, value[, overwrite])	Add a user-defined property as a new attribute.
`circular_photometry`(radius[, name, overwrite])	Perform circular aperture photometry for each source.
`copy`()	Return a deep copy of this SourceCatalog.
`flux_radius`(fraction[, name, overwrite])	Calculate the circular radius that encloses the specified fraction of the Kron flux.
`kron_photometry`(kron_params[, name, overwrite])	Perform photometry for each source using an elliptical Kron aperture.
`make_circular_apertures`(radius)	Make circular aperture for each source.
`make_cutouts`(shape, *[, array, mode, fill_value])	Make cutout arrays for each source.
`make_kron_apertures`([kron_params])	Make Kron apertures for each source.
`plot_circular_apertures`(radius[, ax, origin])	Plot circular apertures for each source on a matplotlib `Axes` instance.
`plot_kron_apertures`([kron_params, ax, origin])	Plot Kron apertures for each source on a matplotlib `Axes` instance.
`remove_properties`(names)	Remove user-defined properties.
`remove_property`(name)	Remove a user-defined property.
`rename_property`(name, new_name)	Rename a user-defined property.
`select_label`(label)	Return a new `SourceCatalog` object for the input `label` only.
`select_labels`(labels)	Return a new `SourceCatalog` object for the input `labels` only.
`to_table`([columns])	Create a `QTable` of source properties.

Attributes Documentation

area#

The total unmasked area of the source 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_centroid#

The value of the per-pixel background at the position of the isophotal (center-of-mass) centroid.

If detection_catalog is input, then its centroid will be used.

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

background_cutout#

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

background_cutout_masked#

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

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

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.

Returns a list for multi-source catalogs, or a single BoundingBox for a single-source catalog.

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 isophotal source segment.

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

centroid_quad#

The (x, y) centroid coordinate, calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.

Notes

centroid_quadratic is used to calculate the centroid with fit_boxsize=3.

Because this centroid is based on fitting data, it can fail for many reasons, returning (np.nan, np.nan):

quadratic fit failed
quadratic fit does not have a maximum
quadratic fit maximum falls outside image
not enough unmasked data points (6 are required)

Also note that a fit is not performed if the maximum data value is at the edge of the source segment. In this case, the position of the maximum pixel will be returned.

centroid_win#

The (x, y) coordinate of the “windowed” centroid.

The window centroid is computed using an iterative algorithm to derive a more accurate centroid. It is equivalent to SourceExtractor’s XWIN_IMAGE and YWIN_IMAGE parameters.

Notes

During each iteration, the centroid is calculated using all pixels within a circular aperture of 4 * sigma from the current position, weighting pixel values with a 2D Gaussian with a standard deviation of sigma. sigma is the half-light radius (i.e., flux_radius(0.5)) times (2.0 / 2.35). A minimum half-light radius of 0.5 pixels is used. Iteration stops when the change in centroid position falls below a pre-defined threshold or a maximum number of iterations is reached.

If the windowed centroid falls outside the 1-sigma ellipse shape based on the image moments, then the isophotal centroid will be used instead. If the half-light radius is not finite (e.g., due to a non-finite Kron radius), then np.nan will be returned.

conv_data_cutout#

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

conv_data_cutout_masked#

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

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

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.

custom_properties#: A list of the user-defined source properties.

cutout_centroid#

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

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

cutout_centroid_quad#

The (x, y) centroid coordinate, relative to the cutout data, calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.

Notes

centroid_quadratic is used to calculate the centroid with fit_boxsize=3.

Because this centroid is based on fitting data, it can fail for many reasons including:

quadratic fit failed
quadratic fit does not have a maximum
quadratic fit maximum falls outside image
not enough unmasked data points (6 are required)

In these cases, then the isophotal centroid will be used instead.

Also note that a fit is not performed if the maximum data value is at the edge of the source segment. In this case, the position of the maximum pixel will be returned.

cutout_centroid_win#

The (x, y) coordinate, relative to the cutout data, of the “windowed” centroid.

The window centroid is computed using an iterative algorithm to derive a more accurate centroid. It is equivalent to SourceExtractor’s XWIN_IMAGE and YWIN_IMAGE parameters. See centroid_win for further details about the algorithm.

cutout_max_value_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_min_value_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.

data_cutout#

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

data_cutout_masked#

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

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

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.

\[\mathrm{ellipticity} = \frac{a - b}{a} = 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_cutout#

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

error_cutout_masked#

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

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

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

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.

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 (or circular) Kron aperture.

The Kron aperture is calculated for each source using its shape parameters, kron_radius, and the kron_params scaling and minimum values input into SourceCatalog. The Kron aperture is used to compute the Kron photometry.

If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to the minimum circular radius (kron_params[2]), then the Kron aperture will be a circle with this minimum radius.

The aperture will be None where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked.

If a detection_catalog was input to SourceCatalog, then its kron_aperture will be returned.

Returns a list of apertures for multi-source catalogs, or a single aperture for a single-source catalog.

kron_flux#

The flux in the Kron aperture.

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

If the Kron aperture is None, then np.nan will be returned. This will occur where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked.

kron_flux_err#

The flux error in the Kron aperture.

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

If the Kron aperture is None, then np.nan will be returned. This will occur where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked.

kron_radius#

The unscaled first-moment Kron radius.

The unscaled first-moment Kron radius is given by:

\[r_k = \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_axis) and semiminor axes (semiminor_axis) 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 (ellipse_cxx, ellipse_cxy, and ellipse_cyy).

The kron_radius value is the unscaled moment value. The minimum unscaled radius can be set using the second element of the SourceCatalog kron_params keyword. If the measured unscaled Kron radius exceeds 6.0 (the measurement aperture scale factor), np.nan will be returned. Such values are unphysical, typically caused by near-cancellation in the denominator of the Kron formula due to outlier pixels or noise.

If either the numerator or denominator above is less than or equal to 0, then the minimum unscaled Kron radius (kron_params[1]) will be used.

The Kron aperture is calculated for each source using its shape parameters, kron_radius, and the kron_params scaling and minimum values input into SourceCatalog. The Kron aperture is used to compute the Kron photometry.

If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to the minimum circular radius (kron_params[2]), then the Kron radius will be set to zero and the Kron aperture will be a circle with this minimum radius.

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

If a detection_catalog was input to SourceCatalog, then its kron_radius will be returned.

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

label#

The source label number(s).

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

Returns an array for multi-source catalogs, or a scalar for a single-source catalog.

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 (per pixel) estimated using a rectangular annulus aperture around the source.

local_background_aperture#

The RectangularAnnulus aperture used to estimate the local background.

Returns a list of apertures for multi-source catalogs, or a single aperture for a single-source catalog.

max_value#: The maximum pixel value of the data within the source segment.

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

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

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

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

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

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

n_labels#: 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 and will be in the range [0, 360) degrees.

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

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

segment_area#

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

This area is simply the area of the source segment from the input segmentation_image. It does not take into account any data masking (i.e., a mask input to SourceCatalog or invalid data values).

segment_cutout#

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

segment_cutout_masked#

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

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

Returns a list of arrays for multi-source catalogs, or a single array for a single-source catalog.

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_flux_err#

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

segment_flux_err 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_err, \(\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.

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

sky_centroid_quad#

The sky coordinate of the centroid (centroid_quad), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.

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

None if wcs is not input.

sky_centroid_win#

The sky coordinate of the “windowed” centroid (centroid_win) 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.

slices#

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

Returns a list for multi-source catalogs, or a single tuple for a single-source catalog.

x_centroid#

The x coordinate of the centroid within the source segment.

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

x_centroid_quad#: The x coordinate of the centroid (centroid_quad), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.

x_centroid_win#

The x coordinate of the “windowed” centroid (centroid_win).

The window centroid is computed using an iterative algorithm to derive a more accurate centroid. It is equivalent to SourceExtractor’s XWIN_IMAGE parameters.

y_centroid#

The y coordinate of the centroid within the source segment.

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

y_centroid_quad#: The y coordinate of the centroid (centroid_quad), calculated by fitting a 2D quadratic polynomial to the unmasked pixels in the source segment.

y_centroid_win#

The y coordinate of the “windowed” centroid (centroid_win).

The window centroid is computed using an iterative algorithm to derive a more accurate centroid. It is equivalent to SourceExtractor’s YWIN_IMAGE parameters.

Methods Documentation

add_property(name, value, overwrite=False)[source]#

Add a user-defined 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 properties is stored in the custom_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_photometry(radius, name=None, overwrite=False)[source]#

Perform circular aperture photometry for each source.

The circular aperture for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

See the SourceCatalog aperture_mask_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]_flux_err 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, flux_errfloat or ndarray of floats: The aperture fluxes and flux errors. NaN will be returned where the aperture is None (e.g., where the source centroid position is not finite or the source is completely masked).

copy()[source]#

Return a deep copy of this SourceCatalog.

Returns:

resultSourceCatalog: A deep copy of this object.

flux_radius(fraction, name=None, overwrite=False)[source]#

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

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

Parameters:

fractionfloat: 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 where the Kron flux is zero or non-finite.

kron_photometry(kron_params, name=None, overwrite=False)[source]#

Perform photometry for each source using an elliptical Kron aperture.

This method can be used to calculate the Kron photometry using alternate kron_params (e.g., different scalings of the Kron radius).

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

Parameters:

kron_paramslist of 2 or 3 floats, optional: A list of parameters used to determine the Kron aperture. The first item is the scaling parameter of the unscaled Kron radius and the second item represents the minimum value for the unscaled Kron radius in pixels. The optional third item is the minimum circular radius in pixels. If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to this radius, then the Kron aperture will be 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]_flux_err 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, flux_errfloat or ndarray of floats: The aperture fluxes and flux errors. NaN will be returned where the aperture is None (e.g., where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked).

make_circular_apertures(radius)[source]#

Make circular aperture for each source.

The aperture for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

Parameters:

radiusfloat: The radius of the circle in pixels.

Returns:

resultCircularAperture or list of CircularAperture: The circular aperture for each source. The aperture will be None where the source centroid position is not finite or where the source is completely masked.

make_cutouts(shape, *, array=None, mode='partial', fill_value=nan)[source]#

Make cutout arrays for each source.

The cutout for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

Parameters:

shape2-tuple: The cutout shape along each axis in (ny, nx) order.
arrayNone or 2D ndarray: A 2D array with the same shape as the data array input to SourceCatalog. If None then the data array will be used. If any cutout arrays are not fully contained within the array array and mode='partial' with fill_value=np.nan, then the input array must have a float data type.
mode{‘partial’, ‘trim’}, optional: The mode used for extracting the cutout array. In 'partial' mode, positions in the cutout array that do not overlap with the large array will be filled with fill_value. In 'trim' mode, only the overlapping elements are returned, thus the resulting small array may be smaller than the requested shape.
fill_valuenumber, optional: If mode='partial', the value to fill pixels in the extracted cutout array that do not overlap with the input array_large. fill_value will be changed to have the same dtype as the array_large array, with one exception. If array_large has integer type and fill_value is np.nan, then a ValueError will be raised.

Returns:

cutoutsCutoutImage or list of CutoutImage: The CutoutImage for each source. The cutout will be None where the source centroid position is not finite or where the source is completely masked.

make_kron_apertures(kron_params=None)[source]#

Make Kron apertures for each source.

The aperture for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

Note that changing kron_params from the values input into SourceCatalog does not change the Kron apertures (kron_aperture) and photometry (kron_flux and kron_flux_err) in the source catalog. This method should be used only to explore alternative kron_params with a detection image.

Parameters:

kron_paramslist of 2 or 3 floats or None, optional: A list of parameters used to determine the Kron aperture. The first item is the scaling parameter of the unscaled Kron radius and the second item represents the minimum value for the unscaled Kron radius in pixels. The optional third item is the minimum circular radius in pixels. If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to this radius, then the Kron aperture will be a circle with this minimum radius. If None, then the kron_params input into SourceCatalog will be used (the apertures will be the same as those in kron_aperture).

Returns:

resultPixelAperture or list of PixelAperture: The Kron apertures for each source. Each aperture will either be a EllipticalAperture, CircularAperture, or None. The aperture will be None where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked.

plot_circular_apertures(radius, ax=None, origin=(0, 0), **kwargs)[source]#

Plot circular apertures for each source on a matplotlib Axes instance.

The aperture for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

An aperture will not be plotted for sources where the source centroid position is not finite or where the source is completely masked.

Parameters:

radiusfloat: The radius of the circle in pixels.
axmatplotlib.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, optional: Any keyword arguments accepted by matplotlib.patches.Patch.

Returns:

patchPatch or list of Patch: The matplotlib patch for each plotted aperture. The patches can be used, for example, when adding a plot legend.

plot_kron_apertures(kron_params=None, ax=None, origin=(0, 0), **kwargs)[source]#

Plot Kron apertures for each source on a matplotlib Axes instance.

The aperture for each source will be centered at its centroid position. If a detection_catalog was input to SourceCatalog, then its centroid values will be used.

An aperture will not be plotted for sources where the source centroid position or elliptical shape parameters are not finite or where the source is completely masked.

Note that changing kron_params from the values input into SourceCatalog does not change the Kron apertures (kron_aperture) and photometry (kron_flux and kron_flux_err) in the source catalog. This method should be used only to visualize/explore alternative kron_params with a detection image.

Parameters:

kron_paramslist of 2 or 3 floats or None, optional: A list of parameters used to determine the Kron aperture. The first item is the scaling parameter of the unscaled Kron radius and the second item represents the minimum value for the unscaled Kron radius in pixels. The optional third item is the minimum circular radius in pixels. If kron_params[0] * kron_radius * sqrt(semimajor_axis * semiminor_axis) is less than or equal to this radius, then the Kron aperture will be a circle with this minimum radius. If None, then the kron_params input into SourceCatalog will be used (the apertures will be the same as those in kron_aperture).
axmatplotlib.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, optional: 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_properties(names)[source]#

Remove user-defined properties.

The properties must have been defined using add_property. The complete list of user-defined properties is stored in the custom_properties attribute.

Parameters:

nameslist of str or str: The names of the properties to remove.

remove_property(name)[source]#

Remove a user-defined property.

The property must have been defined using add_property. The complete list of user-defined properties is stored in the custom_properties attribute.

Parameters:

namestr: The name of the property to remove.

rename_property(name, new_name)[source]#

Rename a user-defined property.

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

Parameters:

namestr: The old attribute name.
new_namestr: The new attribute name.

select_label(label)[source]#

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.

select_labels(labels)[source]#

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.

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