SourceCatalog¶
- class photutils.segmentation.SourceCatalog(data, segment_img, *, convolved_data=None, error=None, mask=None, kernel=None, background=None, wcs=None, localbkg_width=0, apermask_method='correct', kron_params=(2.5, 1.0), detection_cat=None)[source]¶
Bases:
object
Class to create a catalog of photometry and morphological properties for sources defined by a segmentation image.
- Parameters
- data2D
ndarray
orQuantity
, optional The 2D array from which to calculate the source photometry and properties. If
convolved_data
(orkernel
) is input, then a convolved version ofdata
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 background-subtracted. Non-finitedata
values (NaN and inf) are automatically masked.- segment_img
SegmentationImage
A
SegmentationImage
object defining the sources.- convolved_datadata2D
ndarray
orQuantity
, optional The 2D array used to calculate the source centroid and morphological properties. It is recommended that the user input the convolved data directly instead of using the
kernel
keyword. Ifconvolved_data
is input, then thekernel
keyword will be ignored. If bothconvolved_data
andkernel
areNone
, then the unconvolveddata
will be used instead. Non-finiteconvolved_data
values (NaN and inf) are not automatically masked, unless they are at the same position of non-finite values in the inputdata
array. Such pixels can be masked using themask
keyword.- error2D
ndarray
orQuantity
, 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 (seecalc_total_error
) .error
must have the same shape as the inputdata
. Ifdata
is aQuantity
array thenerror
must be aQuantity
array (and vice versa) with identical units. Non-finiteerror
values (NaN and inf) are not automatically masked, unless they are at the same position of non-finite values in the inputdata
array. Such pixels can be masked using themask
keyword. See the Notes section below for details on the error propagation.- mask2D
ndarray
(bool), optional A boolean mask with the same shape as
data
where aTrue
value indicates the corresponding element ofdata
is masked. Masked data are excluded from all calculations. Non-finite values (NaN and inf) in the inputdata
are automatically masked.- kernelarray-like (2D) or
Kernel2D
, optional The 2D array of the kernel used to filter the data prior to calculating the source centroid and morphological parameters. The kernel should be the same one used in defining the source segments, i.e., the detection image (e.g., see
detect_sources()
). IfNone
, then the unfiltereddata
will be used instead. This keyword is ignored ifconvolved_data
is input (recommended).- backgroundfloat, 2D
ndarray
orQuantity
, 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 inputdata
. Ifdata
is aQuantity
array thenbackground
must be aQuantity
array (and vice versa) with identical units. Inputing 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 background-subtracted. Non-finitebackground
values (NaN and inf) are not automatically masked, unless they are at the same position of non-finite values in the inputdata
array. Such pixels can be masked using themask
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
). IfNone
, then all sky-based properties will be set toNone
.- localbkg_widthint, optional
The width of the rectangular annulus used to compute a local background around each source. If 0.0, then no local background subtraction is performed. The local background affects the
min_value
,max_value
,segment_flux
, andkron_flux
properties. It does not affect the moment-based morphological properties of the source.- apermask_method{‘correct’, ‘mask’, ‘none’}, optional
The method used to handle neighboring sources when performing aperture photometry (e.g., circular apertures or elliptical Kron apertures). This parameter also affects the Kron radius.
‘correct’: replace pixels assigned to neighboring sources by replacing them with pixels on the opposite side of the source center (equivalent to MASK_TYPE=CORRECT in SourceExtractor).
‘mask’: mask pixels assigned to neighboring sources (equivalent to MASK_TYPE=BLANK in SourceExtractor).
‘none’: do not mask any pixels (equivalent to MASK_TYPE=NONE in SourceExtractor).
- kron_paramslist of 2 floats, optional
A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius and the second item represents the minimum circular radius. If the Kron radius times sqrt(
semimajor_sigma
*semiminor_sigma
) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.- detection_cat
SourceCatalog
, optional A
SourceCatalog
object for the detection image. The source labels indetection_cat
must correspond to the labels in the inputsegment_img
. If input, this detection catalog will be used to define the source centroids for all aperture-based photometry (e.g., local background aperture, circular aperture, Kron aperture). It will also be used to define the object elliptical shape parameters when calculating the Kron radius. This keyword affects the local-background value, circular aperture photometry, Kron radius, and Kron photometry.
- data2D
Notes
data
should be background-subtracted for accurate source photometry and properties. The previously-subtracted background can be passed into this class to calculate properties of the background for each source.SourceExtractor’s centroid and morphological parameters are always calculated from a convolved, or filtered, “detection” image (
convolved_data
), i.e., the image used to define the segmentation image. The usual downside of the filtering is the sources will be made more circular than they actually are. If you wish to reproduce SourceExtractor centroid and morphology results, then input theconvolved_data
(orkernel
, but not both). Ifconvolved_data
andkernel
are bothNone
, then the unfiltereddata
will be used for the source centroid and morphological parameters.Negative data values within the source segment are set to zero when calculating morphological properties based on image moments. Negative values could occur, for example, if the segmentation image was defined from a different image (e.g., different bandpass) or if the background was oversubtracted. However,
segment_flux
always includes the contribution of negativedata
values.The input
error
array is assumed to include all sources of error, including the Poisson error of the sources.segment_fluxerr
is simply the quadrature sum of the pixel-wise total errors over the unmasked pixels within the source segment:\[\Delta F = \sqrt{\sum_{i \in S} \sigma_{\mathrm{tot}, i}^2}\]where \(\Delta F\) is
segment_fluxerr
, \(S\) are the unmasked 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_ma
andbackground_ma
properties, which are 2DMaskedArray
cutout versions of the inputerror
andbackground
arrays. The mask isTrue
for pixels outside of the source segment, masked pixels from themask
input, or any non-finitedata
values (NaN and inf).Attributes Summary
The total unmasked area of the source segment in units of pixels**2.
A 2D
ndarray
cutout from the background array using the minimal bounding box of the source.The value of the per-pixel
background
at the position of the source centroid.A 2D
MaskedArray
cutout from the background array.The mean of
background
values within the source segment.The sum of
background
values within the source segment.The
BoundingBox
of the minimal rectangular region containing the source segment.The maximum
x
pixel index within the minimal bounding box containing the source segment.The minimum
x
pixel index within the minimal bounding box containing the source segment.The maximum
y
pixel index within the minimal bounding box containing the source segment.The minimum
y
pixel index within the minimal bounding box containing the source segment.The
(x, y)
coordinate of the centroid within the source segment.A 2D
ndarray
cutout from the convolved data using the minimal bounding box of the source.A 2D
MaskedArray
cutout from the convolved data using the minimal bounding box of the source.The
(0, 0)
element of thecovariance
matrix, representing \(\sigma_x^2\), in units of pixel**2.The
(0, 1)
and(1, 0)
elements of thecovariance
matrix, representing \(\sigma_x \sigma_y\), in units of pixel**2.The
(1, 1)
element of thecovariance
matrix, representing \(\sigma_y^2\), in units of pixel**2.The covariance matrix of the 2D Gaussian function that has the same second-order moments as the source.
The two eigenvalues of the
covariance
matrix in decreasing order.The
(x, y)
coordinate, relative to the cutout data, of the centroid within the source segment.The
(y, x)
coordinate, relative to the cutout data, of the maximum pixel value of thedata
within the source segment.The
(y, x)
coordinate, relative to the cutout data, of the minimum pixel value of thedata
within the source segment.SourceExtractor's CXX ellipse parameter in units of pixel**(-2).
SourceExtractor's CXY ellipse parameter in units of pixel**(-2).
SourceExtractor's CYY ellipse parameter in units of pixel**(-2).
A 2D
ndarray
cutout from the data using the minimal bounding box of the source.A 2D
MaskedArray
cutout from the data using the minimal bounding box of the source.The eccentricity of the 2D Gaussian function that has the same second-order moments as the source.
1.0 minus the ratio of the lengths of the semimajor and semiminor axes (or 1.0 minus the
elongation
).The ratio of the lengths of the semimajor and semiminor axes.
The radius of a circle with the same
area
as the source segment.A 2D
ndarray
cutout from the error array using the minimal bounding box of the source.A 2D
MaskedArray
cutout from the error array using the minimal bounding box of the source.A list of the user-defined source properties.
The circularized full width at half maximum (FWHM) of the 2D Gaussian function that has the same second-order central moments as the source.
The Gini coefficient of the source.
The inertia tensor of the source for the rotation around its center of mass.
Whether the instance is scalar (e.g., a single source).
The elliptical Kron aperture.
The flux in the Kron aperture.
The flux error in the Kron aperture.
The unscaled first-moment Kron radius.
The source label number(s).
The source label number(s), always as an iterable
ndarray
.The local background value estimated using a rectangular annulus aperture around the source.
The
RectangularAnnulus
aperture used to estimate the local background.The maximum pixel value of the
data
within the source segment.The
(y, x)
coordinate of the maximum pixel value of thedata
within the source segment.The
x
coordinate of the maximum pixel value of thedata
within the source segment.The
y
coordinate of the maximum pixel value of thedata
within the source segment.The minimum pixel value of the
data
within the source segment.The
(y, x)
coordinate of the minimum pixel value of thedata
within the source segment.The
x
coordinate of the minimum pixel value of thedata
within the source segment.The
y
coordinate of the minimum pixel value of thedata
within the source segment.Spatial moments up to 3rd order of the source.
Central moments (translation invariant) of the source up to 3rd order.
The number of source labels.
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 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.
A list of built-in source properties.
A 2D
ndarray
cutout of the segmentation image using the minimal bounding box of the source.The sum of the unmasked
data
values within the source segment.The uncertainty of
segment_flux
, propagated from the inputerror
array.A 2D
MaskedArray
cutout of the segmentation image using the minimal bounding box of the source.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.
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.
The sky coordinates of the lower-left corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The sky coordinates of the lower-right corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The sky coordinates of the upper-left corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The sky coordinates of the upper-right corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The sky coordinate of the centroid within the source segment, returned as a
SkyCoord
object.The sky coordinate in the International Celestial Reference System (ICRS) frame of the centroid within the source segment, returned as a
SkyCoord
object.A tuple of slice objects defining the minimal bounding box of the source.
The
x
coordinate of the centroid within the source segment.The
y
coordinate of the centroid within the source segment.Methods Summary
add_extra_property
(name, value[, overwrite])Add a user-defined extra property as a new attribute.
circular_aperture
(radius)Deprecated since version 1.3.
circular_photometry
(radius[, name, overwrite])Perform aperture photometry for each source using a circular aperture of the specified radius centered at the source centroid position.
copy
()Return a deep copy of this SourceCatalog.
fluxfrac_radius
(fluxfrac[, name, overwrite])Calculate the circular radius that encloses the specified fraction of the Kron flux.
get_label
(label)Return a new
SourceCatalog
object for the inputlabel
only.get_labels
(labels)Return a new
SourceCatalog
object for the inputlabels
only.kron_photometry
(kron_params[, name, overwrite])Perform photometry for each source using an elliptical Kron aperture.
make_circular_apertures
(radius)Return a list of circular apertures with the specified radius centered at the source centroid position.
make_kron_apertures
(kron_params)Return a list of Kron elliptical apertures with the specified scaling and centered at the source centroid position.
plot_circular_apertures
(radius[, axes, origin])Plot circular apertures on a matplotlib
Axes
instance.plot_kron_apertures
(kron_params[, axes, origin])Plot Kron elliptical apertures on a matplotlib
Axes
instance.remove_extra_properties
(names)Remove user-defined extra properties.
remove_extra_property
(name)Remove a user-defined extra property.
rename_extra_property
(name, new_name)Rename a user-defined extra property.
to_table
([columns])Create a
QTable
of source 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
SourceCatalog
or if thedata
within the segment contains invalid values (NaN and inf).
- background¶
A 2D
ndarray
cutout from the background array using the minimal bounding box of the source.
- background_centroid¶
The value of the per-pixel
background
at the position of the source centroid.The background value at fractional position values are determined using bilinear interpolation.
- background_ma¶
A 2D
MaskedArray
cutout from the background array. using the minimal bounding box of the source.The mask is
True
for pixels outside of the source segment (labeled region of interest), masked pixels from themask
input, or any non-finitedata
values (NaN and inf).
- 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 index within the minimal bounding box containing the source segment.Note that this value is inclusive, unlike numpy slice indices.
- bbox_xmin¶
The minimum
x
pixel index within the minimal bounding box containing the source segment.
- bbox_ymax¶
The maximum
y
pixel index within the minimal bounding box containing the source segment.Note that this value is inclusive, unlike numpy slice indices.
- bbox_ymin¶
The minimum
y
pixel index within the minimal bounding box containing the source segment.
- centroid¶
The
(x, y)
coordinate of the centroid within the source segment.
- convdata_ma¶
A 2D
MaskedArray
cutout from the convolved data using the minimal bounding box of the source.The mask is
True
for pixels outside of the source segment (labeled region of interest), masked pixels from themask
input, or any non-finitedata
values (NaN and inf).
- 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 second-order moments as the source.
- covariance_eigvals¶
The two eigenvalues of the
covariance
matrix in decreasing order.
- cutout_centroid¶
The
(x, y)
coordinate, relative to the cutout data, of the centroid within the source segment.
- cutout_maxval_index¶
The
(y, x)
coordinate, relative to the cutout data, of the maximum pixel value of thedata
within the source segment.If there are multiple occurrences of the maximum value, only the first occurrence is returned.
- cutout_minval_index¶
The
(y, x)
coordinate, relative to the cutout data, of the minimum pixel value of thedata
within the source segment.If there are multiple occurrences of the minimum value, only the first occurrence is returned.
- cxx¶
SourceExtractor’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). SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).
- cxy¶
SourceExtractor’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). SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).
- cyy¶
SourceExtractor’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). SourceExtractor reports that the isophotal limit of a source is well represented by \(R \approx 3\).
- data_ma¶
A 2D
MaskedArray
cutout from the data using the minimal bounding box of the source.The mask is
True
for pixels outside of the source segment (labeled region of interest), masked pixels from themask
input, or any non-finitedata
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.0 minus the ratio of the lengths of the semimajor and semiminor axes (or 1.0 minus the
elongation
).\[\mathrm{ellipticity} = 1 - \frac{b}{a}\]where \(a\) and \(b\) are the lengths of the semimajor and semiminor axes, respectively.
- elongation¶
The ratio of the lengths of the semimajor and semiminor axes.
\[\mathrm{elongation} = \frac{a}{b}\]where \(a\) and \(b\) are the lengths of the semimajor and semiminor axes, respectively.
- error_ma¶
A 2D
MaskedArray
cutout from the error array using the minimal bounding box of the source.The mask is
True
for pixels outside of the source segment (labeled region of interest), masked pixels from themask
input, or any non-finitedata
values (NaN and inf).
- extra_properties¶
A list of the user-defined source properties.
- fwhm¶
The circularized full width at half maximum (FWHM) of the 2D Gaussian function that has the same second-order central moments as the source.
\[\begin{split}\mathrm{FWHM} & = 2 \sqrt{2 \ln(2)} \sqrt{0.5 (a^2 + b^2)} \\ & = 2 \sqrt{\ln(2) \ (a^2 + b^2)}\end{split}\]where \(a\) and \(b\) are the 1-sigma lengths of the semimajor (
semimajor_sigma
) and semiminor (semiminor_sigma
) axes, respectively.
- 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 pixel values \(x_i\) within the source segment.
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.
- inertia_tensor¶
The inertia tensor of the source for the rotation around its center of mass.
- isscalar¶
Whether the instance is scalar (e.g., a single source).
- kron_aperture¶
The elliptical Kron aperture.
For sources where
\[k_r \ \sqrt{a \cdot b} < rc_{min}\]where \(k_r\) is the
kron_radius
, \(a\) and \(b\) are the semimajor (semimajor_sigma
) and semiminor (semiminor_sigma
) axes, respectively, and \(rc_{min}\) is the minimum circular radius defined bykron_params[1]
(seeSourceCatalog
), then a circular aperture with a radius equal tokron_params[1]
will be returned. Ifkron_params[1] <= 0
, then the Kron aperture will beNone
.If
kron_radius = np.nan
then a circular aperture with a radius equal tokron_params[1]
will be returned if the source is not completely masked, otherwiseNone
will be returned.Note that if the Kron aperture is
None
, the Kron flux will benp.nan
.
- kron_flux¶
The flux in the Kron aperture.
See the
SourceCatalog
apermask_method
keyword for options to mask neighboring sources.If the Kron aperture is
None
, thennp.nan
will be returned.
- kron_fluxerr¶
The flux error in the Kron aperture.
See the
SourceCatalog
apermask_method
keyword for options to mask neighboring sources.If the Kron aperture is
None
, thennp.nan
will be returned.
- 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 \(I_i\) are the data values and the sum is over pixels in an elliptical aperture whose axes are defined by six times the semimajor (
semimajor_sigma
) and semiminor axes (semiminor_sigma
) at the calculatedorientation
(all properties derived from the central image moments of the source). \(r_i\) is the elliptical “radius” to the pixel given by:\[r_i^2 = cxx (x_i - \bar{x})^2 + cxy (x_i - \bar{x})(y_i - \bar{y}) + cyy (y_i - \bar{y})^2\]where \(\bar{x}\) and \(\bar{y}\) represent the source centroid and the coefficients are based on image moments (
cxx
,cxy
, andcyy
).The scaling parameter of the
kron_radius
is defined using theSourceCatalog
kron_params
keyword.See the
SourceCatalog
apermask_method
keyword for options to mask neighboring sources.If either the numerator or denominator above is less than or equal to 0, then
np.nan
will be returned for both the Kron radius and Kron flux.If the source is completely masked, then
np.nan
will be returned for both the Kron radius and Kron flux.If the
SourceCatalog
detection_cat
was provided, then itskron_radius
will be returned if the source is not completely masked.
- label¶
The source label number(s).
This label number corresponds to the assigned pixel value in the
SegmentationImage
.
- labels¶
The source label number(s), always as an iterable
ndarray
.This label number corresponds to the assigned pixel value in the
SegmentationImage
.
- local_background¶
The local background value estimated using a rectangular annulus aperture around the source.
- local_background_aperture¶
The
RectangularAnnulus
aperture used to estimate the local background.
- max_value¶
The maximum pixel value of the
data
within the source segment.
- maxval_index¶
The
(y, x)
coordinate of the maximum pixel value of thedata
within the source segment.If there are multiple occurrences of the maximum value, only the first occurrence is returned.
- maxval_xindex¶
The
x
coordinate of the maximum pixel value of thedata
within the source segment.If there are multiple occurrences of the maximum value, only the first occurrence is returned.
- maxval_yindex¶
The
y
coordinate of the maximum pixel value of thedata
within the source segment.If there are multiple occurrences of the maximum value, only the first occurrence is returned.
- min_value¶
The minimum pixel value of the
data
within the source segment.
- minval_index¶
The
(y, x)
coordinate of the minimum pixel value of thedata
within the source segment.If there are multiple occurrences of the minimum value, only the first occurrence is returned.
- minval_xindex¶
The
x
coordinate of the minimum pixel value of thedata
within the source segment.If there are multiple occurrences of the minimum value, only the first occurrence is returned.
- minval_yindex¶
The
y
coordinate of the minimum pixel value of thedata
within the source segment.If there are multiple occurrences of the minimum value, only the first occurrence is returned.
- moments¶
Spatial moments up to 3rd order of the source.
- moments_central¶
Central moments (translation invariant) of the source up to 3rd order.
- nlabels¶
The number of source labels.
- orientation¶
The angle between the
x
axis and the major axis of the 2D Gaussian function that has the same second-order moments as the source. The angle increases in the counter-clockwise direction.
- 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
- properties¶
A list of built-in source properties.
- segment¶
A 2D
ndarray
cutout of the segmentation image using the minimal bounding box of the source.
- segment_flux¶
The sum of the unmasked
data
values within the source segment.\[F = \sum_{i \in S} I_i\]where \(F\) is
segment_flux
, \(I_i\) is the background-subtracteddata
, and \(S\) are the unmasked pixels in the source segment.Non-finite pixel values (NaN and inf) are excluded (automatically masked).
- segment_fluxerr¶
The uncertainty of
segment_flux
, propagated from the inputerror
array.segment_fluxerr
is the quadrature sum of the total errors over the unmasked pixels within the source segment:\[\Delta F = \sqrt{\sum_{i \in S} \sigma_{\mathrm{tot}, i}^2}\]where \(\Delta F\) is the
segment_flux
, \(\sigma_{\mathrm{tot, i}}\) are the pixel-wise total errors (error
), and \(S\) are the unmasked pixels in the source segment.Pixel values that are masked in the input
data
, including any non-finite pixel values (NaN and inf) that are automatically masked, are also masked in the error array.
- segment_ma¶
A 2D
MaskedArray
cutout of the segmentation image using the minimal bounding box of the source.The mask is
True
for pixels outside of the source segment (labeled region of interest), masked pixels from themask
input, or any non-finitedata
values (NaN and inf).
- semimajor_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_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 corner 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, not their centers.
None
ifwcs
is not input.
- sky_bbox_lr¶
The sky coordinates of the lower-right corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.
None
ifwcs
is not input.
- sky_bbox_ul¶
The sky coordinates of the upper-left corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.
None
ifwcs
is not input.
- sky_bbox_ur¶
The sky coordinates of the upper-right corner vertex of the minimal bounding box of the source segment, returned as a
SkyCoord
object.The bounding box encloses all of the source segment pixels in their entirety, thus the vertices are at the pixel corners, not their centers.
None
ifwcs
is not input.
- sky_centroid¶
The sky coordinate of the centroid within the source segment, returned as a
SkyCoord
object.The output coordinate frame is the same as the input
wcs
.None
ifwcs
is not input.
- sky_centroid_icrs¶
The sky coordinate in the International Celestial Reference System (ICRS) frame of the centroid within the source segment, returned as a
SkyCoord
object.None
ifwcs
is not input.
- slices¶
A tuple of slice objects defining the minimal bounding box of the source.
- xcentroid¶
The
x
coordinate of the centroid within the source segment.
- ycentroid¶
The
y
coordinate of the centroid within the source segment.
Methods Documentation
- add_extra_property(name, value, overwrite=False)[source]¶
Add a user-defined extra property as a new attribute.
For example, the property
name
can then be included in theto_table
columns
keyword list to output the results in the table.The complete list of user-defined extra properties is stored in the
extra_properties
attribute.- Parameters
- namestr
The name of property. The name must not conflict with any of the built-in property names or attributes.
- valuearray-like or float
The value to assign.
- overwritebool, option
If
True
, will overwrite the existing propertyname
.
- circular_aperture(radius)[source]¶
Deprecated since version 1.3: The circular_aperture function is deprecated and may be removed in a future version. Use make_circular_apertures instead.
Return a list of circular apertures with the specified radius centered at the source centroid position.
- Parameters
- radiusfloat
The radius of the circle in pixels.
- Returns
- resultlist of
CircularAperture
A list of
CircularAperture
instances. The aperture will beNone
where the source centroid position is not finite or where the source is completely masked.
- resultlist of
- circular_photometry(radius, name=None, overwrite=False)[source]¶
Perform aperture photometry for each source using a circular aperture of the specified radius centered at the source centroid position.
See the
SourceCatalog
apermask_method
keyword for options to mask neighboring sources.- Parameters
- radiusfloat
The radius of the circle in pixels.
- namestr or
None
, optional The prefix name which will be used to define attribute names for the flux and flux error. The attribute names
[name]_flux
and[name]_fluxerr
will store the photometry results. For example, these names can then be included in theto_table
columns
keyword list to output the results in the table.- overwritebool, optional
If True, overwrite the attribute
name
if it exists.
- Returns
- fluxfrac_radius(fluxfrac, name=None, overwrite=False)[source]¶
Calculate the circular radius that encloses the specified fraction of the Kron flux.
To estimate the half-light radius, use
fluxfrac = 0.5
.- Parameters
- fluxfracfloat
The fraction of the Kron flux at which to find the circular radius.
- namestr or
None
, optional The attribute name which will be assigned to the value of the output array. For example, this name can then be included in the
to_table
columns
keyword list to output the results in the table.- overwritebool, optional
If True, overwrite the attribute
name
if it exists.
- Returns
- radius1D
ndarray
The circular radius that encloses the specified fraction of the Kron flux. NaN is returned where no solution was found or if the Kron flux is zero.
- radius1D
- get_label(label)[source]¶
Return a new
SourceCatalog
object for the inputlabel
only.- Parameters
- labelint
The source label.
- Returns
- cat
SourceCatalog
A new
SourceCatalog
object containing only the source with the inputlabel
.
- cat
- get_labels(labels)[source]¶
Return a new
SourceCatalog
object for the inputlabels
only.- Parameters
- labelslist, tuple, or
ndarray
of int The source label(s).
- labelslist, tuple, or
- Returns
- cat
SourceCatalog
A new
SourceCatalog
object containing only the sources with the inputlabels
.
- cat
- kron_photometry(kron_params, name=None, overwrite=False)[source]¶
Perform photometry for each source using an elliptical Kron aperture.
This method can be used to calculate the Kron photometry using different scalings of the Kron radius (
kron_radius
).See the
SourceCatalog
apermask_method
keyword for options to mask neighboring sources.- Parameters
- kron_paramslist of 2 floats, optional
A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (
kron_radius
) and the second item represents the minimum circular radius. If the Kron radius times sqrt(semimajor_sigma
*semiminor_sigma
) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.- namestr or
None
, optional The prefix name which will be used to define attribute names for the Kron flux and flux error. The attribute names
[name]_flux
and[name]_fluxerr
will store the photometry results. For example, these names can then be included in theto_table
columns
keyword list to output the results in the table.- overwritebool, optional
If True, overwrite the attribute
name
if it exists.
- Returns
- make_circular_apertures(radius)[source]¶
Return a list of circular apertures with the specified radius centered at the source centroid position.
If provided, the
SourceCatalog
detection_cat
will be used for the source centroids.- Parameters
- radiusfloat
The radius of the circle in pixels.
- Returns
- resultlist of
CircularAperture
A list of
CircularAperture
instances. The aperture will beNone
where the source centroid position is not finite or where the source is completely masked.
- resultlist of
- make_kron_apertures(kron_params)[source]¶
Return a list of Kron elliptical apertures with the specified scaling and centered at the source centroid position.
If provided, the
SourceCatalog
detection_cat
will be used for the source centroids and elliptical shape parameters.- Parameters
- kron_paramslist of 2 floats, optional
A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (
kron_radius
) and the second item represents the minimum circular radius. If the Kron radius times sqrt(semimajor_sigma
*semiminor_sigma
) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.
- Returns
- resultlist of
PixelAperture
A list of
EllipticalAperture
orCircularAperture
instances. The aperture will beNone
where the source centroid position is not finite or where the source is completely masked.
- resultlist of
- plot_circular_apertures(radius, axes=None, origin=(0, 0), **kwargs)[source]¶
Plot circular apertures on a matplotlib
Axes
instance.The apertures are defined by the specified radius and are centered at the source centroid position.
If provided, the
SourceCatalog
detection_cat
will be used for the source centroids.- Parameters
- radiusfloat
The radius of the circle in pixels.
- axes
matplotlib.axes.Axes
orNone
, optional The matplotlib axes on which to plot. If
None
, then the currentAxes
instance is used.- originarray_like, optional
The
(x, y)
position of the origin of the displayed image.- **kwargs
dict
Any keyword arguments accepted by
matplotlib.patches.Patch
.
- Returns
- patchlist of
Patch
A list of matplotlib patches for the plotted aperture. The patches can be used, for example, when adding a plot legend.
- patchlist of
- plot_kron_apertures(kron_params, axes=None, origin=(0, 0), **kwargs)[source]¶
Plot Kron elliptical apertures on a matplotlib
Axes
instance.The apertures are defined by the specified radius and are centered at the source centroid position.
If provided, the
SourceCatalog
detection_cat
will be used for the source centroids and elliptical shape parameters.- Parameters
- kron_paramslist of 2 floats, optional
A list of two parameters used to determine how the Kron radius and flux are calculated. The first item is the scaling parameter of the Kron radius (
kron_radius
) and the second item represents the minimum circular radius. If the Kron radius times sqrt(semimajor_sigma
*semiminor_sigma
) is less than than this radius, then the Kron flux will be measured in a circle with this minimum radius.- axes
matplotlib.axes.Axes
orNone
, optional The matplotlib axes on which to plot. If
None
, then the currentAxes
instance is used.- originarray_like, optional
The
(x, y)
position of the origin of the displayed image.- **kwargs
dict
Any keyword arguments accepted by
matplotlib.patches.Patch
.
- Returns
- patchlist of
Patch
A list of matplotlib patches for the plotted aperture. The patches can be used, for example, when adding a plot legend.
- patchlist of
- remove_extra_properties(names)[source]¶
Remove user-defined extra properties.
The properties must have been defined using
add_extra_property
. The complete list of user-defined extra properties is stored in theextra_properties
attribute.- Parameters
- namelist of str
The names of the properties to remove.
- remove_extra_property(name)[source]¶
Remove a user-defined extra property.
The property must have been defined using
add_extra_property
. The complete list of user-defined extra properties is stored in theextra_properties
attribute.- Parameters
- namestr
The name of the property to remove.
- rename_extra_property(name, new_name)[source]¶
Rename a user-defined extra property.
The renamed property will remain at the same index in the
extra_properties
list.- Parameters
- namestr
The old attribute name.
- new_namestr
The new attribute name.
- to_table(columns=None)[source]¶
Create a
QTable
of source properties.- Parameters
- columnsstr, list of str,
None
, optional Names of columns, in order, to include in the output
QTable
. The allowed column names are any of theSourceCatalog
properties or custom properties added usingadd_extra_property
. Ifcolumns
isNone
, then a default list of scalar-valued properties (as defined by thedefault_columns
attribute) will be used.
- columnsstr, list of str,
- Returns
- table
QTable
A table of sources properties with one row per source.
- table