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.

The ztfquery.query module is your gateway to the full ZTF archive held at IRSA. Every workflow follows the same two-step pattern: first call load_metadata() to discover what data exists and receive a summary table, then call download_data() to fetch the files you need. The four scenarios below cover the most common use-cases, from a targeted sky-position search to bulk parallel downloads.
You need a free IRSA account to access data. For private ZTF partnership data your IRSA account must also be linked to a ZTF program. Public data releases (e.g. DR3 and later) are available to all registered users. Make sure the environment variable $ZTFDATA is set; it controls where downloaded files are stored.

​
Scenario 1: Query by sky position with filter and time range

Query all i-band (fid=3) science images within 0.01 deg of a target position observed since 14 May 2018.
1

Import the module and compute the start Julian Date

from ztfquery import query
from astropy import time

# Convert a calendar date to a Julian Date
starttime = time.Time("2018-05-14").jd
print(starttime)
# 2458252.5
2

Run the positional metadata query

zquery = query.ZTFQuery()
zquery.load_metadata(
    radec=[276.107960, +44.130398],
    size=0.01,                          # search radius in degrees
    sql_query=f"fid=3 and obsjd>{starttime}"
)
The call hits the IRSA web API and typically takes a few seconds. Results are returned as a pandas DataFrame.
3

Inspect the metatable

metatable is a pandas DataFrame that holds one row per matching image. Key columns include obsjd (observation Julian Date), ccdid (CCD identifier, 1–16), filtercode (e.g. zi, zr, zg), field, qid (quadrant ID), and seeing (FWHM in arcsec). The full schema is documented at the ZTF IRSA API.
zquery.metatable

       obsjd     ccdid  filtercode
0  2.458268e+06      1      zi
1  2.458268e+06     15      zi
2  2.458256e+06     15      zi
3  2.458255e+06      1      zi
4  2.458262e+06      1      zi
5  2.458273e+06      1      zi
6  2.458262e+06     15      zi
7  2.458273e+06     15      zi
4

Visualise the covered fields

zquery.show_gri_fields(
    title="i-band observations since 14 May 2018"
)
This plots the ZTF g/r/i field footprints on the sky with your queried observations highlighted.

​
Scenario 2: Generic SQL query (no coordinates)

Query any observation with a seeing smaller than 2 arcsec between 1 May 2018 and 1 June 2018 without specifying a sky position.
1

Compute Julian Date boundaries

from ztfquery import query
from astropy import time

jdstart = time.Time("2018-05-01").jd   # 2458209.5
jdend   = time.Time("2018-06-01").jd   # 2458240.5
2

Execute the SQL-style query

zquery = query.ZTFQuery()
zquery.load_metadata(
    sql_query=f"seeing<2 and obsjd BETWEEN {jdstart} AND {jdend}"
)
# This may take some time — the result set can contain ~50 000 entries
When no radec position is provided the sql_query argument is required by the IRSA API. You can use any SQL WHERE clause syntax supported by IRSA: AND, OR, BETWEEN, IN, LIKE, and standard arithmetic comparisons. Function calls and sub-queries are not supported.
3

Inspect and visualise — limiting to the main grid

zquery.metatable  # ~50 000 entries

zquery.show_gri_fields(
    title="1 May 2018 < time < 1 June 2018 | seeing < 2 arcsec",
    grid="main"        # use grid="secondary" to see the rest
)

​
Scenario 3: Reference image query

Reference images are deep coadds used as the template for difference imaging. They have their own metadata kind (kind="ref").
1

Query all reference images at a position

from ztfquery import query

zquery = query.ZTFQuery()
zquery.load_metadata(
    kind="ref",
    radec=[276.107960, +44.130398],
    size=0.0001
)
2

Inspect the field/filter/CCD summary

zquery.metatable[["field", "filtercode", "ccdid", "qid"]]

   field filtercode  ccdid  qid
0    764         zg      1    3
1    726         zr     15    2
2    726         zg     15    2
3    726         zi     15    2
4    764         zr      1    3
5    764         zi      1    3
3

