PsfBuild

Build PSF from star catalog

Space Telescope Science Institute

Synopsis

Build PSF models from an image and star catalog. Selects optimal PSF stars from the input catalog and builds Gaussian, Moffat, and summed PSF models.

Command Line Usage

Usage: PsfBuild [-out root] image_file star_catalog

where star_catalog is typically the all_stars.fits output from StarFind.

Description

This module handles all PSF-related decisions:

Selects optimal stars for PSF construction based on SNR, FWHM, eccentricity
Writes the selected PSF stars to {prefix}_psf_stars.fits
Builds Gaussian, Moffat, and summed PSF models
Writes PSF models to FITS files

Primary Routines

select_psf_stars: Select optimal stars for PSF construction from photometry table.
do_one: Build PSF from an image and star catalog.
quick_psf_build: Quick function to build all PSF models.

Notes

History:

251210 ksl Coding begun 251222 ksl Added to kred 260113 ksl Moved select_psf_stars from StarFind; PsfBuild now handles all PSF decisions

Classes

PSFBuilder

Build PSF models from FITS images and star positions.

Functions

`do_one`(image_file, star_file[, prefix, max_stars, weights])	Build PSF from an image and star catalog.
`quick_psf_build`(fits_file, star_table[, stamp_size, ...])	Quick function to build all PSF models.
`select_psf_stars`(phot_table[, max_stars, weights, verbose])	Select optimal stars for PSF construction using percentile-based quality scoring.
`steer`(argv)	This is generally just a steering routine

Module Contents

class PsfBuild.PSFBuilder(fits_file, star_table, stamp_size=25, normalize='peak')

Build PSF models from FITS images and star positions.

Parameters

fits_filestr or HDUList: Path to FITS file or astropy HDUList object
star_tableastropy.Table: Table with star positions (must contain ‘xcenter’ and ‘ycenter’ columns)
stamp_sizeint, optional: Size of stamp to extract around each star (default: 25)
normalizestr, optional: Normalization method: ‘peak’ (default), ‘sum’, or ‘none’

build_all_psfs()

Build all three PSF models.

Returns

resultsdict: Dictionary containing all PSF models and parameters, or None if no stamps available

build_gaussian_psf()

Build elliptical Gaussian PSF model.

Returns

paramsdict: Fitted parameters: amplitude, x0, y0, sigma_x, sigma_y, theta, fwhm_x, fwhm_y
modelndarray: 2D array of the fitted PSF model (normalized)

build_moffat_psf()

Build elliptical Moffat PSF model.

Returns

paramsdict: Fitted parameters: amplitude, alpha, beta, ellipticity, theta, fwhm
modelndarray: 2D array of the fitted PSF model (normalized)

build_summed_psf(subtract_background=True)

Build empirical PSF by summing star stamps.

Parameters

subtract_backgroundbool, optional: Subtract local background from each stamp (default: True)

Returns

psfndarray: 2D array of the summed PSF (normalized)

extract_stamps(filter_outliers=True, sigma_clip=3.0)

Extract postage stamps around each star.

Parameters

filter_outliersbool, optional: Remove stamps with unusual flux levels (default: True)
sigma_clipfloat, optional: Sigma clipping threshold for outlier removal (default: 3.0)

Returns

stampslist of dict: List of stamps, each containing ‘data’, ‘x’, ‘y’, ‘xcenter’, ‘ycenter’

normalize = 'peak'

psf_gaussian = None

psf_moffat = None

psf_summed = None

save_psfs(output_prefix='psf')

Save PSF models to FITS files.

Parameters

output_prefixstr, optional: Prefix for output files (default: ‘psf’)

stamp_size = 25

stamps = None

star_table

PsfBuild.do_one(image_file, star_file, prefix='', max_stars=1000, weights=None)

Build PSF from an image and star catalog.

Parameters

image_filestr: Path to FITS image file.
star_filestr: Path to star catalog (typically all_stars.fits from StarFind).
prefixstr, optional: Output filename prefix. If empty, derived from image_file.
max_starsint, optional: Maximum number of stars to use for PSF. Default: 1000.
weightsdict, optional: Weights for quality score metrics. See select_psf_stars for details.

PsfBuild.quick_psf_build(fits_file, star_table, stamp_size=25, normalize='peak', output_prefix=None)

Quick function to build all PSF models.

Parameters

fits_filestr: Path to FITS file
star_tableastropy.Table: Table with star positions (xcenter, ycenter columns)
stamp_sizeint, optional: Size of PSF stamp (default: 25)
normalizestr, optional: Normalization method: ‘peak’ (default), ‘sum’, or ‘none’
output_prefixstr, optional: If provided, save PSFs to files with this prefix

Returns

resultsdict: Dictionary containing all PSF models and parameters

Example

>>> from astropy.table import Table
>>> star_table = Table.read('stars.fits')
>>> results = quick_psf_build('image.fits', star_table, normalize='peak')
>>> print(f"Gaussian FWHM: {results['gaussian']['params']['fwhm_x']:.2f}")

PsfBuild.select_psf_stars(phot_table, max_stars=100, weights=None, verbose=True)

Select optimal stars for PSF construction using percentile-based quality scoring.

Uses a weighted combination of quality metrics to rank stars, rather than hard cutoffs that may reject all stars in difficult fields.

Parameters

phot_tableastropy.table.Table: Output from do_forced_photometry with add_psf_metrics=True. Required columns: SNR, FWHM, Eccentricity, BkgContam, Concentration
max_starsint: Maximum number of PSF stars to return (default: 100)
weightsdict, optional: Weights for each metric. Default weights emphasize SNR and FWHM consistency: {‘snr’: 0.35, ‘fwhm’: 0.25, ‘ecc’: 0.20, ‘bkg’: 0.10, ‘conc’: 0.10}
verbosebool: Print diagnostic statistics (default: True)

Returns

psf_starsastropy.table.Table: Subset of highest quality stars, sorted by quality score

PsfBuild.steer(argv)

This is generally just a steering routine

Usage: PsfBuild [-out root] image_file star_catalog