SourceProperties

class photutils.segmentation.SourceProperties(data, segment_img, label, filtered_data=None, error=None, mask=None, background=None, wcs=None, localbkg_width=None, kron_params='mask', 2.5, 0.0, 'exact', 5)[source]

Bases: object

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

Parameters
dataarray_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. Non-finite data values (NaN and +/- inf) are automatically masked.

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

labelint

The label number of the source whose properties are calculated.

filtered_dataarray-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 data is a Quantity array then filtered_data must be a Quantity array (and vise versa) with identical units. Non-finite filtered_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. If None, then the unfiltered data will be used instead.

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

maskarray_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. Non-finite values (NaN and +/- inf) in the input data are automatically masked.

backgroundfloat, 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. If data is a Quantity array then background must be a Quantity array (and vise versa) with identical units. 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. Non-finite background values (NaN and +/- inf) are not automatically masked, unless they are at the same position of non-finite values in the input data array. Such pixels can be masked using the mask keyword.

wcsWCS object or None, optional

A world coordinate system (WCS) transformation that supports the astropy shared interface for WCS (e.g., astropy.wcs.WCS, gwcs.wcs.WCS). If None, then all sky-based properties will be set to None.

localbkg_widthNone or positive int, optional

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

kron_paramstuple of list, optional

A list of five parameters used to determine how the Kron radius and flux are calculated. The first item represents how data pixels are masked around the source. It must be one of:

  • ‘none’: do not mask any pixels (equivalent to

    MASK_TYPE=NONE in SourceExtractor).

  • ‘mask’: mask pixels assigned to neighboring sources

    (equivalent to MASK_TYPE=BLANK in SourceExtractor)

  • ‘mask_all’: mask all pixels outside of the source segment.

  • ‘correct’: replace pixels assigned to neighboring sources

    by replacing them with pixels on the opposite side of the source (equivalent to MASK_TYPE=CORRECT in SourceExtractor).

The second item represents the scaling parameter of the Kron radius as a scalar float. The third item represents the minimum circular radius as a scalar float. If the Kron radius times sqrt(semimajor_axis_sigma * semiminor_axis_sigma) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius. The forth and fifth items represent the aperture_photometry() keywords method and subpixels, respectively, which are used to measure the flux in the Kron aperture.

Notes

data (and optional filtered_data) should be background-subtracted for accurate source photometry and properties.

SExtractor’s centroid and morphological parameters are always calculated from a filtered “detection” image, 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 SExtractor centroid and morphology results, then input a filtered and background-subtracted “detection” image into the filtered_data keyword. If filtered_data is None, then the unfiltered data will be used for the source centroid and morphological parameters.

Negative data values (filtered_data or data) 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. Note that source_sum 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. 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 pixels outside of the source segment, masked pixels from the mask input, or any non-finite data values (NaN and +/- inf).

Attributes Summary

area

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

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

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 location within the minimal bounding box containing the source segment.

bbox_xmin

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

bbox_ymax

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

bbox_ymin

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

centroid

The (y, x) coordinate of the centroid within 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 ndarray cutout from the data using the minimal bounding box of the source segment.

data_cutout_ma

A 2D MaskedArray cutout from the data.

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.

filtered_data_cutout_ma

A 2D MaskedArray cutout from the filtered_data.

gini

The Gini coefficient of the source.

id

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

indices

A tuple of two ndarray containing the y and x pixel indices, respectively, of unmasked pixels within the source segment.

inertia_tensor

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

kron_aperture

The Kron aperture.

kron_flux

The flux in the Kron aperture.

kron_fluxerr

The flux error in the Kron aperture.

kron_radius

The unscaled first-moment Kron radius.

local_background

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

local_background_aperture

The rectangular annulus aperture used to estimate the local background.

max_value

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

maxval_cutout_pos

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

maxval_pos

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

maxval_xpos

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

maxval_ypos

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

min_value

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

minval_cutout_pos

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

minval_pos

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

minval_xpos

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

minval_ypos

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.

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.

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 unmasked data values within the source segment.

source_sum_err

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

xcentroid

The x coordinate of the centroid within the source segment.

