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 ofdata
to calculate the source centroid and morphological properties. Source photometry is always measured fromdata
. For accurate source properties and photometry,data
should be backgroundsubtracted.segment_img :
SegmentationImage
or array_like (int)A 2D segmentation image, either as a
SegmentationImage
object or anndarray
, with the same shape asdata
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 : arraylike or
Quantity
, optionalThe filtered version of the backgroundsubtracted
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., seedetect_sources()
). IfNone
, then the unfiltereddata
will be used instead. Note that SExtractor’s centroid and morphological parameters are calculated from the filtered “detection” image.error : array_like or
Quantity
, optionalThe pixelwise Gaussian 1sigma errors of the input
data
.error
is assumed to include all sources of error, including the Poisson error of the sources (seecalc_total_error
) .error
must have the same shape as the inputdata
. 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 aTrue
value indicates the corresponding element ofdata
is masked. Masked data are excluded from all calculations.background : float, array_like, or
Quantity
, optionalThe 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 inputdata
. Inputting thebackground
merely allows for its properties to be measured within each source segment. The inputbackground
does not get subtracted from the inputdata
, which should already be backgroundsubtracted.wcs :
WCS
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. Iffiltered_data
isNone
, then the unfiltereddata
will be used for the source centroid and morphological parameters.Negative (backgroundsubtracted) 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 (backgroundsubtracted) 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 pixelwise total errors over the nonmasked 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 nonmasked pixels in the source segment, and \(\sigma_{\mathrm{tot}, i}\) is the inputerror
array.Custom errors for source segments can be calculated using the
error_cutout_ma
andbackground_cutout_ma
properties, which are 2DMaskedArray
cutout versions of the inputerror
andbackground
. The mask isTrue
for both pixels outside of the source segment and masked pixels from themask
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 inputbackground
, where the mask isTrue
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 they
andx
pixel coordinates of the source segment.covar_sigx2
The (0, 0)
element of thecovariance
matrix, representing \(\sigma_x^2\), in units of pixel**2.covar_sigxy
The (0, 1)
and(1, 0)
elements of thecovariance
matrix, representing \(\sigma_x \sigma_y\), in units of pixel**2.covar_sigy2
The (1, 1)
element of thecovariance
matrix, representing \(\sigma_y^2\), in units of pixel**2.covariance
The covariance matrix of the 2D Gaussian function that has the same secondorder moments as the source. covariance_eigvals
The two eigenvalues of the covariance
matrix in decreasing order.cutout_centroid
The (y, x)
coordinate, relative to thedata_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 (backgroundsubtracted) data of the source segment. data_cutout_ma
A 2D MaskedArray
cutout from the (backgroundsubtracted) data, where the mask isTrue
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 secondorder moments as the source. ellipticity
1
minus the ratio of the lengths of the semimajor andelongation
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 inputerror
image, where the mask isTrue
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 (backgroundsubtracted) data within the source segment. maxval_cutout_pos
The (y, x)
coordinate, relative to thedata_cutout
, of the maximum pixel value of the (backgroundsubtracted) data.maxval_pos
The (y, x)
coordinate of the maximum pixel value of the (backgroundsubtracted) data.maxval_xpos
The x
coordinate of the maximum pixel value of the (backgroundsubtracted) data.maxval_ypos
The y
coordinate of the maximum pixel value of the (backgroundsubtracted) data.min_value
The minimum pixel value of the (backgroundsubtracted) data within the source segment. minval_cutout_pos
The (y, x)
coordinate, relative to thedata_cutout
, of the minimum pixel value of the (backgroundsubtracted) data.minval_pos
The (y, x)
coordinate of the minimum pixel value of the (backgroundsubtracted) data.minval_xpos
The x
coordinate of the minimum pixel value of the (backgroundsubtracted) data.minval_ypos
The y
coordinate of the minimum pixel value of the (backgroundsubtracted) 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 secondorder moments as the source.perimeter
The perimeter of the source segment, approximated lines through the centers of the border pixels using a 4connectivity. ra_icrs_centroid
Deprecated since version 0.4.
semimajor_axis_sigma
The 1sigma standard deviation along the semimajor axis of the 2D Gaussian function that has the same secondorder central moments as the source. semiminor_axis_sigma
The 1sigma standard deviation along the semiminor axis of the 2D Gaussian function that has the same secondorder central moments as the source. sky_bbox_ll
The sky coordinates of the lowerleft vertex of the minimal bounding box of the source segment, returned as a SkyCoord
object.sky_bbox_lr
The sky coordinates of the lowerright vertex of the minimal bounding box of the source segment, returned as a SkyCoord
object.sky_bbox_ul
The sky coordinates of the upperleft vertex of the minimal bounding box of the source segment, returned as a SkyCoord
object.sky_bbox_ur
The sky coordinates of the upperright 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 nonmasked (backgroundsubtracted) data values within the source segment. source_sum_err
The uncertainty of source_sum
, propagated from the inputerror
array.values
A ndarray
of the (backgroundsubtracted) 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 inputbackground
, where the mask isTrue
for both pixels outside of the source segment and masked pixels. Ifbackground
isNone
, thenbackground_cutout_ma
is alsoNone
.

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 they
andx
pixel coordinates of the source segment. Masked pixels are not included.

