Flag definitions and categories#

Flag inventory across DP1 tables#

DP1 contains 660 flag columns distributed across five catalog tables, as listed in the table below.

Table	Flag columns	Flag types
Object	512	Pixel quality, measurement failure, extendedness, deblending, and calibration flags across 5 photometric bands (u, g, r, i, z).
Source	82	Centroiding, photometry, deblending, and calibration flags.
ForcedSource	15	Pixel quality and forced photometry flags.
DiaSource	36	Pixel quality, real/bogus classification, and dipole flags.
ForcedSourceOnDiaObject	15	Pixel quality and forced difference-image photometry flags.

Flag categories#

To help users interpret flag meanings, the following sections organize flags into categories based on what the flag indicates.

Pixel quality flags#

Pattern: {band}_pixelFlags_*

Purpose: Report on issues with individual pixels in the source footprint, derived from image mask planes.

The most commonly used pixel quality flags are listed in the table below.

Flag name	Tables	Meaning when set to 1
`pixelFlags_saturated`	Object, Source, DiaSource	Saturated pixels in footprint; photometry unreliable.
`pixelFlags_saturatedCenter`	Object, Source, DiaSource	Saturated pixel in central 3x3 footprint; critical quality issue.
`pixelFlags_cr`	Object, Source, DiaSource	Cosmic ray detected and interpolated in footprint.
`pixelFlags_crCenter`	Object, Source, DiaSource	Cosmic ray at center.
`pixelFlags_interpolated`	Object, Source, DiaSource	Interpolated pixels in footprint (from CRs, defects, saturation).
`pixelFlags_interpolatedCenter`	Object, Source, DiaSource	Interpolated pixel at center; affects core photometry and shapes.
`pixelFlags_edge`	Source, DiaSource	Source on CCD edge (deprecated for Object coadds; see `sensor_edge`).
`pixelFlags_sensor_edge`	Object	Detector boundary crossed footprint.
`pixelFlags_sensor_edgeCenter`	Object	Detector edge near center; important for coadds.
`pixelFlags_bad`	Object, Source, DiaSource	Known bad pixels (detector defects) in footprint.
`pixelFlags_suspect`	Source, DiaSource	Suspect pixels (near saturation, non-linear response).
`pixelFlags_suspectCenter`	Source, DiaSource	Suspect pixel at center.
`pixelFlags_clipped`	Object	Artifact rejection during coaddition excluded input pixels.
`pixelFlags_clippedCenter`	Object	Clipping occurred at center.
`pixelFlags_nodata`	Object, Source, DiaSource	No pixel data available (off coverage area).
`pixelFlags_inexact_psfCenter`	Object	PSF model discontinuous at center (OR of CLIPPED, REJECTED, SENSOR_EDGE).

Key points:

Center variants: Flags with Center suffix indicate the issue affects the object’s central footprint (typically a 3x3 pixel box), which is more critical for photometry and shapes than flags affecting only the outer footprint.
Coadd-specific flags: On Object table coadds, pixelFlags_edge is deprecated. Use pixelFlags_sensor_edge and pixelFlags_sensor_edgeCenter instead, which indicate where detector boundaries from input visits crossed the object.

Measurement failure flags#

Pattern: *_flag (algorithm-specific)

Purpose: Indicate that a particular measurement algorithm failed or produced unreliable results.

The general measurement failure flags are listed in the table below.

Flag name	Tables	Meaning when set to 1
`{band}_psfFlux_flag`	Object, Source, ForcedSource	PSF flux measurement failed; do not use PSF flux.
`{band}_cModel_flag`	Object, Source	Galaxy model (CModel) fit failed; do not use model fluxes.
`{band}_kronFlux_flag`	Object	Kron aperture flux failed (bad radius, near edge).
`{band}_apNNFlux_flag`	Object, Source	Aperture flux in NN-pixel aperture failed.
`{band}_gaapFlux_flag`	Object	GAaP (Gaussian Aperture and PSF) photometry failed.
`centroid_flag`	Source, DiaSource	Centroid algorithm failed; do not trust position.
`{band}_extendedness_flag`	Object, Source	Star/galaxy classifier failed; extendedness value unreliable.
`{band}_sizeExtendedness_flag`	Object	Shape-based star/galaxy classifier failed.
`shape_flag`	Source, DiaSource	Shape measurement (second moments) failed.
`{band}_hsmShapeRegauss_flag`	Object	HSM Regaussianization shape measurement failed.

Key points:

Measurement values when flagged: {band}_psfFlux_flag is set when the algorithm returns a non-finite flux or a flux error. When the flux is finite, a set flag could be related to other types of errors, such as pixelFlags_saturatedCenter = 1.
Subflag pattern: Many algorithms provide detailed subflags explaining why the measurement failed (e.g., psfFlux_flag_edge, psfFlux_flag_noGoodPixels). If the general flag is set to 1, the specific failure reason may be in a subflag, but the general flag alone is sufficient to filter the measurement.
Usage rule: If a measured quantity (flux, shape, etc.) is used, the corresponding general flag should be required to be 0. For example, when using r_psfFlux, require r_psfFlux_flag = 0.

Deblending flags#

Purpose: Indicate status and quality of the deblending process (separating overlapping sources).

The Source table deblending flags are listed in the table below.

Flag name	Tables	Meaning when set to 1
`deblend_nChild`	Source	Number of deblended children. If > 0, this is a parent (blended group) and should not be used as an independent object (to avoid double-counting). Require `deblend_nChild = 0` for science samples.
`deblend_skipped`	Source	Deblender skipped this source (too complex, too many peaks, or footprint too large). This parent record contains flux from multiple objects. Exclude sources with `deblend_skipped = 1` to avoid contaminated photometry.
`deblend_tooManyPeaks`	Source	Deblending skipped due to excessive peaks in footprint (often accompanies `deblend_skipped`).
`deblend_parentTooBig`	Source	Deblending skipped because parent footprint was too large.
`deblend_deblendedAsPsf`	Source	Source treated as point source during deblending (informational; not a failure).
`deblend_hasStrayFlux`	Source	Blend had unassigned “stray flux” not allocated to children; photometry may be incomplete.
`deblend_masked`	Source	Majority of parent footprint was masked; often leads to `deblend_skipped`.

Typical science cut: deblend_nChild = 0 AND deblend_skipped = 0.

This ensures the sample includes only isolated sources or properly deblended children, excluding blended parents and complex cases.

Difference imaging flags#

The DiaSource-specific flags are listed in the table below.

Flag name	Meaning and recommendation
`isDipole`	Detection classified as dipole artifact (imperfect image subtraction). Exclude dipoles (`isDipole = 0`) for clean transient samples; these are typically subtraction residuals of bright stars.
`reliability`	Real/bogus score (0–1); higher = more likely real astrophysical source. Note: This is not a boolean flag; it is a continuous floating-point value. Apply a threshold (e.g., `reliability > 0.5` or `> 0.8`) to remove artifacts (cosmic rays, ghosts, dipoles). The classifier is preliminary in DP1; use with awareness that it may filter some real variables.
`psfDiffFlux_flag`	PSF flux on difference image failed. Require `0` to use difference flux.
`forced_PsfFlux_flag`	Forced flux on direct (science) image failed. If using science image flux (`scienceFlux`), require `0`.

The ForcedSourceOnDiaObject difference imaging flags are listed in the table below.

Flag name	Meaning when set to 1
`psfDiffFlux_flag`	Forced PSF flux on difference image failed.
`diff_PixelFlags_nodataCenter`	Position outside difference image coverage (no template); difference flux invalid.

Specialized flags#

Other notable flags are listed in the table below.

Flag name	Tables	Meaning when set to 1
`invalidPsfFlag`	Object, ForcedSource, ForcedSourceOnDiaObject	PSF model invalid (no inputs); measurements unreliable. Exclude these sources.
`blendedness_flag`	Object, Source	Blendedness measurement algorithm failed.
`inputCount_flag`	Object	Failed to compute number of coadd input exposures.
`trail_flag_edge`	DiaSource	Trailed source (streak) extended off image edge.

Calibration usage flags#

Pattern: {band}_calib_*

For most science, these flags can be ignored as they pertain to internal use in the calibration process.

These flags indicate whether a source was used in astrometric calibration, photometric calibration, or PSF modeling during single-visit processing.

The common calibration flags are listed in the table below.

Flag name	Tables	Meaning when set to 1
`calib_astrometry_used`	Source	Source used in astrometric (WCS) solution.
`calib_photometry_used`	Source	Source used in photometric zeropoint determination.
`calib_photometry_reserved`	Source	Source reserved from photometric calibration (held out for validation).
`calib_psf_used`	Source	Source used for PSF modeling.
`calib_psf_reserved`	Source	Source reserved from PSF determination.
`calib_psf_candidate`	Source	Source was a candidate for PSF star selection.

Important DP1 caveat: In DP1, these flags reflect preliminary single-visit calibration selections and are not updated for final global calibrations (FGCM photometry, refined astrometry). There are known mismatches between single-visit and final calibrations.

These flags are primarily diagnostic. Calibrator stars can be excluded if needed (e.g., calib_photometry_used = 0 to remove stars used for zeropoint fitting), but the preliminary nature means some true calibrators will not be flagged and vice versa.