Star light curves

What a V3 star light curve contains: the catalog, the curves, every column, its units and time system, and how detections, limits and uncertainties are defined.

API 3.1 · stars release 55c97bc0c218a6c5 · SS release ef7caf53a399bc1f

The V3 catalog#

Sky Patrol V3 measures every ASAS-SN image at fixed catalog positions. The catalog holds 164,180,266 stars, and the light curves hold about 1.21 trillion measurements from 15,164,380 images (release skypatrolV3_packed_20261029).

• Positions are ICRS at epoch 2015.5, with proper motions (pmra, pmdec, mas/yr). The light curves are measured at these fixed positions.
• star_id is an integer from 0 to 164,180,266 − 1. V2 and V3 ids are unrelated numbers; there is no cross-match between them yet.
• AV3 names encode the catalog position: AV3_085448.87+200630.6 is RA 08:54:48.87, Dec +20:06:30.6. Names with an _s or _ap suffix also resolve.
• mag in the catalog record is the reference g magnitude used to select and sort stars, not a light-curve average.
• Gaia ids. Each star record carries the Gaia DR3 and DR2 source_id of its counterpart, and a Gaia id finds its V3 star. See Gaia identifiers below.

Gaia DR2 and DR3 identifiers#

Every V3 star with a Gaia counterpart carries its Gaia DR3 and Gaia DR2 source_id. They appear in the star record (GET /v3/stars/{ref}, key gaia) and on the star page, and a Gaia id leads back to its star: GET /v3/stars/gaia/dr3/{source_id}, the batch form POST /v3/stars/gaia/dr3, any {ref} written Gaia DR3 <source_id>, /v3/resolve and the search box. The API reference has the details.

"gaia": {"dr3": {"source_id": "660820614442429056", "sep_mas": 0.16, "quality": "unique", "flags": 1},
         "dr2": {"source_id": "660820614442429056", "sep_mas": 0.12, "quality": "unique", "flags": 1},
         "g": 15.11}

Gaia source ids need 63 bits, so JSON carries them as decimal strings, like solar-system object_ids. sep_mas is the separation in milliarcseconds at epoch 2015.5; g is the Gaia G magnitude (DR3; DR2 when there is no DR3 match). A release without a match is null.

How the match was made#

• Inputs. The complete gaia_source tables of Gaia DR3 (… sources) and Gaia DR2 (… sources), read from the ESA Gaia archive in November 2026. Every Gaia source within 5″ of a V3 star was compared; there is no magnitude cut, so very red stars and faint white dwarfs are treated like every other star.
• DR2. The V3 positions of the g < 18 stars come from ATLAS Refcat2 (Tonry et al. 2018), whose astrometry is Gaia DR2 at epoch 2015.5. DR2 positions are therefore compared directly. The median separation is … mas, set by the 10⁻⁷ degree rounding of the catalog positions; … of the DR2 matches agree to better than 1 mas.
• DR3. DR3 positions (epoch 2016.0) are moved to 2015.5 with their DR3 proper motions. A DR3 source without a proper motion is compared at 2016.0 after moving the V3 star with its own proper motion. The median separation is … mas and 99% are below … mas.
• Rule. The nearest Gaia source within 1″ is the match. Beyond 100 mas a candidate must also have a plausible brightness, V3 reference g − Gaia G between −2 and +4 mag, so that a faint neighbour never stands in for a counterpart Gaia lacks. Closer than 100 mas the position alone decides. The flags below say how clean each match is.

The match was checked independently against the live ESA archive: cone searches around … random and special stars found the same source with the same separation in every case, and Gaia's own DR2–DR3 link (gaiadr3.dr2_neighbourhood) agrees with … of the (DR2, DR3) pairs it covers.

Match quality#

flags is a bit mask: 1 matched, 2 several Gaia sources within 1″, 4 shared with another V3 star, 8 compared without a Gaia proper motion (DR3 only), 16 Gaia duplicated_source, 32 separation above 100 mas, 64 V3 g − Gaia G outside [−2, +4] (a variable star, a blend or poor photometry; only on matches closer than 100 mas).

Caveats#

• An ASAS-SN pixel is 8″. A Gaia match identifies the star at the catalog position, not everything in the aperture. Close pairs (closest_of_several) and crowded fields blend in the light curve whatever the Gaia id says.
• DR2 and DR3 ids are different catalogs. Most sources kept their DR2 number in DR3, but … of the stars matched in both have different DR2 and DR3 ids, and some DR2 sources were split or merged. Always say which release an id comes from; Gaia <id> without a release is tried as DR3, then DR2. EDR3 ids are DR3 ids.
• High proper motion. The match is made at epoch 2015.5 with the proper motions, so fast stars match normally. Light curves are measured at the fixed 2015.5 position: a star moving more than a few hundred mas per year drifts across its aperture over the survey.
• White dwarfs. The 77,421 white dwarfs of the supplementary list are matched like every other star, with no magnitude cut. The … of them fainter than g = 18 exist in the catalog only because of that list; all of those have a DR3 and a DR2 match.
• Duplicates. Gaia's duplicated_source (flag 16) marks sources that Gaia itself found duplicated; a shared match usually means two V3 catalog entries for one Gaia source.
• No match. A Gaia source without a V3 star (fainter than the catalog limit, or with no counterpart within 1″) returns 404 not_found. Find its position, for example with Sesame, and run a cone search for the V3 stars around it.

