IterativePSFPhotometry#
- class photutils.psf.IterativePSFPhotometry(psf_model, fit_shape, finder, *, grouper=None, fitter=<astropy.modeling.fitting.TRFLSQFitter object>, fitter_maxiters=100, xy_bounds=None, maxiters=3, mode='new', localbkg_estimator=None, aperture_radius=None, sub_shape=None, progress_bar=False)[source]#
Bases:
ModelImageMixin
Class to iteratively perform PSF photometry.
This is a convenience class that iteratively calls the
PSFPhotometry
class to perform PSF photometry on an input image. It can be useful for crowded fields where faint stars are very close to bright stars and are not detected in the first pass of PSF photometry. For complex cases, one may need to manually runPSFPhotometry
in an iterative manner and inspect the residual image after each iteration.- 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
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 only for the first iteration. 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 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.- xy_bounds
None
, float, or 2-tuple of float, optional The maximum distance in pixels that a fitted source can be from the initial (x, y) position. If a single float, then the same maximum distance is used for both x and y. If a 2-tuple of floats, then the distances are in
(x, y)
order. IfNone
, then no bounds are applied. Either value can also beNone
to indicate no bound in that direction.- maxitersint, optional
The maximum number of PSF-fitting/subtraction iterations to perform.
- mode{‘new’, ‘all’}, optional
For the ‘new’ mode,
PSFPhotometry
is run in each iteration only on the new sources detected in the residual image. For the ‘all’ mode,PSFPhotometry
is run in each iteration on all the detected sources (from all previous iterations) on the original, unsubtracted, data. For the ‘all’ mode, a sourcegrouper
must be input. See the Notes section for more details.- 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 only for the first iteration.- sub_shape
None
, int, or length-2 array_like The rectangular shape around the center of a star that will be used when subtracting the fitted PSF models. If
sub_shape
is a scalar then a square shape of sizesub_shape
will be used. Ifsub_shape
has two elements, they must be in(ny, nx)
order. Each element ofsub_shape
must be an odd number. IfNone
, thensub_shape
will be defined by the model bounding box. This keyword must be specified if the model does not have abounding_box
attribute.- 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 data that will be fit for each source is defined by the
fit_shape
parameter. A cutout will be made around the initial center of each source with a shape defined byfit_shape
. The PSF model will be fit to the data in this region. The cutout region that is fit does not shift if the source center shifts during the fit iterations. Therefore, the initial source positions should be close to the true source positions. One way to ensure this is to use afinder
to identify sources in the data.If the fitted positions are significantly different from the initial positions, one can rerun the
PSFPhotometry
class using the fit results as the inputinit_params
, which will change the fitted cutout region for each source. After callingPSFPhotometry
on the data, it will have afit_params
attribute containing the fitted model parameters. This table can be used as theinit_params
input in a subsequent call toPSFPhotometry
.If the returned model parameter errors are NaN, then either the fit did not converge, the model parameter was fixed, or the input
fitter
did not return parameter errors. For the later case, one can try a different fitter that may return parameter errors (e.g.,astropy.modeling.fitting.DogBoxLSQFitter
orastropy.modeling.fitting.LMLSQFitter
).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.This class has two modes of operation: ‘new’ and ‘all’. For both modes,
PSFPhotometry
is first run on the data, a residual image is created, and the source finder is run on the residual image to detect any new sources.In the ‘new’ mode,
PSFPhotometry
is then run on the residual image to fit the PSF model to the new sources. The process is repeated until no new sources are detected or a maximum number of iterations is reached.In the ‘all’ mode, a new source list combining the sources from first
PSFPhotometry
run and the new sources detected in the residual image is created.PSFPhotometry
is then run on the original, unsubtracted, data with this combined source list. This allows the sourcegrouper
(which is required for the ‘all’ mode) to combine close sources to be fit simultaneously, improving the fit. Again, the process is repeated until no new sources are detected or a maximum number of iterations is reached.Care should be taken in defining the star groups. Simultaneously fitting very large star groups is computationally expensive and error-prone. Internally, source grouping requires the creation of a compound Astropy model. Due to the way compound Astropy models are currently constructed, large groups also require excessively large amounts of memory; this will hopefully be fixed in a future Astropy version. A warning will be raised if the number of sources in a group exceeds 25.
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 model parameters (e.g., x, y, flux) for each source only for the first iteration. If the x and y values are not input, then the
finder
will be used for all iterations. If the flux values are not input, then the initial fluxes will be measured using theaperture_radius
keyword. 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
.If the PSF model has additional free parameters that are fit, they can be included in the table. The column names must match the parameter names in the PSF model. They can also be suffixed with either the “_init” or “_fit” suffix. The suffix search order is “_init”, “” (no suffix), and “_fit”. For example, if the PSF model has an additional parameter named “sigma”, then the allowed column names are: “sigma_init”, “sigma”, and “sigma_fit”. If the column name is not found in the table, then the default value from the PSF model will be used. The default values from the PSF model will also be used for all iterations after the first.
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.
- 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 sourceiter_detected
: the iteration number in which the source was detectedx_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 initial central pixel value divided by the fit flux. NaN values indicate that the central pixel was masked.flags
: bitwise flag values1 : 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
32 : the fit x or y position is at the bounded value
- table
- make_model_image(shape, *, psf_shape=None, 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, optional
The shape of the region around the center of the fit model to render in the output image. If
psf_shape
is a scalar integer, then a square shape of sizepsf_shape
will be used. IfNone
, then the bounding box of the model will be used. This keyword must be specified if the model does not have abounding_box
attribute.- 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=None, 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, optional
The shape of the region around the center of the fit model to subtract. If
psf_shape
is a scalar integer, then a square shape of sizepsf_shape
will be used. IfNone
, then the bounding box of the model will be used. This keyword must be specified if the model does not have abounding_box
attribute.- 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 the fit PSF models minus the optional``local_bkg``.
- array2D