AIMS Provenance: Zwicky Transient Facility

Draft for review. This page describes the current AIMS handling of Zwicky Transient Facility alert detections.

Source summary

The Zwicky Transient Facility (ZTF) is a time-domain survey that produces alert packets for difference-image detections. ZTF alert packets include a top-level alert record, a nested candidate record, historical candidate context, forced-photometry history, and image cutouts. The ZTF project publishes Avro schema documentation for these alert packets.

AIMS uses the ZTF alert stream as a source of candidate moving-source detections. It does not ingest all ZTF images or all ZTF source measurements.

How AIMS accesses ZTF

AIMS queries a public BigQuery mirror of ZTF alerts. The AIMS extraction logic chooses the correct upstream alert table by Julian Date and currently knows about these alert table versions:

alerts_v1_8
alerts_v3_0
alerts_v3_1
alerts_v3_3
alerts_v4_02

AIMS partitions ZTF extraction by day and materializes the normalized AIMS ZTF table by daily windows, with monthly source-transform partitions upstream.

AIMS date range and observatory

AIMS partition start: 2018-06-01.
AIMS treats ZTF as active/continuing.
AIMS observatory code: I41.

AIMS source fields

AIMS reads these ZTF alert candidate fields:

ZTF field	Use in AIMS
`candid`	Observation id.
`candidate.fid`	Filter mapping.
`candidate.jd`	Exposure start time.
`candidate.ra`, `candidate.dec`	Detection position.
`candidate.magpsf`	PSF-fit magnitude.
`candidate.sigmapsf`	Magnitude uncertainty.
`candidate.exptime`	Exposure duration when available.
`candidate.rb`	RealBogus quality filter.
`candidate.ndethist`	Repeated-detection/static-source filter.

For older alert-table versions that lack exptime, AIMS assumes 30 seconds, consistent with the operational ZTF exposure duration used by the ETL.

AIMS filtering

AIMS applies these source filters before normalization:

candidate.rb > 0.5, using the ZTF RealBogus score where values closer to 1 are more reliable;
candidate.ndethist < 5, where ndethist is the number of spatially coincident detections within 1.5 arcsec going back to the beginning of the survey on the same field/readout-channel;
duplicate alert rows are collapsed by candid, keeping the first deterministic row ordered by time and position.

This intentionally selects alert candidates that are more likely to be transient or moving detections rather than frequently detected static sources.

AIMS-derived and normalized values

AIMS field	ZTF source or derivation
`observation_id`	`candid` converted to string.
`exposure_id`	Synthetic id `ztf_exp_<mjd_midpoint>` because the selected alert fields do not provide a stable exposure id.
`dataset_id`	Constant `ztf`.
`observatory_code`	Constant `I41`.
Observation time	`candidate.jd` converted to UTC MJD plus half the exposure duration.
`filter`	`fid` mapped as `1 -> g`, `2 -> r`, `3 -> i`.
`ra_deg`, `dec_deg`	`candidate.ra`, `candidate.dec`.
`ra_sigma_deg`, `dec_sigma_deg`	Not supplied by this AIMS ZTF source path; stored as null.
`mag`, `mag_sigma`	`magpsf`, `sigmapsf`.
`healpixel`	Derived by AIMS from RA/Dec at nside=128 NESTED.

Known limitations and interpretation notes

AIMS ZTF rows come from alert candidates, not from a complete ZTF source catalog or image archive.
The rb and ndethist filters improve moving/transient relevance but are not definitive object classifications.
The synthetic exposure id is an AIMS convenience value and should not be treated as a native ZTF exposure identifier.
AIMS currently does not preserve the full ZTF alert packet, alert cutouts, or all history fields in the normalized detection row.
ZTF alert times in the source are Julian Dates; AIMS stores UTC MJD/timestamp values after conversion.