decode_psf_flags#

photutils.psf.decode_psf_flags(flags, return_bit_values=False)[source]#

Decode PSF photometry bit flags into individual components.

This function takes integer flag values from PSF photometry results and returns a list of human-readable descriptions of the issues that occurred during fitting. This is useful for understanding what problems were encountered without needing to manually perform bitwise operations.

Parameters:
flagsint or array-like of int

Integer flag value(s) to decode. Each bit in the flag represents a specific condition that occurred during PSF fitting.

return_bit_valuesbool, optional

If True, return the decoded bit flags (integers) instead of the flag descriptions (strings). Default is False.

Returns:
decodedlist of str, list of int, list of list of str, or list of list of int

List of active flag names (or bit values), or list of lists if input is an array. Each string (or integer) represents a specific condition that was detected during PSF fitting. If no flags are set, an empty list is returned. Possible flag names are:

  • 'n_pixels_fit_partial' : bit 1, n_pixels_fit smaller than full fit_shape region

  • 'outside_bounds' : bit 2, fitted position outside input image bounds

  • 'negative_flux' : bit 4, non-positive flux

  • 'no_convergence' : bit 8, possible non-convergence

  • 'no_covariance' : bit 16, missing parameter covariance

  • 'near_bound' : bit 32, fitted parameter near a bound

  • 'no_overlap' : bit 64, no overlap with data

  • 'fully_masked' : bit 128, fully masked source

  • 'too_few_pixels' : bit 256, too few pixels for fitting

  • 'non_finite_position' : bit 512, non-finite fitted position

  • 'non_finite_flux' : bit 1024, non-finite fitted flux

  • 'non_finite_localbkg' : bit 2048, non-finite local background

Examples

Decode a single flag value:

>>> from photutils.psf import decode_psf_flags
>>> issues = decode_psf_flags(5)  # bits 1 and 4 set
>>> print(issues)
['n_pixels_fit_partial', 'negative_flux']
>>> 'n_pixels_fit_partial' in issues
True
>>> 'no_convergence' in issues
False

Decode multiple flag values:

>>> flags = [0, 8, 136]  # 0, bit 8, bits 8+128
>>> decoded_list = decode_psf_flags(flags)
>>> len(decoded_list)
3
>>> decoded_list[0]  # No issues
[]
>>> decoded_list[1]  # Convergence issue
['no_convergence']
>>> decoded_list[2]  # Multiple issues
['no_convergence', 'fully_masked']

Check for specific issues:

>>> issues = decode_psf_flags(136)
>>> if 'no_convergence' in issues:
...     print("Fit may not have converged")
Fit may not have converged
>>> if issues:  # Any issues present
...     print(f"Found {len(issues)} issues: {', '.join(issues)}")
Found 2 issues: no_convergence, fully_masked

Working with PSF photometry results:

>>> import numpy as np
>>> from astropy.modeling import models
>>> from astropy.table import Table
>>> from photutils.psf import (CircularGaussianPRF, PSFPhotometry,
...                            decode_psf_flags)
>>> # Create minimal test data
>>> yy, xx = np.mgrid[:21, :21]
>>> m1 = CircularGaussianPRF(flux=-10, x_0=10, y_0=10, fwhm=2)
>>> m2 = CircularGaussianPRF(flux=10, x_0=3, y_0=3, fwhm=2)
>>> m3 = CircularGaussianPRF(flux=10, x_0=21, y_0=21, fwhm=2)
>>> data = m1(xx, yy) + m2(xx, yy) + m3(xx, yy)
>>> psf_model = CircularGaussianPRF(flux=1, x_0=10, y_0=10, fwhm=2)
>>> init_params = Table({'x': (10, 3, 21), 'y': (10, 3, 21),
...                      'flux': (1, 10, 10)})
>>> photometry = PSFPhotometry(psf_model, (3, 3))
>>> results = photometry(data, init_params=init_params)
>>> issues_list = decode_psf_flags(results['flags'])
>>> for i, issues in enumerate(issues_list):
...     if issues:
...         print(f"Source {i+1}: {', '.join(issues)}")
Source 1: negative_flux
Source 3: n_pixels_fit_partial, no_covariance, too_few_pixels, non_finite_position, non_finite_flux
On this page