covar_sigx2
¶ The
(0, 0)
element of thecovariance
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 thecovariance
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 thecovariance
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 secondorder moments as the source.

covariance_eigvals
¶ The two eigenvalues of the
covariance
matrix in decreasing order.

cutout_centroid
¶ The
(y, x)
coordinate, relative to thedata_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 (backgroundsubtracted) data of the source segment.

data_cutout_ma
¶ A 2D
MaskedArray
cutout from the (backgroundsubtracted) data, where the mask isTrue
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 secondorder 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 (or1
minus theelongation
):\[\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.

error_cutout_ma
¶ A 2D
MaskedArray
cutout from the inputerror
image, where the mask isTrue
for both pixels outside of the source segment and masked pixels. Iferror
isNone
, thenerror_cutout_ma
is alsoNone
.

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 (backgroundsubtracted) data within the source segment.

maxval_cutout_pos
¶ The
(y, x)
coordinate, relative to thedata_cutout
, of the maximum pixel value of the (backgroundsubtracted) data.

maxval_pos
¶ The
(y, x)
coordinate of the maximum pixel value of the (backgroundsubtracted) data.

maxval_xpos
¶ The
x
coordinate of the maximum pixel value of the (backgroundsubtracted) data.

maxval_ypos
¶ The
y
coordinate of the maximum pixel value of the (backgroundsubtracted) data.

min_value
¶ The minimum pixel value of the (backgroundsubtracted) data within the source segment.

minval_cutout_pos
¶ The
(y, x)
coordinate, relative to thedata_cutout
, of the minimum pixel value of the (backgroundsubtracted) data.

minval_pos
¶ The
(y, x)
coordinate of the minimum pixel value of the (backgroundsubtracted) data.

minval_xpos
¶ The
x
coordinate of the minimum pixel value of the (backgroundsubtracted) data.

minval_ypos
¶ The
y
coordinate of the minimum pixel value of the (backgroundsubtracted) 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 secondorder moments as the source. The angle increases in the counterclockwise direction.

perimeter
¶ The perimeter of the source segment, approximated lines through the centers of the border pixels using a 4connectivity.

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 1sigma standard deviation along the semimajor axis of the 2D Gaussian function that has the same secondorder central moments as the source.

semiminor_axis_sigma
¶ The 1sigma standard deviation along the semiminor axis of the 2D Gaussian function that has the same secondorder central moments as the source.

sky_bbox_ll
¶ The sky coordinates of the lowerleft 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 lowerright 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 upperleft 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 upperright 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 nonmasked (backgroundsubtracted) 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 backgroundsubtracted inputdata
, and \(S\) are the nonmasked pixels in the source segment.

source_sum_err
¶ The uncertainty of
source_sum
, propagated from the inputerror
array.source_sum_err
is the quadrature sum of the total errors over the nonmasked 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 pixelwise total errors, and \(S\) are the nonmasked pixels in the source segment.

values
¶ A
ndarray
of the (backgroundsubtracted) pixel values within the source segment. Masked pixels are not included.

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.Parameters: data : arraylike (2D)
The data array from which to create the masked cutout array.
data
must have the same shape as the segmentation image input intoSourceProperties
.masked_array : bool, optional
If
True
then aMaskedArray
will be created where the mask isTrue
for both pixels outside of the source segment and any masked pixels. IfFalse
, then andarray
will be generated.Returns: result :
ndarray
orMaskedArray
(2D)The 2D cutout array or masked array.

to_table
(columns=None, exclude_columns=None)[source]¶ Create a
QTable
of properties.If
columns
orexclude_columns
are not input, then theQTable
will include all scalarvalued properties. Multidimensional properties, e.g.data_cutout
, can be included in thecolumns
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 ofSourceProperties
.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 singlerow table of properties of the source.
