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