stdpipe.photometry_psf module

Routines for PSF photometry using photutils.

This module provides PSF fitting photometry as an alternative to aperture photometry, which is more accurate for point sources especially in crowded fields or when PSF wings are significant.

class stdpipe.photometry_psf.GradientLocalBackground(inner_radius, outer_radius, order=1, sigma=3.0, maxiters=3)

Bases: LocalBackground

Local background estimator using gradient fitting with sigma-clipping.

Inherits from photutils.background.LocalBackground but overrides the estimation method to fit polynomial gradients instead of taking mean/median.

Instead of taking mean/median of annulus (assumes flat background), fits a polynomial model to the annulus and evaluates at source position. Includes sigma-clipping to reject outliers (contaminating sources).

This dramatically reduces biases with background gradients: - Linear gradients: ~20× improvement (19% → <1% error) - Quadratic gradients: ~100-400× improvement (-415% → <5% error) - Sigma-clipping provides robustness in crowded fields

Parameters:

inner_radiusfloat

Inner radius of annulus in pixels

outer_radiusfloat

Outer radius of annulus in pixels

orderint, optional

Polynomial order: 0 = constant (mean, equivalent to standard LocalBackground) 1 = plane (linear gradient, recommended) 2 = quadratic surface (complex gradients) Default is 1.

sigmafloat, optional

Sigma threshold for sigma-clipping outliers. Default is 3.0. Higher values are more permissive, lower values reject more outliers.

maxitersint, optional

Maximum number of sigma-clipping iterations. Default is 3.

Methods

__call__(data, x, y[, mask])	Estimate local background at position(s) (x, y).
to_aperture(x, y)	Return a ~photutils.aperture.CircularAnnulus instance representing the local background annulus at the given positions.

stdpipe.photometry_psf.measure_objects_psf(obj, image, psf=None, psf_size=None, fwhm=None, mask=None, bg=None, err=None, gain=None, bg_size=64, bkgann=None, bkg_order=1, sn=None, fit_shape='circular', fit_size=None, maxiters=3, recentroid=True, keep_negative=True, get_bg=False, use_position_dependent_psf=False, group_sources=True, grouper_radius=None, verbose=False)

PSF photometry at the positions of already detected objects using photutils.

Performs PSF fitting photometry which is more accurate than aperture photometry, especially for point sources in crowded fields or when accurate flux measurement of PSF wings is important.

This function will estimate and subtract the background unless external background estimation (bg) is provided, and use user-provided noise map (err) if requested.

If a PSF model is not provided, a simple Gaussian PSF will be constructed based on the fwhm parameter or estimated from the data.

Parameters:

obj~astropy.table.Table

Table with initial object detections to be measured. Must have ‘x’ and ‘y’ columns.

image~numpy.ndarray

Input image as a 2D NumPy array.

psfphotutils PSF model, dict, or None, optional

PSF model to use. Can be a photutils PSF model (e.g., IntegratedGaussianPRF, FittableImageModel), a PSFEx PSF structure from stdpipe.psf.run_psfex(), or None (will create Gaussian PSF based on fwhm).

psf_sizeint or None, optional

Size of the PSF model in pixels. If None, will be estimated from PSF or set to 5*fwhm.

fwhmfloat or None, optional

Full width at half maximum in pixels. Used if PSF model is not provided, or to estimate psf_size. If None, will be estimated from obj[‘fwhm’] if available.

mask~numpy.ndarray or None, optional

Image mask as a boolean array (True values will be masked).

bg~numpy.ndarray or None, optional

If provided, use this background (same shape as input image) instead of automatically computed one.

err~numpy.ndarray or None, optional

Image noise map to be used instead of automatically computed one.

gainfloat or None, optional

Image gain in e-/ADU, used to build image noise model.

bg_sizeint, optional

Background grid size in pixels.

bkgannlist of float or None, optional

Background annulus for local background estimation, [inner_radius, outer_radius] in pixels. If None, no local background subtraction is performed (relies only on global Background2D subtraction). If set, uses gradient-aware local background fitting to handle non-uniform backgrounds. Note: radii are NOT scaled by FWHM (unlike measure_objects).

bkg_orderint, optional

Polynomial order for local background fitting. 0 = constant (mean), 1 = plane (linear gradient, recommended), 2 = quadratic surface. Only used if bkgann is set.

snfloat or None, optional

Minimal S/N ratio for the object to be considered good. If set, all measurements with magnitude errors exceeding 1/sn will be discarded.

fit_shapestr, optional

Shape of fitting region. Options: ‘circular’ (default), ‘square’. Determines the aperture used for PSF fitting.

fit_sizeint or None, optional

Size of fitting region in pixels. If None, defaults to psf_size.

maxitersint, optional

Maximum number of iterations for PSF fitting.

recentroidbool, optional

If True, allow PSF position to vary during fitting (recommended).

keep_negativebool, optional

If False, measurements with negative fluxes will be discarded.

get_bgbool, optional

If True, the routine will also return estimated background and background noise images.

use_position_dependent_psfbool, optional

If True and PSF is a PSFEx model, use polynomial evaluation for position-dependent PSF (evaluates PSF at each source position).

group_sourcesbool, optional

If True, use grouped PSF fitting for overlapping sources. Fits nearby sources simultaneously for better accuracy in crowded fields.

grouper_radiusfloat or None, optional

Radius in pixels for grouping nearby sources. If None, defaults to 2*psf_size. Only used if group_sources is True.

verbosebool or callable, optional

Whether to show verbose messages during the run. May be either boolean, or a print-like function.

Returns:

result~astropy.table.Table or tuple

Copy of original table with flux, fluxerr, mag, magerr, x_psf, y_psf columns from PSF fitting. Also includes quality of fit columns: qfit_psf (fit quality, 0=good), cfit_psf (central pixel fit quality), flags_psf (photutils fit flags), npix_psf (number of unmasked pixels used in fit), and reduced_chi2_psf (reduced chi-squared, available in photutils >= 2.3.0). If get_bg is True, returns a tuple of (table, background, background_error).