Flag usage guidance

Flag usage guidance by table

This section provides table-specific guidance on which flags to apply for typical science-quality selections. The flags listed under “essential quality filters” should be applied in most science analyses. Additional filters are provided as guidance for specific science cases and should be adapted based on the science requirements.

Object table

Guidance for the application of flags on the deep coadd measurements of static sky objects.

Essential quality filters for the Object table are listed below. Minimal quality cuts for r-band PSF photometry are shown; adjust the band prefix as needed.

-- For r-band example; adjust band as needed
WHERE r_psfFlux_flag = 0                   -- PSF flux succeeded
  AND r_pixelFlags_saturatedCenter = 0     -- No saturation at center
  AND r_pixelFlags_crCenter = 0            -- No cosmic ray at center
  AND r_pixelFlags_interpolatedCenter = 0  -- No interpolation at center
  AND r_pixelFlags_sensor_edgeCenter = 0   -- Not on detector edge
  AND r_pixelFlags_inexact_psfCenter = 0   -- PSF model not discontinuous
  AND r_invalidPsfFlag = 0                 -- Valid PSF model

Additional filters for specific science cases are described below.

Galaxy samples (model photometry).

AND r_cModel_flag = 0        -- CModel fit succeeded
AND r_extendedness = 1       -- Extended source (galaxy)
AND r_extendedness_flag = 0  -- Classification valid

Note

The extendedness classifier in DP1 has not been fully characterized for purity or completeness. There is currently no published guidance on the selection function these cuts produce. Users should treat galaxy/star separation as approximate and validate against their specific science requirements.

Star samples (PSF photometry).

AND r_extendedness = 0       -- Point source (star)
AND r_extendedness_flag = 0  -- Classification valid

Note

The same caveats about the extendedness classifier apply as for galaxy samples above.

Stars used and reserved in PSF modeling can also be identified using {band}_calib_psf_used and {band}_calib_psf_reserved in the Source table (see Calibration usage flags).

Deblending filters for the Object table. Sources in the Object table are derived from the Source table deblending. To avoid contaminated photometry from blended parents, apply deblending filters when working with the Source table (see Source table).

High-precision Kron photometry.

AND r_kronFlux_flag = 0  -- Kron flux succeeded

High-precision shape measurements.

AND r_hsmShapeRegauss_flag = 0  -- HSM shapes succeeded

Strict pixel quality (optional).

AND r_pixelFlags_interpolated = 0  -- No interpolated pixels in footprint

Multi-band requirements: When requiring detections in multiple bands, ensure flux measurements and key pixel flags are valid in each band used. Check pixelFlags_nodata to confirm coverage.

Band-specific flags: The Object table has approximately 100 flags per band. The naming pattern is {band}_{measurement}_flag (e.g., g_psfFlux_flag, i_cModel_flag). Apply the same flag logic to each band independently.

Source table

Guidance for the application of flags on single-epoch visit detections.

Essential quality filters for the Source table are listed below.

WHERE centroid_flag = 0               -- Centroid succeeded
  AND psfFlux_flag = 0                -- PSF flux succeeded
  AND pixelFlags_edge = 0             -- Not on CCD edge
  AND pixelFlags_saturatedCenter = 0  -- No saturation at center
  AND pixelFlags_bad = 0              -- No bad pixels
  AND deblend_nChild = 0              -- Not a parent (avoid double-counting)
  AND deblend_skipped = 0             -- Deblending completed

Additional quality filters.

AND pixelFlags_crCenter = 0            -- No cosmic ray at center
AND pixelFlags_interpolatedCenter = 0  -- No interpolation at center
AND pixelFlags_suspectCenter = 0       -- No suspect pixels at center

Deblending note: Always use deblend_nChild = 0 to select isolated sources or deblended children. Parents (deblend_nChild > 0) represent blended groups and should not be treated as individual objects. Sources with deblend_skipped = 1 are complex blends that failed deblending and should also be excluded.

Calibration stars: If specifically selecting or excluding calibration stars, use calib_* flags (including calib_psf_used and calib_psf_reserved), but note DP1 caveats (Calibration usage flags).

ForcedSource table

Guidance for the application of flags on forced photometry at Object positions on single-epoch images.

Essential quality filters for ForcedSource are listed below (apply per measurement).

WHERE psfFlux_flag = 0                -- PSF flux succeeded
  AND pixelFlags_saturatedCenter = 0  -- No saturation at forced position
  AND pixelFlags_edge = 0             -- Position not on edge
  AND invalidPsfFlag = 0              -- PSF model valid

If using difference image flux.

AND psfDiffFlux_flag = 0              -- Difference flux succeeded
AND diff_PixelFlags_nodataCenter = 0  -- Difference image has coverage

Light curve usage: When constructing light curves, apply these flags to each measurement (row) individually. This filters out poor-quality epochs while retaining good measurements for the same object across other visits.

DiaSource table

Guidance for the application of flags on transient/variable detections on difference images.

Essential quality filters for DiaSource are listed below.

High-confidence real astrophysical transients.

WHERE isDipole = 0                    -- Not a subtraction dipole artifact
  AND reliability > 0.5               -- Likely real (adjust threshold)
  AND psfFlux_flag = 0                -- Difference flux succeeded
  AND pixelFlags_edge = 0             -- Not on edge
  AND pixelFlags_saturatedCenter = 0  -- No saturation
  AND pixelFlags_bad = 0              -- No bad pixels

Note

The real/bogus classifier in DP1 is preliminary. These threshold values are approximate suggestions and no purity/completeness characterization is currently available for DP1. The classifier may assign lower scores to some real variables (especially variable stars) that did not match training expectations. See the DIA processing documentation for more information on the reliability model. Always consider the science tolerance for contamination versus completeness.

Additional quality filters.

AND centroid_flag = 0  -- Position reliable
AND pixelFlags_cr = 0  -- Not a cosmic ray residual

ForcedSourceOnDiaObject table

Guidance for the application of flags on forced photometry at DiaObject positions on difference images.

Essential quality filters for ForcedSourceOnDiaObject are listed below (apply per measurement).

WHERE psfDiffFlux_flag = 0              -- Difference flux succeeded
  AND diff_PixelFlags_nodataCenter = 0  -- Difference image has coverage
  AND pixelFlags_saturatedCenter = 0    -- No saturation
  AND invalidPsfFlag = 0                -- PSF valid

Apply these filters when building DiaObject light curves from forced photometry. Similar to ForcedSource, filter per-measurement to remove bad epochs while keeping good ones.