IterativePSFPhotometry¶
- class photutils.psf.IterativePSFPhotometry(psf_model, fit_shape, finder, *, grouper=None, fitter=<astropy.modeling.fitting.LevMarLSQFitter object>, fitter_maxiters=100, maxiters=3, mode='new', localbkg_estimator=None, aperture_radius=None, sub_shape=None, progress_bar=False)[source]¶
Bases:
object
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_model
astropy.modeling.Fittable2DModel
The PSF model to fit to the data. The model needs to have three parameters named
x_0
,y_0
, andflux
, corresponding to the center (x, y) position and flux.- 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'
,'xcentroid'
,'x_centroid'
,'x_peak'
,'x'
,'xcen'
,'x_cen'
,'xpos'
,'x_pos'
,'x_0'
, and'x0'
. 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.- 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.- 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.- aperture_radiusfloat, optional
The radius of the circular aperture used to estimate the initial flux of each source. The
flux_init
values ininit_params
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
is set tofit_shape
.- 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_model
Notes
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.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 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
. If aQuantity
array, thendata
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 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 in using theaperture_radius
keyword. The input flux values will be used for the first iteration only. The allowed column names are:x_init
,xinit
,xcentroid
,x_centroid
,x_peak
,x
,xcen
,x_cen
,xpos
,x_pos
,x_0
, andx0
.y_init
,yinit
,ycentroid
,y_centroid
,y_peak
,y
,ycen
,y_cen
,ypos
,y_pos
, andy_0
, andy0
.flux_init
,flux
,source_sum
,segment_flux
, andkron_flux
.
The parameter names are searched in the input table in the above order, stopping at the first match.
- 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 groupiter_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 sourcegroup_size
: the total number of sources that were simultaneously fit along with the given 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
16 : the fitter parameter covariance matrix was not returned
- table
- make_model_image(shape, psf_shape)[source]¶
Create a 2D image from the fit PSF models and 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.
- Returns:
- array2D
ndarray
The rendered image from the fit PSF models.
- array2D
- make_residual_image(data, psf_shape)[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.
- data2D
- Returns:
- array2D
ndarray
The residual image of the
data
minus thelocal_bkg
minus the fit PSF models.
- array2D