Quality flags

Thirteen warning bits on every measurement, plus eleven moving-object bits for asteroids and comets. They are warnings, not cuts: you decide what to drop.

API 3.1 · stars release 55c97bc0c218a6c5 · SS release ef7caf53a399bc1f

How the flags work#

Every row has a 16-bit quality value; bits 0–12 are used (version Q5). A bit set means "this check raised a warning". Zero means that none of the checks that ran raised one; it does not promise that every check ran.
The API never drops a row because of a flag unless you ask with exclude_quality. Negative fluxes, non-detections and variability are not quality problems.
The website hides the Recommended set, 0x17, by default and always shows how many points it hid.
/v3/flags returns all the definitions on this page as JSON.

The 13 quality bits#

0BAD

1SAT

2IMG

3SUB

4NEG

5SKY

6EDGE

7CORNER

8FWHM

9WCS

10ZP_FIT

11THRU

12DEPTH

13—

14—

15—

stored when measureddetector positiondecile of this curveunused

Bit	Value	Name	Raised when
0	`1` 0x1	`BAD_PIXEL_APERTURE`	A bad pixel overlaps the aperture: a pixel on the pipeline's bad-pixel list, or an unstable ("telegraph") dark-current pixel of the image's dark frame.
1	`2` 0x2	`SATURATED_APERTURE`	A saturated pixel overlaps the aperture.
2	`4` 0x4	`IMAGE_NOT_GOOD`	The image was not explicitly marked good by the pipeline.
3	`8` 0x8	`SUBTRACTION_FAILED`	No successful difference image exists for this image.
4	`16` 0x10	`NEGATIVE_PIXEL`	A pixel in the aperture lies more than 5σ below the local sky (an over-subtracted pixel, whatever the cause).
5	`32` 0x20	`SKY_FALLBACK`	The local sky estimate fell back to a plain median of the annulus, or found no usable sky pixel.
6	`64` 0x40	`NEAR_CHIP_EDGE`	The aperture centre is within 25 pixels of the detector edge.
7	`128` 0x80	`NEAR_CHIP_CORNER`	The aperture centre is within 50 pixels of a detector corner, measured along the diagonal.
8	`256` 0x100	`POOR_FWHM`	The image FWHM is in the worst 10% of this curve. With 8″ pixels this is mostly the camera's focus, not the seeing.
9	`512` 0x200	`POOR_WCS`	The image's astrometric residual (`wcs_med`) is in the worst 10%.
10	`1024` 0x400	`POOR_ZP_FIT`	The zero-point fit scatter is in the worst 10%. Evaluated only when at least 10 calibration stars were used.
11	`2048` 0x800	`POOR_THROUGHPUT`	The zero point is in the lowest 10%: clouds, extinction or other light loss.
12	`4096` 0x1000	`POOR_DEPTH`	The limiting magnitude is in the shallowest 10%.

Bits 0–5: stored with the measurement#

These bits record facts about this source's pixels in this image (bits 0, 1, 4, 5) or about the image as a whole (bits 2, 3). They were fixed when the image was measured and do not change.

Bits 6–7: detector position#

These bits are computed from the stored aperture position each time a light curve is returned. Photometry near the edge or a corner of the detector is more often affected by vignetting, a poor flat field or distortion.

Bits 8–12: deciles#

Each decile bit marks the epochs that were among the worst 10% of this light curve for one image property. They are computed when a light curve is returned, and you should keep in mind what that means:

Population. Stars: each (curve, camera) group, so a star's worst camera is not flagged as a whole; each camera's own worst 10% is. Solar-system objects: see deciles.
Full curve first. The bits are computed on the full curve, before the rows, exclude_quality and max_blend filters. Filtering never changes which rows carry them.
At least 30 epochs. In a smaller group the bits are not evaluated and stay 0.
Relative, not absolute. Each bit marks about 10% of any long curve, so the bits cannot be compared between stars, and counting them across a sample means nothing.
They can change. A future release with more epochs shifts the deciles, so an epoch that is clean now may be flagged later. Cite the release you used.

Presets and `exclude_quality`#

Preset	Mask	Hides
All (API default)	`0`	Nothing
Recommended (website default)	`23` = `0x17`	BAD_PIXEL_APERTURE, SATURATED_APERTURE, IMAGE_NOT_GOOD, NEGATIVE_PIXEL
Strict	`8063` = `0x1F7F`	Every bit except NEAR_CHIP_CORNER

The website default (Recommended, 0x17) is waiting for Ben's approval.

Pass a mask as exclude_quality, in decimal or hex, to drop rows that have any of its bits. Or fetch everything and filter yourself:

Shell

curl -s "https://asassn-v3.ifa.hawaii.edu/v3/stars/11010359/lc?format=csv&exclude_quality=0x17" -o oj287_clean.csv

Python

import pandas as pd

lc = pd.read_csv("https://asassn-v3.ifa.hawaii.edu/v3/stars/11010359/lc?format=csv", comment="#")
clean = lc[(lc.quality & 0x17) == 0]                 # the Recommended preset
saturated = lc[(lc.quality & 0x2) != 0]               # one bit
print(len(lc), "rows,", len(clean), "clean,", len(saturated), "with saturated pixels")

Solar-system `moving_quality` bits#

Asteroid and comet rows carry the 13 quality bits above and a second column, moving_quality, for problems that only moving objects have:

Bit	Value	Name	Meaning
0	`1`	`TRAIL`	The object moved more than 0.25 pixel during the exposure
1	`2`	`EPHEMERIS_UNVALIDATED`	The ephemeris was not validated. Set on every SS-1 row.
2	`4`	`REFERENCE_CONTAMINATION`	Difference rows: a static source in the reference image lies under the aperture (\|ref\| > 3σ)
3	`8`	`PARTIAL_APERTURE`	The aperture runs off the image
4	`16`	`NONFINITE`	Non-finite flux, variance or zero point; the row is not valid
5	`32`	`NO_FLAT`	No flat-field value at this position
6	`64`	`NO_DARK`	The dark frame was unavailable, so unstable dark pixels were not checked
7	`128`	`COADD_MOTION`	Coadded images only; none in SS-1
8	`256`	`ERROR_APPROXIMATION`	Difference rows: the error budget is approximate (reference and kernel covariance not modelled)
9	`512`	`UNKNOWN_MAGNITUDE`	No predicted magnitude
10	`1024`	`POSITION_UNCERTAIN`	The predicted position's uncertainty is unknown or larger than 1″. Set on every SS-1 row.

EPHEMERIS_UNVALIDATED and POSITION_UNCERTAIN are set on every SS-1 row because the release has no orbit-uncertainty information. They do not mean the measurement is bad; ignore them unless you need validated positions. exclude_quality applies to quality only; filter moving_quality yourself.

Recommended rules#

Stars: No recommended column. The website's Recommended preset hides quality 0x17; use exclude_quality=0x17 or (quality & 0x17) == 0 to get the same rows.
Solar system: The recommended column and rows=recommended: detected, quality bits 0–5 clear, moving_quality 8, 16 and 32 clear, a measured image position and, for reduced-image rows, a small blend ratio. The solar-system page gives the rule in full.

Earlier versions#

Q5 is the only flag version served by V3. Earlier versions (Q1–Q4) numbered some bits differently and stored the edge bit at a fixed 50 pixels; the server translates older stored values, so every served quality value follows the table above.