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’s internal scheduling and logging system, SkyVision, records every completed exposure — field ID, filter, program, pointing coordinates, exposure time, and Julian date — in nightly observing logs. The ztfquery.skyvision module downloads these logs from skyvision.caltech.edu, caches them as CSV files under $ZTFDATA/skyvision/, and exposes the data through the CompletedLog class with a rich set of filtering and visualisation methods.
Access to SkyVision requires the ZTF collaboration password. Store it with ztfquery.io.set_account("skyvision", username=..., password=...) before making any requests.

​
CompletedLog Class

CompletedLog is the primary interface for working with ZTF observing logs. Each instance wraps a pandas DataFrame (.data) containing the cleaned, standardised log entries for one or more nights.

​
Loading logs for a single night

from ztfquery import skyvision

logs = skyvision.CompletedLog.from_date("2020-02-01")
If the log for that night is already cached locally it is read from disk instantly; otherwise it is downloaded from SkyVision automatically.

​
Loading logs for multiple nights

Pass a list of date strings to from_date to load several non-contiguous nights into a single CompletedLog: 
from ztfquery import skyvision

logs = skyvision.CompletedLog.from_date(["2020-02-01", "2020-07-03"])

​
Loading a contiguous date range

from ztfquery import skyvision

# All nights from 2020-02-01 through yesterday
logs = skyvision.CompletedLog.from_daterange("2020-02-01", end=None)

# All nights between two specific dates
logs = skyvision.CompletedLog.from_daterange("2020-02-01", end="2020-03-31")
​
start
str
required
Start date in YYYY-MM-DD format.
​
end
str
default:"None"
End date in YYYY-MM-DD format. None means through yesterday.

​
The .data DataFrame

logs.data is a cleaned pandas DataFrame. Each row is one completed exposure.
ColumnTypeDescription
datetimestrISO 8601 timestamp of the observation (YYYY-MM-DDTHH:MM:SS.sss)
datestrUT date (YYYY-MM-DD)
exptimefloatExposure time in seconds
totalexptimefloatExposure time plus readout/setup overhead
fidintFilter ID: 1 = ztf:g, 2 = ztf:r, 3 = ztf:i
fieldintZTF field ID
pidfloatProgram ID: 1 = MSIP, 2 = Partners, 3 = Caltech
rastrBoresight right ascension (sexagesimal)
decstrBoresight declination (sexagesimal)
totaltimefloatTotal time including overheads
obsjdfloatJulian date of the observation
Example output for a single-night log: 
     datetime                  date        exptime  fid  field  pid   ra             dec         obsjd
1    2020-02-01T02:16:18.868   2020-02-01  30       1    447    1     +00:20:57.39   +04:33:00   2458880.59
2    2020-02-01T02:17:03.249   2020-02-01  30       1    603    1     +01:34:09.22   +26:09:00   2458880.59
...
839  2020-02-01T13:49:26.419   2020-02-01  90       3    823    2     +15:33:20      +62:09:00   2458880.08

​
Methods

​
Visualising observed fields

logs.show_gri_fields(title="2020-02-01")
Renders a Hammer-projection sky map of all fields observed during the loaded nights, colour-coded by filter (green = ztf:g, red = ztf:r, orange/gold = ztf:i).

​
Filtering by field ID

field_rows = logs.get_when_field_observed(456)
print(field_rows)
Returns a sub-DataFrame of all rows where the given field (or list of fields) was observed. Additional keyword arguments pid, fid, startdate, and enddate allow further narrowing. Example output across a date range: 
     datetime                  date        exptime  fid  field  pid
176  2020-02-01T04:18:41.870   2020-02-01  30       2    456    1
106  2020-02-05T03:32:29.182   2020-02-05  30       2    456    1
162  2020-02-07T04:12:57.286   2020-02-07  30       1    456    1
...
137  2020-03-05T04:15:26.386   2020-03-05  30       2    456    1

​
Filtering by sky position

# ra, dec in decimal degrees
target_rows = logs.get_when_target_observed([83.8221, 22.0145])
Identifies all ZTF fields that contain the given coordinates and returns matching log rows, using the same optional pid, fid, and date-range filters as get_when_field_observed.

​
Counting observations by program or filter

# How many exposures did each program take in ztf:r (fid=2)?
counts = logs.get_count("pid", fid=2)
print(counts)

pid
1    24986
2    13661
3    14249
get_count groups logs.data by the named column and returns a Series of observation counts. Pass fid to restrict to a single filter.

​
Generic filtered access

# Get a filtered sub-DataFrame
subset = logs.get_filtered(field=456, fid=2, pid=1)
get_filtered supports field, fid, pid, startdate, enddate, grid, and query arguments and returns a filtered pandas DataFrame.

​
Bulk Downloading

For analyses spanning months or years, download all available logs in parallel before creating CompletedLog objects: 
from ztfquery import skyvision

skyvision.download_timerange_log(
    "2018-05-01",
    which="completed",
    nprocess=4,
)
​
start
str
required
First night to download, in YYYY-MM-DD format.
​
which
str
default:"\"completed\""
Log type to download. Currently "completed" (science queue) and "qa" (quality-assurance) are supported.
​
nprocess
int
default:"1"
Number of parallel download workers. Setting this to 4 or higher significantly reduces total download time for large date ranges.
Run download_timerange_log once to populate your local cache for the entire ZTF baseline. After that, CompletedLog.from_date and CompletedLog.from_daterange will download only the nights that are not yet cached — so routine daily or weekly use is fast and requires no extra setup.
A progress bar is displayed during the download. Expect roughly 10–20 seconds per year of data at nprocess=4.

Build docs developers (and LLMs) love

Get started for freeTalk to us