BasicPSFPhotometry

class photutils.psf.BasicPSFPhotometry(group_maker, bkg_estimator, psf_model, fitshape, *, finder=None, fitter=<astropy.modeling.fitting.LevMarLSQFitter object>, aperture_radius=None, extra_output_cols=None, subshape=None)

Bases: object

Deprecated since version 1.9.0: The BasicPSFPhotometry class is deprecated and may be removed in a future version. Use photutils.psf.PSFPhotometry instead.

This class implements a PSF photometry algorithm that can find sources in an image, group overlapping sources into a single model, fit the model to the sources, and subtracting the models from the image. This is roughly equivalent to the DAOPHOT routines FIND, GROUP, NSTAR, and SUBTRACT. This implementation allows a flexible and customizable interface to perform photometry. For instance, one is able to use different implementations for grouping and finding sources by using group_maker and finder respectively. In addition, sky background estimation is performed by bkg_estimator.

Parameters:

group_makercallable or GroupStarsBase

group_maker should be able to decide whether a given star overlaps with any other and label them as belonging to the same group. group_maker receives as input an Table object with columns named as id, x_0, y_0, in which x_0 and y_0 have the same meaning of xcentroid and ycentroid. This callable must return an Table with columns id, x_0, y_0, and group_id. The column group_id should contain integers starting from 1 that indicate which group a given source belongs to. See, e.g., DAOGroup.

bkg_estimatorcallable, instance of any BackgroundBase subclass, or None

bkg_estimator should be able to compute either a scalar background or a 2D background of a given 2D image. See, e.g., MedianBackground. If None, no background subtraction is performed.

psf_modelastropy.modeling.Fittable2DModel instance

PSF or PRF model to fit the data. Could be one of the models in this package like IntegratedGaussianPRF or any other suitable 2D model. This object needs to identify three parameters (position of center in x and y coordinates and the flux) in order to set them to suitable starting values for each fit. The names of these parameters should be given as x_0, y_0 and flux. prepare_psf_model can be used to prepare any 2D model to match this assumption.

fitshapeint or length-2 array_like

Rectangular shape around the center of a star that will be used to define the PSF-fitting region. If fitshape is a scalar then a square shape of size fitshape will be used. If fitshape has two elements, they must be in (ny, nx) order. Each element of fitshape must be an odd number.

findercallable or instance of any StarFinderBase subclasses or None

finder should be able to identify stars, i.e., compute a rough estimate of the centroids, in a given 2D image. finder receives as input a 2D image and returns an Table object which contains columns with names: id, xcentroid, ycentroid, and flux. In which id is an integer-valued column starting from 1, xcentroid and ycentroid are center position estimates of the sources and flux contains flux estimates of the sources. See, e.g., DAOStarFinder. If finder is None, initial guesses for positions of objects must be provided.

fitterFitter instance

Fitter object used to compute the optimized centroid positions and/or flux of the identified sources. See fitting for more details on fitters.

aperture_radiusNone or float

The radius (in units of pixels) used to compute initial estimates for the fluxes of sources. aperture_radius must be set if initial flux guesses are not input to the photometry class via the init_guesses keyword. For tabular PSF models (e.g., an EPSFModel), you must input the aperture_radius keyword. For analytical PSF models, alternatively you may define a FWHM attribute on your input psf_model.

extra_output_colslist of str, optional

List of additional columns for parameters derived by any of the intermediate fitting steps (e.g., finder), such as roundness or sharpness.

subshapeNone, int, or length-2 array_like

Rectangular shape around the center of a star that will be used to define the PSF-subtraction region. If None, then fitshape will be used. If subshape is a scalar then a square shape of size subshape will be used. If subshape has two elements, they must be in (ny, nx) order. Each element of subshape must be an odd number.

Notes

Note that an ambiguity arises whenever finder and init_guesses (keyword argument for do_photometry) are both not None. In this case, finder is ignored and initial guesses are taken from init_guesses. In addition, an warning is raised to remind the user about this behavior.

If there are problems with fitting large groups, change the parameters of the grouping algorithm to reduce the number of sources in each group or input a star_groups table that only includes the groups that are relevant (e.g., manually remove all entries that coincide with artifacts).

References

[1] Stetson, Astronomical Society of the Pacific, Publications,

