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.marshal module provides a Python interface to the ZTF-I Growth Marshal, the target management system used during the first phase of ZTF operations. It lets you query target tables containing coordinates, classifications, and redshifts, as well as download and visualise spectra and light curves — all stored locally under $ZTFDATA/marshal/.
The Growth Marshal covers ZTF-I data. For ZTF-II sources, use the fritz module instead. Requirements
Credentials
The first time you query the Marshal without an explicit auth= argument, ztfquery will prompt for your username and password and store them encrypted in ~/.ztfquery. All subsequent calls reuse the stored credentials automatically.
To pass credentials explicitly:
from ztfquery import marshal
m = marshal.MarshalAccess()
m.load_target_sources(auth=["your_username", "your_password"])
MarshalAccess
MarshalAccess is the main class for working with Marshal target tables. Instantiate it and load the targets you need, or reload a previously saved snapshot from disk.
Loading all targets
from ztfquery import marshal
# Instantiate
m = marshal.MarshalAccess()
# Download all targets you have access to (takes ~1 min the first time)
m.load_target_sources()
# Inspect the result
print(m.target_sources)
# DataFrame with columns:
# [candid, name, ra, dec, classification, field, redshift,
# creationdate, iauname, id, lastmodified, rcid,
# release_auth, release_status]
Loading a specific program
Pass the program argument to restrict the download to one of your Marshal programs:
from ztfquery import marshal
m = marshal.MarshalAccess()
m.load_target_sources(program="Cosmology")
load_target_sources accepts program="*" (the default) to load all programs you have access to, a single program name string, or a list of program names.
Fast loading from local cache
Every successful call to load_target_sources() saves the result to $ZTFDATA/marshal/. Use MarshalAccess.load_local() to reload that snapshot instantly without hitting the network.
from ztfquery import marshal
m = marshal.MarshalAccess.load_local()
# Optionally filter to a specific program:
# m = marshal.MarshalAccess.load_local(program="Cosmology")
Target Accessors
After loading target_sources, several methods let you retrieve target-level information.
get_target_data
Returns a filtered DataFrame containing all columns for the requested target(s):
m.get_target_data(["SN2018zd", "ZTF18aahflrr", "at2018akx"])
# Returns a DataFrame with columns:
# candid, name, ra, dec, classification, field, redshift,
# creationdate, iauname, id, lastmodified, rcid, release_auth, release_status
get_target_coordinates
m.get_target_coordinates(["SN2018zd", "ZTF18aahflrr", "at2018akx"])
# ra dec
# 0 94.513250 94.513250
# 2 150.846667 -26.182181
# 3 153.923187 14.119114
get_target_redshift
m.get_target_redshift(["SN2018zd", "ZTF18aahflrr"])
get_target_classification
m.get_target_classification(["SN2018zd", "ZTF18aahflrr"])
# Returns classification labels such as: SN Ia, SN Ib, AGN, None, etc.
ZTFQuery.load_metadata() to pull IRSA data for a Marshal target:
from ztfquery import query, marshal
m = marshal.MarshalAccess.load_local()
meta_kwargs = m.get_target_metadataquery("SN2018zd")
zquery = query.ZTFQuery()
zquery.load_metadata(**meta_kwargs)
Retrieving target metadata (coordinates, redshift, classification) for 1 target takes roughly the same time as retrieving it for 1,000 targets, because the entire target list is loaded once. Always query all your targets together in a single call for maximum efficiency.
Spectra
Download spectra
from ztfquery import marshal
# Store to $ZTFDATA/marshal/spectra/ZTF18abcdef/ (default)
marshal.download_spectra("ZTF18abcdef")
# Store to a custom directory
marshal.download_spectra("ZTF18abcdef", dirout="/path/to/my/spectra/")
# Return the data in memory without storing (dirout=None)
spectra = marshal.download_spectra("ZTF18abcdef", dirout=None)
# spectra = {filename: readlines_array_of_ascii_spectral_data, ...}
Load stored spectra
Once downloaded with dirout="default", reload spectra from disk:
spectra = marshal.get_local_spectra("ZTF18abcdef")
# Returns: {filename: readlines_array_of_ascii_spectral_data}
Light Curves
Download light curves
from ztfquery import marshal
# Store to $ZTFDATA/marshal/lightcurves/ZTF18abcdef/ (default)
marshal.download_lightcurve("ZTF18abcdef")
download_lightcurve accepts the same dirout options as download_spectra:
dirout="default" — saves under $ZTFDATA/marshal/lightcurves/{name}/dirout="path" — saves to a custom pathdirout=None — returns data in memory as a pandas.DataFrame without storing
Load and plot light curves
get_local_lightcurves with the default only_marshal=True returns the primary marshal light curve as a single pandas.DataFrame. Pass only_marshal=False to get a {filename: DataFrame} dict of all stored files.
from ztfquery import marshal
# Download
marshal.download_lightcurve("ZTF18abcdef")
# Load from disk — returns a single DataFrame (only_marshal=True by default)
lc_df = marshal.get_local_lightcurves("ZTF18abcdef")
# Plot
marshal.plot_lightcurve(lc_df)
plot_lightcurve supports ZTF (r, g, i), Swift UVOT, and Liverpool IO:O photometry styles out of the box.
Full Workflow Example
The following example shows a complete end-to-end workflow: loading targets, inspecting a subset, downloading their spectra and light curves, and plotting.
from ztfquery import marshal, query
# --- 1. Load targets (fast from cache) ---
m = marshal.MarshalAccess.load_local()
# --- 2. Inspect a subset ---
targets = ["SN2018zd", "ZTF18aahflrr", "at2018akx"]
print(m.get_target_coordinates(targets))
print(m.get_target_classification(targets))
# --- 3. Download spectra and light curves ---
for name in targets:
marshal.download_spectra(name) # → $ZTFDATA/marshal/spectra/{name}/
marshal.download_lightcurve(name) # → $ZTFDATA/marshal/lightcurves/{name}/
# --- 4. Load and plot a light curve ---
lc_df = marshal.get_local_lightcurves("SN2018zd")
marshal.plot_lightcurve(lc_df)
# --- 5. Build a ZTFQuery metadata query for IRSA ---
meta_kwargs = m.get_target_metadataquery("SN2018zd")
zquery = query.ZTFQuery()
zquery.load_metadata(**meta_kwargs)
Local Storage Layout
Data downloaded with dirout="default" are organised under $ZTFDATA/marshal/:
$ZTFDATA/marshal/
├── spectra/
│ └── ZTF18abcdef/
│ └── <instrument>_<date>_<target>.ascii
├── lightcurves/
│ └── ZTF18abcdef/
│ └── marshal_plot_lc_lightcurve_ZTF18abcdef.csv
└── <program>_target_sources.csv
Make sure the $ZTFDATA environment variable points to a writable directory before calling any function with dirout="default". See the installation guide for setup instructions. 