ycentroid

The y coordinate of the centroid within 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 total unmasked area of the source segment in units of pixels**2.

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

background_at_centroid

The value of the background at the position of the source centroid.

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

background_cutout_ma

A 2D MaskedArray cutout from the input background.

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

If background is None, then background_cutout_ma is also None.

background_mean

The mean of background values within the source segment.

Pixel values that are masked in the input data, including any non-finite pixel values (NaN and +/- inf) that are automatically masked, are also masked in the background array.

background_sum

The sum of background values within the source segment.

Pixel values that are masked in the input data, including any non-finite pixel values (NaN and +/- inf) that are automatically masked, are also masked in the background array.

bbox

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

bbox_xmax

The maximum x pixel location 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 location within the minimal bounding box containing the source segment.

bbox_ymax

The maximum y pixel location 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 location within the minimal bounding box containing the source segment.

centroid

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

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 ndarray cutout from the data using the minimal bounding box of the source segment.

data_cutout_ma

A 2D MaskedArray cutout from the data.

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

eccentricity

The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.

The eccentricity is the fraction of the distance along the semimajor axis at which the focus lies.

\[e = \sqrt{1 - \frac{b^2}{a^2}}\]

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

ellipticity

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

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

If error is None, then error_cutout_ma is also None.

filtered_data_cutout_ma

A 2D MaskedArray cutout from the filtered_data.

If filtered_data was not input, then the cutout will be from the input data.

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

gini

The Gini coefficient of the source.

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

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

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

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

id

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

indices

A tuple of two ndarray containing the y and x pixel indices, respectively, of unmasked pixels within the source segment.

Non-finite data values (NaN and +/- inf) are excluded.

If all data pixels are masked, a tuple of two empty arrays will be returned.

inertia_tensor

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

kron_aperture

The Kron aperture.

kron_flux

The flux in the Kron aperture.

kron_fluxerr

The flux error in the Kron aperture.

kron_radius

The unscaled first-moment Kron radius.

The unscaled first-moment Kron radius is given by:

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

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

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

where \(\bar{x}\) and \(\bar{y}\) represent the source centroid.

local_background

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

local_background_aperture

The rectangular annulus aperture used to estimate the local background.

max_value

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

maxval_cutout_pos

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

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

maxval_pos

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 occurence is returned.

maxval_xpos

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 occurence is returned.

maxval_ypos

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 occurence is returned.

min_value

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

minval_cutout_pos

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

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

minval_pos

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 occurence is returned.

minval_xpos

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 occurence is returned.

minval_ypos

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

orientation

The angle between the x axis and the major axis of the 2D Gaussian function that has the same second-order moments as the source. The angle increases in the counter-clockwise direction.

perimeter

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

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

References

1

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

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 unmasked 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 data, and \(S\) are the unmasked pixels in the source segment.

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

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.

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.

xcentroid

The x coordinate of the centroid within the source segment.

ycentroid

The y coordinate of the centroid within 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.

If masked_array is False (default), then the returned cutout array is simply a ndarray. The returned cutout is a view (not a copy) of the input data. No pixels are altered (e.g., set to zero) within the bounding box.

If masked_array` is `True`, then the returned cutout array is a `~numpy.ma.MaskedArray`.  The mask is `True` for pixels outside of the source segment (labeled region of interest), masked pixels from the ``mask input, or any non-finite data values (NaN and +/- inf). The data part of the masked array is a view (not a copy) of the input data.

Parameters
dataarray-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_arraybool, optional

If True then a MaskedArray will be returned, where the mask is True for pixels outside of the source segment (labeled region of interest), masked pixels from the mask input, or any non-finite data values (NaN and +/- inf). If False, then a ndarray will be returned.

Returns
result2D ndarray or MaskedArray

The 2D cutout 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 a default list of scalar-valued properties.

Parameters
columnsstr 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_columnsstr or list of str, optional

Names of columns to exclude from the default columns in the output QTable. The default columns are defined in the photutils.segmentation.properties.DEFAULT_COLUMNS variable.

Returns
tableQTable

A single-row table of properties of the source.