decode_aperture_flags#

photutils.aperture.decode_aperture_flags(flags, *, return_bit_values=False)[source]#

Decode aperture bit flags into individual components.

This function takes integer flag values from aperture photometry or aperture statistics results and returns a list of human-readable names of the conditions that were detected. 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 was detected when measuring the aperture.

return_bit_valuesbool, optional

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

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

List of active flag names (or bit values) for a scalar input. For an array input, a nested list with the same shape as the input is returned, where each innermost element is the list of active flag names (or bit values) for the corresponding flag. If no flags are set, an empty list is returned. Possible flags are:

  • 0 : No flags set.

  • 1 ('no_overlap') : The aperture is fully outside the data array: no pixel with nonzero aperture weight falls inside the data.

  • 2 ('partial_overlap') : The aperture is partially outside the data array: one or more pixels with nonzero aperture weight fall outside the data.

  • 4 ('no_pixels') : The aperture contains zero pixels with nonzero weight inside the data, e.g., a fully off-image aperture or a tiny aperture that contains no pixel (or subpixel) centers with the “center” or “subpixel” methods.

  • 8 ('masked_pixels') : One or more input-masked pixels (mask keyword) have nonzero aperture weight.

  • 16 ('all_masked') : The aperture contains pixels, but none are valid: every nonzero-weight pixel inside the data is masked, non-finite, or excluded by segmentation masking.

  • 32 ('non_finite_data') : One or more unmasked data values (NaN or inf) with nonzero aperture weight are non-finite.

  • 64 ('non_finite_error') : One or more unmasked error values (NaN or inf) with nonzero aperture weight are non-finite.

  • 128 ('neighbor_pixels') : One or more pixels within the aperture were excluded, restricted, or corrected due to neighboring sources in the segmentation image.

  • 256 ('uncorrected_pixels') : With mask_method="correct", one or more neighbor-source pixels could not be corrected (the mirror pixel was unavailable) and were excluded instead.

  • 512 ('sigma_clipped') : One or more pixels within the aperture were rejected by sigma clipping.

  • 1024 ('all_clipped') : All valid pixels within the aperture were rejected by sigma clipping.

  • 2048 ('too_few_pixels') : There are too few valid pixels within the aperture to compute a requested statistic (e.g., the variance and standard deviation are undefined when the number of valid pixels is not larger than ddof).

  • 4096 ('singular_covariance') : The source covariance matrix is singular or nearly singular (the minor-axis variance is below 1/12, the variance of a uniform distribution across a single pixel), so covariance-derived shape properties (e.g., semimajor_axis, orientation, eccentricity) are ill-defined and have been regularized or set to NaN. This is a stats-only flag that is set only when a covariance-derived property has been computed.

Examples

Decode a single flag value:

>>> from photutils.aperture import decode_aperture_flags
>>> issues = decode_aperture_flags(10)  # bits 2 and 8 set
>>> print(issues)
['partial_overlap', 'masked_pixels']
>>> 'partial_overlap' in issues
True
>>> 'no_overlap' in issues
False

Decode multiple flag values:

>>> flags = [0, 8, 24]  # 0, bit 8, bits 8+16
>>> decoded_list = decode_aperture_flags(flags)
>>> decoded_list[0]  # No issues
[]
>>> decoded_list[1]
['masked_pixels']
>>> decoded_list[2]
['masked_pixels', 'all_masked']

Return the bit values instead of the names:

>>> decode_aperture_flags(10, return_bit_values=True)
[2, 8]