PSFPhotometry¶
- class photutils.psf.PSFPhotometry(psf_model, fit_shape, *, finder=None, grouper=None, fitter=<astropy.modeling.fitting.LevMarLSQFitter object>, fitter_maxiters=100, localbkg_estimator=None, aperture_radius=None, progress_bar=False)[source]¶
Bases:
ModelImageMixin
Class to perform PSF photometry.
This class implements a flexible PSF photometry algorithm that can find sources in an image, group overlapping sources, fit the PSF model to the sources, and subtract the fit PSF models from the image.
- Parameters:
- psf_model2D
astropy.modeling.Model
The PSF model to fit to the data. The model must have parameters named
x_0
,y_0
, andflux
, corresponding to the center (x, y) position and flux, or it must have ‘x_name’, ‘y_name’, and ‘flux_name’ attributes that map to the x, y, and flux parameters (i.e., a model output frommake_psf_model
). The model must be two-dimensional such that it accepts 2 inputs (e.g., x and y) and provides 1 output.- fit_shapeint or length-2 array_like
The rectangular shape around the center of a star that will be used to define the PSF-fitting data. If
fit_shape
is a scalar then a square shape of sizefit_shape
will be used. Iffit_shape
has two elements, they must be in(ny, nx)
order. Each element offit_shape
must be an odd number. In general,fit_shape
should be set to a small size (e.g.,(5, 5)
) that covers the region with the highest flux signal-to-noise.- findercallable or
StarFinderBase
orNone
, optional A callable used to identify stars in an image. The
finder
must accept a 2D image as input and return aTable
containing the x and y centroid positions. These positions are used as the starting points for the PSF fitting. The allowedx
column names are (same suffix fory
):'x_init'
,'xinit'
,'x'
,'x_0'
,'x0'
,'xcentroid'
,'x_centroid'
,'x_peak'
,'xcen'
,'x_cen'
,'xpos'
,'x_pos'
,'x_fit'
, and'xfit'
. IfNone
, then the initial (x, y) model positions must be input using theinit_params
keyword when calling the class. The (x, y) values ininit_params
override this keyword. If this class is run on an image that has units (i.e., aQuantity
array), then certainfinder
keywords (e.g.,threshold
) must have the same units. Please see the the documentation for the specificfinder
class for more information.- grouper
SourceGrouper
or callable orNone
, optional A callable used to group stars. Typically, grouped stars are those that overlap with their neighbors. Stars that are grouped are fit simultaneously. The
grouper
must accept the x and y coordinates of the sources and return an integer array of the group id numbers (starting from 1) indicating the group in which a given source belongs. IfNone
, then no grouping is performed, i.e. each source is fit independently. Thegroup_id
values ininit_params
override this keyword only for the first iteration. A warning is raised if any group size is larger than 25 sources.- fitter
Fitter
, optional The fitter object used to perform the fit of the model to the data.
- fitter_maxitersint, optional
The maximum number of iterations in which the
fitter
is called for each source. This keyword can be increased if the fit is not converging for sources (e.g., the outputflags
value contains 8).- localbkg_estimator
LocalBackground
orNone
, optional The object used to estimate the local background around each source. If
None
, then no local background is subtracted. Thelocal_bkg
values ininit_params
override this keyword. This option should be used with care, especially in crowded fields where thefit_shape
of sources overlap (see Notes below).- aperture_radiusfloat, optional
The radius of the circular aperture used to estimate the initial flux of each source. If initial flux values are present in the
init_params
table, they will override this keyword.- progress_barbool, optional
Whether to display a progress bar when fitting the sources (or groups). The progress bar requires that the tqdm optional dependency be installed. Note that the progress bar does not currently work in the Jupyter console due to limitations in
tqdm
.
- psf_model2D
Notes
The local background value around each source is optionally estimated using the
localbkg_estimator
or obtained from thelocal_bkg
column in the inputinit_params
table. This local background is then subtracted from the data over thefit_shape
region for each source before fitting the PSF model. For sources where theirfit_shape
regions overlap, the local background will effectively be subtracted twice in the overlappingfit_shape
regions, even if the sourcegrouper
is input. This is not an issue if the sources are well-separated. However, for crowded fields, please use thelocalbkg_estimator
(orlocal_bkg
column ininit_params
) with care.Methods Summary
__call__
(data, *[, mask, error, init_params])Perform PSF photometry.
make_model_image
(shape, psf_shape, *[, ...])Create a 2D image from the fit PSF models and optional local background.
make_residual_image
(data, psf_shape, *[, ...])Create a 2D residual image from the fit PSF models and local background.
Methods Documentation
- __call__(data, *, mask=None, error=None, init_params=None)[source]¶
Perform PSF photometry.
- Parameters:
- data2D
ndarray
The 2D array on which to perform photometry. Invalid data values (i.e., NaN or inf) are automatically masked.
- mask2D bool
ndarray
, optional A boolean mask with the same shape as
data
, where aTrue
value indicates the corresponding element ofdata
is masked.- error2D
ndarray
, optional The pixel-wise 1-sigma 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
. Ifdata
is aQuantity
array, thenerror
must also be aQuantity
array with the same units.- init_params
Table
orNone
, optional A table containing the initial guesses of the (x, y, flux) model parameters for each source. If the x and y values are not input, then the
finder
keyword must be defined. If the flux values are not input, then theaperture_radius
keyword must be defined. Note that the initial flux values refer to the model flux parameters and are not corrected for local background values (computed usinglocalbkg_estimator
or input in alocal_bkg
column) The allowed column names are:x_init
,xinit
,x
,x_0
,x0
,xcentroid
,x_centroid
,x_peak
,xcen
,x_cen
,xpos
,x_pos
,x_fit
, andxfit
.y_init
,yinit
,y
,y_0
,y0
,ycentroid
,y_centroid
,y_peak
,ycen
,y_cen
,ypos
,y_pos
,y_fit
, andyfit
.flux_init
,fluxinit
,flux
,flux_0
,flux0
,flux_fit
,fluxfit
,source_sum
,segment_flux
, andkron_flux
.
The parameter names are searched in the input table in the above order, stopping at the first match.
If
data
is aQuantity
array, then the initial flux values in this table must also must also have compatible units.The table can also have
group_id
andlocal_bkg
columns. Ifgroup_id
is input, the values will be used andgrouper
keyword will be ignored. Iflocal_bkg
is input, those values will be used and thelocalbkg_estimator
will be ignored. Ifdata
has units, then thelocal_bkg
values must have the same units.
- data2D
- Returns:
- table
QTable
An astropy table with the PSF-fitting results. The table will contain the following columns:
id
: unique identification number for the sourcegroup_id
: unique identification number for the source groupgroup_size
: the total number of sources that were simultaneously fit along with the given sourcex_init
,x_fit
,x_err
: the initial, fit, and error of the source x centery_init
,y_fit
,y_err
: the initial, fit, and error of the source y centerflux_init
,flux_fit
,flux_err
: the initial, fit, and error of the source fluxnpixfit
: the number of unmasked pixels used to fit the sourceqfit
: a quality-of-fit metric defined as the absolute value of the sum of the fit residuals divided by the fit fluxcfit
: a quality-of-fit metric defined as the fit residual in the central pixel divided by the fit fluxflags
bitwise flag values:1 : one or more pixels in the
fit_shape
region were masked2 : the fit x and/or y position lies outside of the input data
4 : the fit flux is less than or equal to zero
8 : the fitter may not have converged. In this case, you can try increasing the maximum number of fit iterations using the
fitter_maxiters
keyword.16 : the fitter parameter covariance matrix was not returned
- table
- make_model_image(shape, psf_shape, *, include_localbkg=False)[source]¶
Create a 2D image from the fit PSF models and optional local background.
- Parameters:
- shape2 tuple of int
The shape of the output array.
- psf_shape2 tuple of int
The shape of region around the center of the fit model to render in the output image.
- include_localbkgbool, optional
Whether to include the local background in the rendered output image. Note that the local background level is included around each source over the region defined by
psf_shape
. Thus, regions where thepsf_shape
of sources overlap will have the local background added multiple times.
- Returns:
- array2D
ndarray
The rendered image from the fit PSF models. This image will not have any units.
- array2D
- make_residual_image(data, psf_shape, *, include_localbkg=False)[source]¶
Create a 2D residual image from the fit PSF models and local background.
- Parameters:
- data2D
ndarray
The 2D array on which photometry was performed. This should be the same array input when calling the PSF-photometry class.
- psf_shape2 tuple of int
The shape of region around the center of the fit model to subtract.
- include_localbkgbool, optional
Whether to include the local background in the subtracted model. Note that the local background level is subtracted around each source over the region defined by
psf_shape
. Thus, regions where thepsf_shape
of sources overlap will have the local background subtracted multiple times.
- data2D
- Returns:
- array2D
ndarray
The residual image of the
data
minus thelocal_bkg
minus the fit PSF models.
- array2D