SourceProperties¶

class photutils.segmentation.SourceProperties(data, segment_img, label, filtered_data=None, error=None, mask=None, background=None, wcs=None)[source]¶

Bases: object

Class to calculate photometry and morphological properties of a single labeled source.

Parameters:

data : array_like or Quantity: The 2D array from which to calculate the source photometry and properties. If filtered_data is input, then it 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.
segment_img : SegmentationImage or array_like (int): A 2D segmentation image, either as a SegmentationImage object or an ndarray, with the same shape as data where sources are labeled by different positive integer values. A value of zero is reserved for the background.
label : int: The label number of the source whose properties to calculate.
filtered_data : array-like or Quantity, optional: The filtered version of the background-subtracted data from which to calculate the source centroid and morphological properties. The kernel used to perform the filtering should be the same one used in defining the source segments (e.g., see detect_sources()). If None, then the unfiltered data will be used instead. Note that SExtractor’s centroid and morphological parameters are calculated from the filtered “detection” image.
error : array_like or Quantity, optional: The pixel-wise Gaussian 1-sigma errors of the input data. error is assumed to include all sources of error, including the Poisson error of the sources (see calc_total_error) . error must have the same shape as the input data. See the Notes section below for details on the error propagation.
mask : array_like (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.
background : float, array_like, 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. Inputting 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.
wcs : WCS: The WCS transformation to use. If None, then any sky-based properties will be set to None.

Notes

SExtractor’s centroid and morphological parameters are always calculated from the filtered “detection” image. The usual downside of the filtering is the sources will be made more circular than they actually are. If you wish to reproduce SExtractor results, then use the filtered_data input. If filtered_data is None, then the unfiltered data will be used for the source centroid and morphological parameters.

Negative (background-subtracted) data values within the source segment are set to zero when measuring morphological properties based on image moments. This could occur, for example, if the segmentation image was defined from a different image (e.g., different bandpass) or if the background was oversubtracted. Note that source_sum includes the contribution of negative (background-subtracted) data values.

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

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

where \(\Delta F\) is source_sum_err, \(S\) are the non-masked 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_ma and background_cutout_ma properties, which are 2D MaskedArray cutout versions of the input error and background. The mask is True for both pixels outside of the source segment and masked pixels from the mask input.

Attributes Summary

`area`	The area of the source segment in units of pixels**2.
`background_at_centroid`	The value of the `background` at the position of the source centroid.
`background_cutout_ma`	A 2D `MaskedArray` cutout from the input `background`, where the mask is `True` for both pixels outside of the source segment and masked pixels.
`background_mean`	The mean of `background` values within the source segment.
`background_sum`	The sum of `background` values within the source segment.
`bbox`	The bounding box `(ymin, xmin, ymax, xmax)` of the minimal rectangular region containing the source segment.
`centroid`	The `(y, x)` coordinate of the centroid within the source segment.
`coords`	A tuple of `ndarray` containing the `y` and `x` pixel coordinates of the source segment.
`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 `(y, x)` coordinate, relative to the `data_cutout`, of the centroid within the source segment.
`cxx`	SExtractor’s CXX ellipse parameter in units of pixel**(-2).
`cxy`	SExtractor’s CXY ellipse parameter in units of pixel**(-2).
`cyy`	SExtractor’s CYY ellipse parameter in units of pixel**(-2).
`data_cutout`	A 2D cutout from the (background-subtracted) data of the source segment.
`data_cutout_ma`	A 2D `MaskedArray` cutout from the (background-subtracted) data, where the mask is `True` for both pixels outside of the source segment and masked pixels.
`dec_icrs_centroid`	Deprecated since version 0.4.
`eccentricity`	The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.
`ellipticity`	`1` minus the ratio of the lengths of the semimajor and semiminor axes (or `1` 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_cutout_ma`	A 2D `MaskedArray` cutout from the input `error` image, where the mask is `True` for both pixels outside of the source segment and masked pixels.
`icrs_centroid`	Deprecated since version 0.4.
`id`	The source identification number corresponding to the object label in the segmentation image.
`inertia_tensor`	The inertia tensor of the source for the rotation around its center of mass.
`max_value`	The maximum pixel value of the (background-subtracted) data within the source segment.
`maxval_cutout_pos`	The `(y, x)` coordinate, relative to the `data_cutout`, of the maximum pixel value of the (background-subtracted) data.
`maxval_pos`	The `(y, x)` coordinate of the maximum pixel value of the (background-subtracted) data.
`maxval_xpos`	The `x` coordinate of the maximum pixel value of the (background-subtracted) data.
`maxval_ypos`	The `y` coordinate of the maximum pixel value of the (background-subtracted) data.
`min_value`	The minimum pixel value of the (background-subtracted) data within the source segment.
`minval_cutout_pos`	The `(y, x)` coordinate, relative to the `data_cutout`, of the minimum pixel value of the (background-subtracted) data.
`minval_pos`	The `(y, x)` coordinate of the minimum pixel value of the (background-subtracted) data.
`minval_xpos`	The `x` coordinate of the minimum pixel value of the (background-subtracted) data.
`minval_ypos`	The `y` coordinate of the minimum pixel value of the (background-subtracted) data.
`moments`	Spatial moments up to 3rd order of the source.
`moments_central`	Central moments (translation invariant) of the source up to 3rd order.
`orientation`	The angle in radians 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 lines through the centers of the border pixels using a 4-connectivity.
`ra_icrs_centroid`	Deprecated since version 0.4.
`semimajor_axis_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_axis_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 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 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 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 vertex of the minimal bounding box of the source segment, returned as a `SkyCoord` object.
`sky_centroid`	The sky coordinates of the centroid within the source segment, returned as a `SkyCoord` object.
`sky_centroid_icrs`	The sky coordinates, in the International Celestial Reference System (ICRS) frame, of the centroid within the source segment, returned as a `SkyCoord` object.
`source_sum`	The sum of the non-masked (background-subtracted) data values within the source segment.
`source_sum_err`	The uncertainty of `source_sum`, propagated from the input `error` array.
`values`	A `ndarray` of the (background-subtracted) pixel values within the source segment.
`xcentroid`	The `x` coordinate of the centroid within the source segment.
`xmax`	The maximum `x` pixel location of the minimal bounding box (`bbox`) of the source segment.
`xmin`	The minimum `x` pixel location of the minimal bounding box (`bbox`) of the source segment.
`ycentroid`	The `y` coordinate of the centroid within the source segment.
`ymax`	The maximum `y` pixel location of the minimal bounding box (`bbox`) of the source segment.
`ymin`	The minimum `y` pixel location of the minimal bounding box (`bbox`) of the source segment.

Methods Summary

`make_cutout`(data[, masked_array])	Create a (masked) cutout array from the input `data` using the minimal bounding box of the source segment.
`to_table`([columns, exclude_columns])	Create a `QTable` of properties.

Attributes Documentation

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

background_at_centroid¶: The value of the background at the position of the source centroid. Fractional position values are determined using bilinear interpolation.

background_cutout_ma¶: A 2D MaskedArray cutout from the input background, where the mask is True for both pixels outside of the source segment and masked pixels. If background is None, then background_cutout_ma is also None.

background_mean¶: The mean of background values within the source segment.

background_sum¶: The sum of background values within the source segment.

bbox¶: The bounding box (ymin, xmin, ymax, xmax) of the minimal rectangular region containing the source segment.

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

coords¶: A tuple of ndarray containing the y and x pixel coordinates of the source segment. Masked pixels are not included.

covar_sigx2¶

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

Note that this is the same as SExtractor’s X2 parameter.

covar_sigxy¶

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

Note that this is the same as SExtractor’s XY parameter.

covar_sigy2¶

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

Note that this is the same as SExtractor’s Y2 parameter.

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 (y, x) coordinate, relative to the data_cutout, of the centroid within the source segment.

cxx¶

SExtractor’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). SExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

cxy¶

SExtractor’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). SExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

cyy¶

SExtractor’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). SExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).

data_cutout¶: A 2D cutout from the (background-subtracted) data of the source segment.

data_cutout_ma¶: A 2D MaskedArray cutout from the (background-subtracted) data, where the mask is True for both pixels outside of the source segment and masked pixels.

dec_icrs_centroid¶: Deprecated since version 0.4: The dec_icrs_centroid function is deprecated and may be removed in a future version. Use sky_centroid_icrs.dec instead.

The ICRS Declination coordinate (in degrees) of the centroid within the source segment.

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 minus the ratio of the lengths of the semimajor and semiminor axes (or 1 minus the elongation):

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

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

Note that this is the same as SExtractor’s ellipticity parameter.

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.

Note that this is the same as SExtractor’s elongation parameter.

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

error_cutout_ma¶: A 2D MaskedArray cutout from the input error image, where the mask is True for both pixels outside of the source segment and masked pixels. If error is None, then error_cutout_ma is also None.

icrs_centroid¶: Deprecated since version 0.4: The icrs_centroid function is deprecated and may be removed in a future version. Use sky_centroid_icrs instead.

The sky coordinates, in the International Celestial Reference System (ICRS) frame, of the centroid within the source segment, returned as a SkyCoord object.

id¶: The source identification number corresponding to the object label in the segmentation image.

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

max_value¶: The maximum pixel value of the (background-subtracted) data within the source segment.

maxval_cutout_pos¶: The (y, x) coordinate, relative to the data_cutout, of the maximum pixel value of the (background-subtracted) data.

maxval_pos¶: The (y, x) coordinate of the maximum pixel value of the (background-subtracted) data.

maxval_xpos¶: The x coordinate of the maximum pixel value of the (background-subtracted) data.

maxval_ypos¶: The y coordinate of the maximum pixel value of the (background-subtracted) data.

min_value¶: The minimum pixel value of the (background-subtracted) data within the source segment.

minval_cutout_pos¶: The (y, x) coordinate, relative to the data_cutout, of the minimum pixel value of the (background-subtracted) data.

minval_pos¶: The (y, x) coordinate of the minimum pixel value of the (background-subtracted) data.

minval_xpos¶: The x coordinate of the minimum pixel value of the (background-subtracted) data.

minval_ypos¶: The y coordinate of the minimum pixel value of the (background-subtracted) data.

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

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

orientation¶: The angle in radians 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 lines through the centers of the border pixels using a 4-connectivity.

ra_icrs_centroid¶: Deprecated since version 0.4: The ra_icrs_centroid function is deprecated and may be removed in a future version. Use sky_centroid_icrs.ra instead.

The ICRS Right Ascension coordinate (in degrees) of the centroid within the source segment.

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

sky_bbox_lr¶

The sky coordinates of the lower-right 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.

sky_bbox_ul¶

The sky coordinates of the upper-left 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.

sky_bbox_ur¶

The sky coordinates of the upper-right 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.

sky_centroid¶

The sky coordinates of the centroid within the source segment, returned as a SkyCoord object.

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

sky_centroid_icrs¶: The sky coordinates, in the International Celestial Reference System (ICRS) frame, of the centroid within the source segment, returned as a SkyCoord object.

source_sum¶

The sum of the non-masked (background-subtracted) data values within the source segment.

\[F = \sum_{i \in S} (I_i - B_i)\]

where \(F\) is source_sum, \((I_i - B_i)\) is the background-subtracted input data, and \(S\) are the non-masked pixels in the source segment.

source_sum_err¶

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

source_sum_err is the quadrature sum of the total errors over the non-masked pixels within the source segment:

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

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

values¶: A ndarray of the (background-subtracted) pixel values within the source segment. Masked pixels are not included.

xcentroid¶: The x coordinate of the centroid within the source segment.

xmax¶: The maximum x pixel location of the minimal bounding box (bbox) of the source segment.

xmin¶: The minimum x pixel location of the minimal bounding box (bbox) of the source segment.

ycentroid¶: The y coordinate of the centroid within the source segment.

ymax¶: The maximum y pixel location of the minimal bounding box (bbox) of the source segment.

ymin¶: The minimum y pixel location of the minimal bounding box (bbox) of the source segment.

Methods Documentation

make_cutout(data, masked_array=False)[source]¶

Create a (masked) cutout array from the input data using the minimal bounding box of the source segment.

Parameters:

data : array-like (2D): The data array from which to create the masked cutout array. data must have the same shape as the segmentation image input into SourceProperties.
masked_array : bool, optional: If True then a MaskedArray will be created where the mask is True for both pixels outside of the source segment and any masked pixels. If False, then a ndarray will be generated.

Returns:

result : ndarray or MaskedArray (2D): The 2D cutout array or masked array.

to_table(columns=None, exclude_columns=None)[source]¶

Create a QTable of properties.

If columns or exclude_columns are not input, then the QTable will include all scalar-valued properties. Multi-dimensional properties, e.g. data_cutout, can be included in the columns input.

Parameters:	columns : str or list of str, optional Names of columns, in order, to include in the output `QTable`. The allowed column names are any of the attributes of `SourceProperties`. exclude_columns : str or list of str, optional Names of columns to exclude from the default properties list in the output `QTable`. The default properties are those with scalar values.
Returns:	table : `QTable` A single-row table of properties of the source.

Navigation

SourceProperties¶