EPSFBuildResults#

class photutils.psf.EPSFBuildResults(epsf: ImagePSF, fitted_stars: EPSFStars, iterations: int, converged: bool, final_center_accuracy: float, n_excluded_stars: int, excluded_star_indices: list, smoothing_kernel: ndarray | None = None, fit_shape: tuple | None = None, final_converged_fraction: float | None = None, iteration_epsfs: list | None = None, iteration_info: Table | None = None, initial_epsf: ndarray | None = None)[source]#

Bases: object

Container for ePSF building results.

This class provides structured access to the results of the ePSF building process, including convergence information and diagnostic data that can help users understand and validate the building process.

Attributes:

epsfImagePSF object: The final constructed ePSF model.
fitted_starsEPSFStars object: The input stars with updated centers and fluxes derived from fitting the final ePSF.
iterationsint: The number of building iterations performed. This will be <= maxiters specified in EPSFBuilder. The refinement iterations are not counted.
convergedbool: Whether the building process converged based on the center accuracy criterion. True if at least the converged_fraction of the successfully fitted stars moved by less than the specified center accuracy between the final iterations. If the ePSF was refined, converged, final_center_accuracy, and final_converged_fraction are measured in the last refinement iteration, so that they describe the returned fitted_stars. A build whose building iterations converged can therefore report False. The first refit of the refinement moves some stars by more than the center accuracy, because the ePSF changes when the refinement restores its signal near one cycle per pixel. This mostly happens with a single refinement iteration (refinement_iters=1). The star centers settle again within a few refinement iterations. With different oversampling factors along the two axes they can need more refinement iterations than the default (about 10 in tests). The converged column of iteration_info gives the convergence of every building and refinement iteration.
final_center_accuracyfloat: The maximum center displacement in the final iteration, in pixels, over all of the successfully fitted stars. This includes the stars that the converged_fraction of the builder allows to remain unconverged, so it can be much larger than the center_accuracy for a converged build. Use it together with final_converged_fraction to assess the convergence quality.
final_converged_fractionfloat: The fraction of the successfully fitted stars whose centers changed by less than center_accuracy in the final iteration. The build is converged when this fraction is at least the converged_fraction of the builder.
n_excluded_starsint: The number of individual stars (including those from linked stars) that were excluded from fitting due to repeated fit failures.
excluded_star_indiceslist: Indices of stars that were excluded from fitting during the building process. These correspond to positions in the flattened star list (stars.all_stars).
smoothing_kernel2D ndarray or None: The smoothing kernel applied in the final iteration, or None if no smoothing was applied. This includes the kernel chosen by smoothing_kernel='auto', which can be input as a fixed smoothing_kernel to reproduce the build.
fit_shapetuple or None: The (ny, nx) shape of the fitting box used in the final iteration, or None if the entire star cutouts were fit. This includes the shape chosen by fit_shape='auto'.
iteration_epsfslist of 2D ndarray: The ePSF image after each iteration, in order. The building iterations come first, followed by the refinement iterations (if any). Each image has the shape and normalization of epsf.data. The images can be used to check how the ePSF evolved and whether it stopped changing. See also plot_iterations. The smoothing of the wings of the final ePSF (see the wing_smoothing keyword of EPSFBuilder) is not an iteration, so the last image is the ePSF before its wings were smoothed, and it differs from epsf.data in the wings if that smoothing changed the ePSF.
iteration_infoTable: A table with one row for each image in iteration_epsfs. The columns are the iteration number (iteration, starting at 1), the kind of iteration (stage, 'build' or 'refine'), whether the star centers had converged in that iteration (converged), the fraction of the successfully fitted stars whose centers moved by less than the center accuracy in that iteration (converged_fraction), the largest center movement in pixels (max_center_shift), the number of stars whose fit failed (n_fit_failed), and the largest absolute change of the ePSF image from the previous iteration as a fraction of the ePSF peak (max_epsf_change). The change of the first iteration is measured from initial_epsf, or from an empty ePSF if the ePSF was built from scratch. The last row gives the converged, final_converged_fraction, and final_center_accuracy values of the results. The last 'build' row tells whether the building iterations converged, which converged alone does not when the ePSF was refined.
initial_epsf2D ndarray or None: The image of the input ePSF that the build started from, or None if the ePSF was built from scratch.

Notes

This result object maintains backward compatibility by implementing tuple unpacking, so existing code like:

epsf, stars = epsf_builder(stars)

will continue to work unchanged. The additional information is available as attributes for users who want more detailed results.

Examples

>>> from photutils.psf import EPSFBuilder
>>> epsf_builder = EPSFBuilder(oversampling=4)
>>> result = epsf_builder(stars)
>>> print(result.iterations)
>>> print(result.final_center_accuracy)
>>> print(result.n_excluded_stars)

Attributes Summary

`final_converged_fraction`
`fit_shape`
`initial_epsf`
`iteration_epsfs`
`iteration_info`
`smoothing_kernel`

Methods Summary

plot_iterations(*[, iterations, figsize, ...])

Plot the ePSF after each iteration and its change from the previous iteration.

Attributes Documentation

final_converged_fraction: float | None = None#

fit_shape: tuple | None = None#

initial_epsf: ndarray | None = None#

iteration_epsfs: list | None = None#

iteration_info: Table | None = None#

smoothing_kernel: ndarray | None = None#

Methods Documentation

plot_iterations(*, iterations=None, figsize=None, cmap='viridis', diff_cmap='RdBu_r')[source]#

Plot the ePSF after each iteration and its change from the previous iteration.

The figure has one row for each iteration. The left panel shows the ePSF with a logarithmic stretch that is common to all the rows. The right panel shows the difference from the ePSF of the previous iteration, as a fraction of the peak of the final ePSF, with a symmetric linear stretch of its own. For the first iteration the right panel shows the difference from initial_epsf, or the ePSF itself if the ePSF was built from scratch.

If the wings of the final ePSF were smoothed (see the wing_smoothing keyword of EPSFBuilder), the figure has one more row at the bottom. It shows the returned ePSF and its difference from the ePSF of the last iteration, which is the change made by the wing smoothing. This row is always plotted, whatever the value of iterations.

Parameters:

iterationsint, 1D array_like of int, or None, optional: The iteration numbers (starting at 1, as in the iteration column of iteration_info) to plot. If None, all the iterations are plotted. The figure has one row per iteration, so select a few iterations to get a compact figure.
figsizetuple of 2 float or None, optional: The figure (width, height) in inches. If None, the figure is 7 inches wide and 2.6 inches tall per row.
cmapstr or matplotlib.colors.Colormap, optional: The colormap of the ePSF panels.
diff_cmapstr or matplotlib.colors.Colormap, optional: The colormap of the difference panels.

Returns:

figmatplotlib.figure.Figure: The figure.

Notes

This method returns a figure object. If you are using this method in a script, you will need to call fig.show() to display the figure. If you are using this method in a Jupyter notebook, the figure will be displayed automatically.

When in a notebook, if you do not store the return value of this function, the figure will be displayed twice due to the REPL automatically displaying the return value of the last function call. Alternatively, you can append a semicolon to the end of the function call to suppress the display of the return value.