# Licensed under a 3-clause BSD style license - see LICENSE.rst
"""
Tools for working with PSF photometry flags, including centralized flag
definitions and decoding utilities.
"""
from dataclasses import dataclass
from typing import ClassVar
import numpy as np
from photutils.utils._deprecation import (deprecated_getattr,
deprecated_positional_kwargs)
__all__ = ['PSF_FLAGS', 'decode_psf_flags']
@dataclass(frozen=True)
class _PSFFlagDefinition:
"""
A single PSF flag definition.
Attributes
----------
bit_value : int
The bit value (power of 2) for this flag.
name : str
Short name for the flag (used in decode_psf_flags).
description : str
Brief description of what this flag indicates.
detailed_description : str
Detailed description for use in docstrings.
"""
bit_value: int
name: str
description: str
detailed_description: str
class _PSFFlags:
"""
Centralized definition of PSF photometry flags.
This class provides a single source of truth for all PSF flag
definitions, including bit values, names, and descriptions. It
enables consistent flag handling across the PSF photometry codebase
and supports dynamic docstring generation.
Examples
--------
>>> from photutils.psf.flags import _PSFFlags
>>> flags = _PSFFlags()
>>> flags.N_PIXELS_FIT_PARTIAL
1
>>> flags.get_name(1)
'n_pixels_fit_partial'
>>> flags.get_description(8)
'possible non-convergence'
"""
# Define all PSF flags with their properties
FLAG_DEFINITIONS: ClassVar = [
_PSFFlagDefinition(
bit_value=1,
name='n_pixels_fit_partial',
description=('n_pixels_fit smaller than full fit_shape '
'region'),
detailed_description=('The number of fitted pixels '
'(n_pixels_fit) is smaller than the '
'full fit_shape region, indicating '
'partial PSF fitting'),
),
_PSFFlagDefinition(
bit_value=2,
name='outside_bounds',
description='fitted position outside input image bounds',
detailed_description=('The fitted source position is outside the '
'bounds of the input image'),
),
_PSFFlagDefinition(
bit_value=4,
name='negative_flux',
description='non-positive flux',
detailed_description=('The fitted flux value is negative or zero, '
'which is non-physical'),
),
_PSFFlagDefinition(
bit_value=8,
name='no_convergence',
description='possible non-convergence',
detailed_description=('The PSF fitting algorithm may not have '
'converged to a stable solution'),
),
_PSFFlagDefinition(
bit_value=16,
name='no_covariance',
description='missing parameter covariance',
detailed_description=('Parameter covariance matrix is not '
'available, preventing error estimation'),
),
_PSFFlagDefinition(
bit_value=32,
name='near_bound',
description='fitted parameter near a bound',
detailed_description=('One or more fitted parameters are very '
'close to their imposed bounds'),
),
_PSFFlagDefinition(
bit_value=64,
name='no_overlap',
description='no overlap with data',
detailed_description=('The source PSF fitting region has no '
'overlap with valid data pixels'),
),
_PSFFlagDefinition(
bit_value=128,
name='fully_masked',
description='fully masked source',
detailed_description=('All pixels in the source fitting region '
'are masked'),
),
_PSFFlagDefinition(
bit_value=256,
name='too_few_pixels',
description='too few pixels for fitting',
detailed_description=('Insufficient unmasked pixels available '
'for reliable PSF fitting'),
),
_PSFFlagDefinition(
bit_value=512,
name='non_finite_position',
description='non-finite fitted position',
detailed_description=('The fitted x or y position is NaN or inf, '
'indicating an invalid or failed fit'),
),
_PSFFlagDefinition(
bit_value=1024,
name='non_finite_flux',
description='non-finite fitted flux',
detailed_description=('The fitted flux value is NaN or inf, '
'indicating an invalid or failed fit'),
),
_PSFFlagDefinition(
bit_value=2048,
name='non_finite_localbkg',
description='non-finite local background',
detailed_description=('The local background value is NaN or '
'inf, so it was not subtracted before '
'fitting'),
),
]
# Remove in 4.0
_DEPRECATED_FLAG_NAMES: ClassVar = {
'npixfit_partial': 'n_pixels_fit_partial',
}
# Remove in 4.0
_DEPRECATED_CONSTANT_NAMES: ClassVar = {
'NPIXFIT_PARTIAL': 'N_PIXELS_FIT_PARTIAL',
}
def __init__(self):
for flag_def in self.FLAG_DEFINITIONS:
# Create uppercase constants (e.g., N_PIXELS_FIT_PARTIAL = 1)
setattr(self, flag_def.name.upper(), flag_def.bit_value)
# Create lookup dictionaries for efficient access
self._bit_to_def = {fd.bit_value: fd for fd in self.FLAG_DEFINITIONS}
self._name_to_def = {fd.name: fd for fd in self.FLAG_DEFINITIONS}
# Remove in 4.0
def __getattr__(self, name):
return deprecated_getattr(self, name,
self._DEPRECATED_CONSTANT_NAMES,
since='3.0', until='4.0')
@property
def all_flags(self):
"""
Return all flag definitions.
"""
return self.FLAG_DEFINITIONS.copy()
@property
def bit_values(self):
"""
Return all bit values.
"""
return [fd.bit_value for fd in self.FLAG_DEFINITIONS]
@property
def names(self):
"""
Return all flag names.
"""
return [fd.name for fd in self.FLAG_DEFINITIONS]
@property
def flag_dict(self):
"""
Return dictionary mapping bit values to names.
"""
return {fd.bit_value: fd.name for fd in self.FLAG_DEFINITIONS}
def get_definition(self, identifier):
"""
Get flag definition by bit value or name.
Parameters
----------
identifier : int or str
Either the bit value (int) or name (str) of the flag.
Returns
-------
definition : `_PSFFlagDefinition`
The flag definition.
Raises
------
KeyError
If the identifier is not found.
"""
if isinstance(identifier, int):
if identifier not in self._bit_to_def:
msg = f'No flag with bit value {identifier}'
raise KeyError(msg)
return self._bit_to_def[identifier]
if isinstance(identifier, str):
# Remove in 4.0
if identifier in self._DEPRECATED_FLAG_NAMES:
import warnings
from astropy.utils.exceptions import AstropyDeprecationWarning
new_name = self._DEPRECATED_FLAG_NAMES[identifier]
warnings.warn(
f"The flag name '{identifier}' is deprecated "
f"in version 3.0. Use '{new_name}' instead. "
'It will be removed in version 4.0.',
AstropyDeprecationWarning,
stacklevel=2,
)
identifier = new_name
if identifier not in self._name_to_def:
msg = f"No flag with name '{identifier}'"
raise KeyError(msg)
return self._name_to_def[identifier]
msg = 'identifier must be int (bit value) or str (name)'
raise TypeError(msg)
def get_name(self, bit_value):
"""
Get flag name from bit value.
Parameters
----------
bit_value : int
The bit value of the flag.
Returns
-------
name : str
The name of the flag.
"""
return self.get_definition(bit_value).name
def get_bit_value(self, name):
"""
Get flag bit value from name.
Parameters
----------
name : str
The name of the flag.
Returns
-------
bit_value : int
The bit value of the flag.
"""
return self.get_definition(name).bit_value
def get_description(self, bit_value):
"""
Get flag description from bit value.
Parameters
----------
bit_value : int
The bit value of the flag.
Returns
-------
description : str
The brief description of the flag.
"""
return self.get_definition(bit_value).description
def get_detailed_description(self, bit_value):
"""
Get detailed flag description from bit value.
Parameters
----------
bit_value : int
The bit value of the flag.
Returns
-------
detailed_description : str
The detailed description of the flag.
"""
return self.get_definition(bit_value).detailed_description
# Create a singleton instance for global use
PSF_FLAGS = _PSFFlags()
def _update_decode_docstring(func):
"""
Decorator to update function docstring with PSF flag documentation.
This decorator can be applied to functions like decode_psf_flags to
automatically replace manually defined flag lists with dynamically
generated ones.
Parameters
----------
func : function
The function to decorate.
Returns
-------
func : function
The decorated function with updated docstring.
"""
if not hasattr(func, '__doc__') or func.__doc__ is None:
return func
docstring = func.__doc__
# Look for the placeholder text
placeholder = '<flag descriptions>'
if placeholder in docstring:
# Generate the flag descriptions
flag_descriptions = ['']
indent = ' ' * 4
for flag_def in PSF_FLAGS.FLAG_DEFINITIONS:
name = flag_def.name
bit_val = flag_def.bit_value
desc = flag_def.description
line = f"{indent}- ``'{name}'`` : bit {bit_val}, {desc}"
flag_descriptions.append(line)
# Replace the placeholder with the flag descriptions
flag_text = '\n'.join(flag_descriptions)
new_docstring = docstring.replace(placeholder, flag_text)
func.__doc__ = new_docstring
return func
[docs]
@_update_decode_docstring
@deprecated_positional_kwargs(since='3.0', until='4.0')
def decode_psf_flags(flags, return_bit_values=False):
# numpydoc ignore: RT05
"""
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
----------
flags : int 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_values : bool, optional
If `True`, return the decoded bit flags (integers) instead of
the flag descriptions (strings). Default is `False`.
Returns
-------
decoded : list 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:
<flag descriptions>
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
"""
# Get flag definitions from centralized source
flag_definitions = PSF_FLAGS.flag_dict
def _decode_single_flag(flag_value):
"""
Decode a single integer flag value.
"""
if not isinstance(flag_value, (int, np.integer)):
msg = 'Flag value must be an integer'
raise TypeError(msg)
if flag_value < 0:
msg = 'Flag value must be a non-negative integer'
raise ValueError(msg)
active_flags = []
for bit_value, description in flag_definitions.items():
if flag_value & bit_value:
if return_bit_values:
active_flags.append(bit_value)
else:
active_flags.append(description)
return active_flags
# Handle both single values and arrays
if np.isscalar(flags):
return _decode_single_flag(flags)
# Convert to numpy array for consistent handling
flags_array = np.asarray(flags)
if flags_array.ndim == 0:
# Handle 0-d arrays (scalar arrays)
return _decode_single_flag(flags_array.item())
# Handle 1-d or higher dimensional arrays
return [_decode_single_flag(flag) for flag in flags_array.flat]
