EPSFBuilder#

class photutils.psf.EPSFBuilder(*, oversampling=4, shape=None, smoothing_kernel='quartic', sigma_clip=<default: SigmaClip(sigma=3.0, maxiters=10)>, recentering_func=<function centroid_com>, recentering_boxsize=(5, 5), recentering_maxiters=20, center_accuracy=0.001, fitter=None, fit_shape=5, fitter_maxiters=100, maxiters=10, progress_bar=True)[source]#

Bases: object

Class to build an effective PSF (ePSF).

See Anderson and King 2000 (PASP 112, 1360) and Anderson 2016 (WFC3 ISR 2016-12) for details.

Parameters:

oversamplingint or array_like (int): The integer oversampling factor(s) of the output ePSF relative to the input stars along each axis. If oversampling is a scalar then it will be used for both axes. If oversampling has two elements, they must be in (y, x) order.
shapefloat, tuple of two floats, or None, optional: The (ny, nx) shape of the output ePSF. If the input shape is even along any axis, it will be made odd by adding one. If the shape is None, it will be derived from the sizes of the input stars and the ePSF oversampling factor. The output ePSF will always have odd sizes along both axes to ensure a well-defined central pixel.
smoothing_kernel{‘quartic’, ‘quadratic’}, 2D ndarray, or None: The smoothing kernel to apply to the ePSF during each iteration step. The predefined 'quartic' and 'quadratic' kernels are derived from fourth and second degree polynomials, respectively. Alternatively, a custom 2D array can be input. If None then no smoothing will be performed.
sigma_clipastropy.stats.SigmaClip instance, optional: A SigmaClip object that defines the sigma clipping parameters used to determine which pixels are ignored when stacking the ePSF residuals in each iteration step. If None then no sigma clipping will be performed.
recentering_funccallable, optional: A callable object that is used to calculate the centroid of a 2D array. The callable must accept a 2D ndarray, have a mask keyword and optionally an error keyword. The callable object must return a tuple of (x, y) centroids.
recentering_boxsizefloat or tuple of two floats, optional: The size (in pixels) of the box used to calculate the centroid of the ePSF during each build iteration. The size is in the input star (i.e., undersampled) pixel space; it is automatically scaled by the oversampling factor when applied to the oversampled ePSF grid. If a single integer number is provided, then a square box will be used. If two values are provided, then they must be in (ny, nx) order. recentering_boxsize must have odd values and be greater than or equal to 3 for both axes.
recentering_maxitersint, optional: The maximum number of recentering iterations to perform during each ePSF build iteration.
center_accuracyfloat, optional: The desired accuracy for the centers of stars. The building iterations will stop if the centers of all the stars change by less than center_accuracy pixels between iterations. All stars must meet this condition for the building iterations to stop.
fitterFitter or EPSFFitter, optional: A Fitter object used to fit the ePSF to stars. If None, then the default TRFLSQFitter will be used.

Deprecated since version 3.0: Passing an EPSFFitter instance is deprecated; use the fitter, fit_shape, and fitter_maxiters parameters instead.
fit_shapeint, tuple of int, or None, optional: The size (in pixels) of the box centered on the star to be used for ePSF fitting. This allows using only a small number of central pixels of the star (i.e., where the star is brightest) for fitting. If fit_shape is a scalar then a square box of size fit_shape will be used. If fit_shape has two elements, they must be in (ny, nx) order. fit_shape must have odd values and be greater than or equal to 3 for both axes. If None, the fitter will use the entire star image.
fitter_maxitersint, optional: The maximum number of iterations in which the fitter is called for each star. The value can be increased if the fit is not converging. This parameter is passed to the fitter if it supports the maxiter parameter and ignored otherwise.
maxitersint, optional: The maximum number of ePSF building iterations to perform.
progress_barbool, option: Whether to print the progress bar during the build iterations. The progress bar requires that the tqdm optional dependency be installed.

Methods Summary

`__call__`(stars)	Build an ePSF from input stars.
`build_epsf`(stars, *[, epsf])	Build iteratively an ePSF from star cutouts.

Methods Documentation

__call__(stars)[source]#

Build an ePSF from input stars.

Parameters:

starsEPSFStars: The stars used to build the ePSF.

Returns:

resultEPSFBuildResult: The result of the ePSF building process.

build_epsf(stars, *, epsf=None)[source]#

Build iteratively an ePSF from star cutouts.

This method builds an ePSF from an initial model when epsf is provided, or from scratch when epsf is None. In the latter case, it is equivalent to invoking an EPSFBuilder instance on the input stars.

Parameters:

starsEPSFStars object: The stars used to build the ePSF.
epsfImagePSF object, optional: The initial ePSF model. If None, then the ePSF will be built from scratch.

Returns:

resultEPSFBuildResult or tuple: The ePSF building results. Returns an EPSFBuildResult object with detailed information about the building process. For backward compatibility, the result can be unpacked as a tuple: (epsf, fitted_stars) = epsf_builder(stars).

Notes

The structured result object contains: - epsf: The final constructed ePSF - fitted_stars: Stars with updated centers/fluxes - iterations: Number of iterations performed - converged: Whether convergence was achieved - final_center_accuracy: Final center movement accuracy - n_excluded_stars: Number of stars excluded due to fit failures - excluded_star_indices: Indices of excluded stars