(ISSN 0004-6280), vol. 99, March 1987, p. 191-222. Available at: https://ui.adsabs.harvard.edu/abs/1987PASP…99..191S/abstract

Deprecated since version 1.9.0: The BasicPSFPhotometry class is deprecated and may be removed in a future version. Use photutils.psf.PSFPhotometry instead.

Attributes Summary

aperture_radius
fitshape
subshape

Methods Summary

__call__(image, *[, mask, init_guesses, ...])	Perform PSF photometry.
do_photometry(image, *[, mask, ...])	Perform PSF photometry in image.
get_residual_image()	Return an image that is the result of the subtraction between the original image and the fitted sources.
nstar(image, star_groups, *[, mask, ...])	Fit, as appropriate, a compound or single model to the given star_groups.
set_aperture_radius()	Set the fallback aperture radius for initial flux calculations in cases where no flux is supplied for a given star.

Attributes Documentation

aperture_radius

fitshape

subshape

Methods Documentation

__call__(image, *, mask=None, init_guesses=None, progress_bar=False, uncertainty=None)

Perform PSF photometry. See do_photometry for more details including the __call__ signature.

do_photometry(image, *, mask=None, init_guesses=None, progress_bar=False, uncertainty=None)

Perform PSF photometry in image.

This method assumes that psf_model has centroids and flux parameters which will be fitted to the data provided in image. A compound model, in fact a sum of psf_model, will be fitted to groups of stars automatically identified by group_maker. Also, image is not assumed to be background subtracted. If init_guesses are not None then this method uses init_guesses as initial guesses for the centroids. If the centroid positions are set as fixed in the PSF model psf_model, then the optimizer will only consider the flux as a variable.

Parameters:

image2D ndarray

Image to perform photometry. Invalid data values (i.e., NaN or inf) are automatically ignored.

init_guessesTable

Table which contains the initial guesses (estimates) for the set of parameters. Columns ‘x_0’ and ‘y_0’ which represent the positions (in pixel coordinates) for each object must be present. ‘flux_0’ can also be provided to set initial fluxes. If ‘flux_0’ is not provided, aperture photometry is used to estimate initial values for the fluxes. Additional columns of the form ‘<parametername>_0’ will be used to set the initial guess for any parameters of the psf_model model that are not fixed. If init_guesses supplied with extra_output_cols the initial values are used; if the columns specified in extra_output_cols are not given in init_guesses then NaNs will be returned.

mask2D bool ndarray, optional

A boolean mask with the same shape as image, where a True value indicates the corresponding element of image is masked.

progress_barbool, optional

Whether to display a progress bar when fitting the star 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.

uncertainty2D ndarray, optional

Stddev uncertainty for each element in image.

Returns:

output_tabTable or None

Table with the photometry results, i.e., centroids and fluxes estimations and the initial estimates used to start the fitting process. Uncertainties on the fitted parameters are reported as columns called <paramname>_unc provided that the fitter object contains a dictionary called fit_info with the key param_cov, which contains the covariance matrix. If param_cov is not present, uncertanties are not reported.

get_residual_image()

Return an image that is the result of the subtraction between the original image and the fitted sources.

Returns:

residual_image2D ndarray

The 2D residual image.

nstar(image, star_groups, *, mask=None, progress_bar=False, uncertainty=None)

Fit, as appropriate, a compound or single model to the given star_groups. Groups are fitted sequentially from the smallest to the biggest. In each iteration, image is subtracted by the previous fitted group.

Parameters:

image2D ndarray

Background-subtracted image. Invalid data values (i.e., NaN or inf) are automatically ignored.

star_groupsTable

This table must contain the following columns: id, group_id, x_0, y_0, flux_0. x_0 and y_0 are initial estimates of the centroids and flux_0 is an initial estimate of the flux. Additionally, columns named as <param_name>_0 are required if any other parameter in the psf model is free (i.e., the fixed attribute of that parameter is False).

mask2D bool ndarray, optional

A boolean mask with the same shape as image, where a True value indicates the corresponding element of image is masked.

progress_barbool, optional

Use a progress bar to show progress over the star 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.

uncertainty2D ndarray, optional

Stddev uncertainty for each element in image.

Returns:

result_tabQTable

Astropy table that contains photometry results.

image2D ndarray

Residual image.

set_aperture_radius()

Set the fallback aperture radius for initial flux calculations in cases where no flux is supplied for a given star.