Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MickaelRigault/ztfquery/llms.txt

Use this file to discover all available pages before exploring further.

ZTF distributes real-time transient detections as alert packets encoded in the Apache Avro binary format. Each .avro file bundles the candidate photometric measurement, its multi-epoch history, and three image stamps (science, reference, and difference) into a single self-describing record. The ztfquery.alert module provides a lightweight reader and visualiser for these packets without requiring any external account or data service.
No account or authentication is required for this module. It operates entirely on .avro files that you already have on disk.

​
AlertReader

AlertReader loads a single Avro alert file into memory and exposes its contents as a Python dictionary.

​
Loading an alert

from ztfquery import alert

ztfalert = alert.AlertReader.load("/path/to/alert.avro")
​
avrofile
str
required
Absolute or relative path to the .avro alert packet file on disk.
The class method AlertReader.load opens the file with fastavro, deserialises the first record, and returns an AlertReader instance.

​
Accessing alert data

The parsed alert is available as the .alert attribute — a plain Python dictionary whose structure mirrors the ZTF alert schema: 
from ztfquery import alert

ztfalert = alert.AlertReader.load("/path/to/alert.avro")

# Top-level alert dictionary
print(ztfalert.alert)

# Candidate-level measurements
candidate = ztfalert.alert["candidate"]
print(candidate["ra"], candidate["dec"])
print(candidate["magpsf"], candidate["sigmapsf"])

# Previous detections (list of dicts)
history = ztfalert.alert["prv_candidates"]

# Convenience methods for history
detections  = ztfalert.get_history_photopoints()  # real detections only
upper_limits = ztfalert.get_history_upperlimits()  # non-detections only
FieldDescription
ra, decSky coordinates of the transient candidate (degrees)
magpsf, sigmapsfPSF-fit magnitude and uncertainty
fidFilter ID: 1 = ztf:g, 2 = ztf:r, 3 = ztf:i
jdJulian date of the observation
rbReal/bogus score (0 = bogus, 1 = real)
fwhmFull-width at half maximum of the PSF (pixels)
isdiffposSign of the difference image flux
candidUnique candidate identifier

​
display_alert

display_alert generates a single-figure summary of an alert, combining the three image stamps with the full photometric history light curve. 
from ztfquery import alert

fig = alert.display_alert("/path/to/alert.avro", show_ps_stamp=True)
fig.savefig("alert_summary.png", dpi=200)
​
alert
str or dict
required
Either a path to an .avro file (string) or a pre-loaded alert dictionary.
​
savefile
str
default:"None"
If provided, the figure is saved to this path at 250 dpi.
​
show_ps_stamp
bool
default:"False"
If True, download and display a Pan-STARRS colour cutout (y/g/i) centred on the candidate position alongside the ZTF stamps.
The figure layout includes:
  • Science stamp — the new observation
  • Reference stamp — the template image at the same position
  • Difference stamp — science minus reference (the transient signal)
  • Pan-STARRS stamp (optional) — a deeper colour context image
  • Light curve panel — PSF magnitudes and upper limits across all historical ZTF detections, colour-coded by filter
The light curve shows all entries from prv_candidates that have a candid value (detections) as filled points with error bars, colour-coded by filter (green = ztf:g, red = ztf:r, orange = ztf:i). Non-detections appear as downward-pointing arrows at the limiting magnitude. The current alert candidate is marked with a diamond.

​
query_alert

alert.query_alert(alertid)
​
alertid
int or str
required
The unique alert candidate identifier.
The query_alert service is not yet implemented. Calling it will print a placeholder message and return None.

Build docs developers (and LLMs) love

Get started for freeTalk to us