Filter to a single band

Pass a sql_query argument to restrict results to one filter. Both of the following are equivalent for g-band:
# Using the numeric filter ID
zquery.load_metadata(
    kind="ref",
    radec=[276.107960, +44.130398],
    size=0.0001,
    sql_query="fid=1"
)

# Using the filter code string (note the inner single quotes)
zquery.load_metadata(
    kind="ref",
    radec=[276.107960, +44.130398],
    size=0.0001,
    sql_query="filtercode='zg'"
)
When matching string values in sql_query you must wrap the value in single quotes inside the double-quoted Python string, e.g. sql_query="filtercode='zg'". Filter IDs are: fid=1 → g-band (zg), fid=2 → r-band (zr), fid=3 → i-band (zi).
4

Download the reference image

zquery.download_data()   # downloads refimg.fits by default

​
Scenario 4: Downloading data

Once load_metadata() has been called you can download any of the associated data products.
1

Load metadata for a position with seeing constraint

from ztfquery import query

zquery = query.ZTFQuery()
zquery.load_metadata(
    radec=[276.107960, +44.130398],
    size=0.01,
    sql_query="seeing<2 and obsjd>2458252.5"
)

# Check the table before downloading
zquery.metatable[["obsjd", "seeing", "filtercode"]]

       obsjd     seeing filtercode
0  2.458277e+06  1.83882         zr
1  2.458277e+06  1.84859         zr
2  2.458268e+06  1.74317         zi
3  2.458269e+06  1.65564         zr
4  2.458267e+06  1.90791         zr
...
40  2.458253e+06  1.98775         zr
41  2.458275e+06  1.99942         zg
2

Single-process download

zquery.download_data("psfcat.fits", show_progress=False)
Files are saved under $ZTFDATA following IRSA’s directory structure.
3

Parallel download with multiple processes

zquery.download_data(
    "psfcat.fits",
    show_progress=True,   # display overall progress bar
    notebook=True,        # use a Jupyter-friendly progress bar
    nprocess=4,           # number of parallel worker processes
    verbose=True,         # print each filename as it downloads
    overwrite=True        # re-download even if the file already exists
)
Set overwrite=False (the default) to skip files you already have. verbose=True prints each file path as it is written, which is useful for debugging large batches.
4

Partial download using metatable indexes

# Download only the rows at these metatable indexes
zquery.download_data("psfcat.fits", indexes=[4, 6, 12, 40])
The indexes argument accepts any list of integer row labels from zquery.metatable.
5

Retrieve local file paths

local_files = zquery.get_local_data("psfcat.fits")
# Returns a list of absolute paths for files that exist on disk
If you close your Python session and come back later you must re-run load_metadata() before calling get_local_data(). The ZTFQuery object needs the metatable to know which file paths to look for.

​
Available science image products

Each science exposure queried through load_metadata(kind="sci") (the default) has up to eleven associated data products. Pass the filename suffix to download_data() to choose which one to fetch.
SuffixDescription
sciimg.fitsPrimary science image (default)
mskimg.fitsBit-mask image
psfcat.fitsPSF-fit photometry catalog
sexcat.fitsNested-aperture photometry catalog
sciimgdao.psfSpatially varying PSF estimate in DAOPhot look-up table format
sciimgdaopsfcent.fitsPSF estimate at science image centre as a FITS image
sciimlog.txtLog output from the instrumental calibration pipeline
scimrefdiffimg.fits.fzDifference image (science minus reference), fpack-compressed
diffimgpsf.fitsPSF estimate for the difference image
diffimlog.txtLog output from the image subtraction and extraction pipeline
log.txtOverall system summary log from the realtime pipeline
SuffixDescription
refimg.fitsReference image (default)
refcov.fitsCoverage map
refunc.fitsUncertainty image
refpsfcat.fitsPSF-fit photometry catalog for the reference
refsexcat.fitsAperture photometry catalog for the reference
refimlog.txtCalibration pipeline log
log.txtOverall system log

Build docs developers (and LLMs) love

Get started for freeTalk to us