If you use these identifiers, please also cite the Gaia mission (Gaia Collaboration, Prusti et al. 2016) and the release you used: Gaia DR3 (Gaia Collaboration, Vallenari et al. 2023) or Gaia DR2 (Gaia Collaboration, Brown et al. 2018).

Images, cameras and bands#

ASAS-SN has five units of four telescopes each, in Hawaii, Chile (two units), South Africa and Texas. Each telescope has its own camera, named by two letters such as bA or bm. An image name is the camera plus a six-digit number, for example bA685528; the image_num column holds the number. The cameras have 8.0″ pixels.

• V band came from the original cameras ba to bh, until they switched to g in 2018.
• g band comes from all cameras since late 2017.

V3 uses only reduced images whose reduction and astrometric solution succeeded. Images that were not marked good by the pipeline are kept but flagged (IMAGE_NOT_GOOD).

Curves and apertures#

A star's light curve is made of curves. Each curve is one (field, band, aperture) combination: ASAS-SN fields overlap, so a star can be measured in two or three fields, and each field has its own calibration. The curve column indexes the header's curves list, which gives each curve's field, band, aperture and its rows (start, count). CSV, JSON and Parquet expand curve into field, band and aperture columns.

Rows are grouped by curve and sorted by time within each curve. Sort by bjd yourself if you need one time-ordered series.

Time#

bjd is the Barycentric Julian Date in the TDB time scale (BJD_TDB) at mid-exposure, as a 64-bit float. The website plots BJD − 2450000. The full column set adds jd, the Julian Date in UTC at mid-exposure, and ut_date, the image's UT date and time string exactly as recorded. Do not try to rebuild ut_date from jd; about 5% of images would not match.

Magnitudes and upper limits#

Every image that covered the star is a row, whether or not the star was detected. A row is detected when the aperture counts exceed 5 times their uncertainty.

So select rows with detected and limit, never by testing mag:

import numpy as np
import pandas as pd

lc = pd.read_csv("https://asassn-v3.ifa.hawaii.edu/v3/stars/11010359/lc?format=csv", comment="#")
det = lc[lc.detected == 1]                               # measured magnitudes
lim = lc[(lc.detected == 0) & np.isfinite(lc.limit)]    # 5-sigma upper limits
print(len(det), "detections,", len(lim), "upper limits")

Magnitudes are 25 + zp − 2.5 log10(counts), where zp is the image's zero point at the star's position. The limit is 25 + zp − 2.5 log10(5 × counts_err).

Flux#

flux and flux_err are flux densities in mJy, computed for every row with finite counts, detected or not. The flux of a non-detection is the forced measurement at the catalog position and can be negative; averaging fluxes, not magnitudes, is the right way to combine faint epochs.

flux = F0 × counts × 10−0.4 (25 + zp) × 1000, with F₀ = 3631 Jy in g (AB) and 3836.3 Jy in V.

Uncertainties#

For a detection, mag_err combines the photometric error and the zero-point error: mag_err² = (1.0857 counts_err / counts)² + zp_err². flux_err combines the same two terms in flux.

The counts error comes from the error model chosen with error_model:

legacy (default)

The rc1 model: counts_err² = |counts| / gain + area × σbg², where σ_bg is the background scatter measured in the sky annulus.

v2

A model built on measured per-camera gain, read noise and dark current. The server offers it only when its supplement is installed, which is not the case at launch.

These errors are statistical only. For bright stars (g < 12) the epoch-to-epoch scatter is 2 to 4 times larger, because flat-field, zero-point and position errors of 0.009 to 0.020 mag per camera are not included. For epoch-to-epoch work, add a floor in quadrature: √(mag_err² + 0.014²) is a fair default. Solar-system light curves include such a floor by default (error floor).

Quality flags#

The quality column holds 13 warning bits. They never remove rows by themselves. The bits split into three groups:

• bits 0–5, facts about the pixels in the aperture or the image, fixed when the image was measured;
• bits 6–7, the aperture centre near the edge or a corner of the detector;
• bits 8–12, deciles: this epoch was among the worst 10% of this star's curve for image width, astrometry, zero-point fit, throughput or depth. They are computed per (curve, camera) on the full curve when it is returned, before the rows and exclude_quality filters, and need at least 30 epochs.

The quality flags page explains each bit and how to choose a mask.

Columns#

Lean columns (cols=lean, the default)#

Text, JSON, Arrow and Parquet add field, band and aperture (pixels) after curve.

Full columns (cols=full)#

All lean columns, plus:

The full set rebuilds the rc1 client's LightCurve.rows exactly. It is about three times the size of the lean set, so ask for it only when you need it.

Sentinel values#