Use this file to discover all available pages before exploring further.
The ztfquery.fields module is the central toolkit for working with ZTF’s fixed sky tessellation. ZTF tiles the observable sky into a predefined grid of fields, each observed by a mosaic camera of 16 CCDs, with every CCD subdivided into 4 quadrants (identified by a readout-channel ID, rcid). The module exposes a global pandas DataFrame (FIELD_DATAFRAME) and a flat array of IDs (FIELDSNAMES) loaded from the bundled ztf_fields.txt catalogue, along with a comprehensive set of functions for querying spatial containment, computing polygon geometry, checking reference image availability, and producing publication-quality sky maps.
The module exposes two module-level objects that are available immediately after import:
from ztfquery import fields# pandas DataFrame indexed by field ID (int)# Columns: RA, Dec, Ebv, GalLong, GalLat, EclLong, EclLat, Entryprint(fields.FIELD_DATAFRAME.head())# numpy array of all field IDs (main + secondary grids)print(fields.FIELDSNAMES[:10])
Object
Type
Description
FIELD_DATAFRAME
pandas.DataFrame
All field properties, indexed by field ID. Columns include RA, Dec, Ebv, GalLong, GalLat, EclLong, EclLat.
from ztfquery import fields# All main-grid fields with Dec between -10 and +30 degfids = fields.get_fieldid(grid="main", decrange=[-10, 30])# Fields in a specific RA/Dec boxbox_fids = fields.get_fieldid(rarange=[30, 60], decrange=[-5, 5])# Low-extinction fields above Dec = -20clean_fids = fields.get_fieldid(grid="main", ebvrange=[None, 0.1], decrange=[-20, None])
Expand each field polygon by this many degrees before testing containment. Useful to account for the ~0.3 deg inter-CCD gap.
from ztfquery import fieldsra, dec = 195.0, 27.5 # some target position# Field IDs containing the positioncontaining = fields.get_fields_containing_target(ra, dec)print(containing) # e.g. Index([440, 441], dtype='int64')# Include CCD-level resolutioncontaining_ccd = fields.get_fields_containing_target(ra, dec, inclccd=True)print(containing_ccd) # e.g. ['440_7', '441_12']
get_fields_containing_target requires shapely (pip install shapely). Performance is greatly improved with geopandas (pip install geopandas), which enables a vectorised GeoSeries lookup. Without geopandas the function falls back to a pure-Python loop over every field polygon.
from ztfquery import fields# Vertices of a single field (full focal plane)verts = fields.get_field_vertices(440)# shape: (20, 2) — boundary sampled at 5 points per edge × 4 edges# CCD-level vertices as a dict: {"440_1": Polygon, ..., "440_16": Polygon}ccd_verts = fields.get_field_vertices(440, inclccd=True, as_dict=True, as_polygon=True)
Low-level function that computes the four-edge boundary for one or more fields given explicit (ra_field, dec_field) reference coordinates and an optional CCD/quadrant layout.
ZTF’s focal plane contains 16 CCDs, each split into 4 quadrants. The rcid (readout-channel ID) uniquely identifies a quadrant across the entire focal plane (0–63).
from ztfquery import fields# Centroid of a specific rcid within a fieldpos = fields.get_rcid_centroid(rcid=9, fieldid=440)# returns [ra, dec] of that quadrant's centre# Centroids of all 4 quadrants of a given CCD (fieldid + ccdid)quads = fields.get_qids_centroid(fieldid=440, ccdid=3)# returns {'q1': [ra1, dec1], 'q2': ..., 'q3': ..., 'q4': ...}# Alternatively, pass pre-computed CCD vertices directly (skips the vertex lookup)ccd_verts = fields.get_field_vertices(fieldid=440, inclccd=True, ccd=3)quads = fields.get_qids_centroid(ccd_vertices=ccd_verts)
from ztfquery import fieldsimport matplotlib.pyplot as pltfig = fields.show_field_ccds(440)plt.show()# Show only CCDs 1-8fig = fields.show_field_ccds(440, ccd=range(1, 9))
from ztfquery import fields# Map of Milky Way dust extinction across all main-grid fieldsfig = fields.show_ztf_fieldvalues(key="Ebv", fieldid="main", mindec=-30, cmap="hot")# Galactic latitude mapfig = fields.show_ztf_fieldvalues(key="GalLat", cmap="RdBu_r")
For programmatic control over plots and animations, the module exposes three classes.
FieldPlotter — base visualisation class
FieldPlotter manages a Hammer-projection axes and a combined histogram-colorbar, and is the engine behind show_fields.
from ztfquery.fields import FieldPlotter, get_fields_with_band_referencefplot = FieldPlotter(inclcax=True, inclhist=True)# Draw ZTF grid outlinefplot.show_ztf_grid(which="main", edgecolor="0.6", alpha=0.15)# Draw Milky Way planefplot.show_milkyway()# Overplot specific fieldsfplot.show_fields( get_fields_with_band_reference("zr"), facecolor="C3", alpha=0.4,)fplot.fig.savefig("custom_map.png", dpi=150)
FieldAnimation — animated survey sequences
FieldAnimation extends FieldPlotter for animating sequences of ZTF observations. Pass a list of field IDs observed in order and optional per-frame properties.
from ztfquery.fields import FieldAnimationimport numpy as np# Simulate a sequence of 50 observed fieldsobserved = np.random.choice(range(200, 600), size=50)dates = [f"2024-01-{i+1:02d}" for i in range(50)]anim = FieldAnimation( fields=observed, dates=dates, facecolors="C0", alphas=0.6,)anim.launch(interval=120, repeat=True)
PalomarPlanning — nightly observability tool
PalomarPlanning computes which fields are observable from Palomar on a given night given airmass and twilight constraints.
from ztfquery.fields import PalomarPlanning, get_grid_fieldplanner = PalomarPlanning(date="2024-06-15")# Observable fraction of the night for each fieldmain_fields = get_grid_field("main")stime, ffrac = planner.get_fields_observability( main_fields, airmasslimit=[1, 1.5], minobservability=None,)# Fields observable for at least 90 minobservable = planner.get_observable_fields(main_fields)print(f"{len(observable)} fields observable tonight")# Full observability mapfig = planner.show_fields_observability(main_fields)
