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 run PSFPhotometry 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, and flux, 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 from make_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 size fit_shape will be used. If fit_shape has two elements, they must be in (ny, nx) order. Each element of fit_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 a Table containing the x and y centroid positions. These positions are used as the starting points for the PSF fitting. The allowed x column names are (same suffix for y): 'x_init', 'xinit', 'x', 'x_0', 'x0', 'xcentroid', 'x_centroid', 'x_peak', 'xcen', 'x_cen', 'xpos', 'x_pos', 'x_fit', and 'xfit'. If None, then the initial (x, y) model positions must be input using the init_params keyword when calling the class. The (x, y) values in init_params override this keyword only for the first iteration. If this class is run on an image that has units (i.e., a Quantity array), then certain finder keywords (e.g., threshold) must have the same units. Please see the documentation for the specific finder class for more information.

grouperSourceGrouper or callable or None, 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. If None, then no grouping is performed, i.e. each source is fit independently. The group_id values in init_params override this keyword only for the first iteration. A warning is raised if any group size is larger than 25 sources.

fitterFitter, 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_boundsNone, 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. If None, then no bounds are applied. Either value can also be None 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 source grouper must be input. See the Notes section for more details.

localbkg_estimatorLocalBackground or None, optional

The object used to estimate the local background around each source. If None, then no local background is subtracted. The local_bkg values in init_params override this keyword. This option should be used with care, especially in crowded fields where the fit_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_shapeNone, 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 size sub_shape will be used. If sub_shape has two elements, they must be in (ny, nx) order. Each element of sub_shape must be an odd number. If None, then sub_shape will be defined by the model bounding box. This keyword must be specified if the model does not have a bounding_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.

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 by fit_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 a finder 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 input init_params, which will change the fitted cutout region for each source. After calling PSFPhotometry on the data, it will have a fit_params attribute containing the fitted model parameters. This table can be used as the init_params input in a subsequent call to PSFPhotometry.

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 or astropy.modeling.fitting.LMLSQFitter).

The local background value around each source is optionally estimated using the localbkg_estimator or obtained from the local_bkg column in the input init_params table. This local background is then subtracted from the data over the fit_shape region for each source before fitting the PSF model. For sources where their fit_shape regions overlap, the local background will effectively be subtracted twice in the overlapping fit_shape regions, even if the source grouper is input. This is not an issue if the sources are well-separated. However, for crowded fields, please use the localbkg_estimator (or local_bkg column in init_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 source grouper (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 a True value indicates the corresponding element of data 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 (see calc_total_error) . error must have the same shape as the input data. If data is a Quantity array, then error must also be a Quantity array with the same units.

init_paramsTable or None, 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 the aperture_radius keyword. Note that the initial flux values refer to the model flux parameters and are not corrected for local background values (computed using localbkg_estimator or input in a local_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, and xfit.

  • y_init, yinit, y, y_0, y0, ycentroid, y_centroid, y_peak, ycen, y_cen, ypos, y_pos, y_fit, and yfit.

  • flux_init, fluxinit, flux, flux_0, flux0, flux_fit, fluxfit, source_sum, segment_flux, and kron_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 a Quantity array, then the initial flux values in this table must also must also have compatible units.

Returns:
tableQTable

An astropy table with the PSF-fitting results. The table will contain the following columns:

  • id : unique identification number for the source

  • group_id : unique identification number for the source group

  • group_size : the total number of sources that were simultaneously fit along with the given source

  • iter_detected : the iteration number in which the source was detected

  • x_init, x_fit, x_err : the initial, fit, and error of the source x center

  • y_init, y_fit, y_err : the initial, fit, and error of the source y center

  • flux_init, flux_fit, flux_err : the initial, fit, and error of the source flux

  • npixfit : the number of unmasked pixels used to fit the source

  • qfit : a quality-of-fit metric defined as the absolute value of the sum of the fit residuals divided by the fit flux

  • cfit : 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 values

    • 1 : one or more pixels in the fit_shape region were masked

    • 2 : 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

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 size psf_shape will be used. If None, then the bounding box of the model will be used. This keyword must be specified if the model does not have a bounding_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 the psf_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.

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 size psf_shape will be used. If None, then the bounding box of the model will be used. This keyword must be specified if the model does not have a bounding_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 the psf_shape of sources overlap will have the local background subtracted multiple times.

Returns:
array2D ndarray

The residual image of the data minus the fit PSF models minus the optional``local_bkg``.