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.sedm module provides access to data from the SED Machine (SEDM), a low-resolution integral field spectrograph mounted at the Palomar 60-inch telescope. SEDM is the primary classification instrument for ZTF transient alerts, and its reduced data — IFU cubes and extracted 1D spectra — are hosted on the Pharos archive at Caltech. SEDMQuery handles authentication, nightly index management, and file downloads, saving everything under $ZTFDATA/sedm/redux/YYYYMMDD/.
A Pharos account is required. If you are a ZTF collaboration member and do not yet have one, email Richard Walters at rsw@astro.caltech.edu to request access.

​
SEDMQuery Class

SEDMQuery is the primary interface for fetching SEDM data. Instantiating it loads the local Pharos index; no arguments are needed for typical use. 
from ztfquery import sedm

squery = sedm.SEDMQuery()
​
load_pharosio
bool
default:"True"
Load the local PharosIO index on instantiation. Set to False only if you intend to manage the index manually.

​
Downloading target data

Use download_target_data to fetch files associated with a named ZTF target. The kind argument selects the data product type.
​
targetname
str
required
The ZTF target identifier, e.g. "ZTF18abqlpgq".
​
kind
str
required
Type of data product to retrieve. Common values:
  • "e3d" / "cube" — 3-D IFU data cubes (.fits)
  • "spec" / "spectra" — extracted 1-D spectra (.fits by default)
​
extension
str
default:".fits"
File extension filter. Use "txt" to retrieve the plain-text ASCII spectrum format used by the ZTF marshal.
​
nprocess
int
default:"4"
Number of parallel download processes.
For convenience, dedicated wrappers exist for the most common data products: Download IFU cubes: 
from ztfquery import sedm

squery = sedm.SEDMQuery()
squery.download_target_cubes("ZTF18abqlpgq")
Download extracted spectra in ASCII format: 
from ztfquery import sedm

squery = sedm.SEDMQuery()
squery.download_target_spectra("ZTF18abqlpgq", extension=".txt")
You can also call download_target_data directly and specify kind explicitly: 
from ztfquery import sedm

squery = sedm.SEDMQuery()
# Download spectra as .txt files
squery.download_target_data("ZTF18abqlpgq", kind="spec", extension="txt")

​
Retrieving local file paths

Once data has been downloaded, get_target_cubes and get_target_spectra return the local paths of matching files. 
# Paths to downloaded IFU cubes
cube_paths = squery.get_target_cubes("ZTF18abqlpgq")
print(cube_paths)

# Paths to downloaded ASCII spectra
spec_paths = squery.get_target_spectra("ZTF18abqlpgq", extension=".txt")
print(spec_paths)
Both methods return a list of absolute file paths. Only files that exist on disk are included (controlled by the exist=True default).

​
What Files and the Pharos Index

Pharos maintains per-night summary files called “what files” — plain-text lists that record every target observed during a given night and its corresponding raw IFU filename. ztfquery downloads these automatically and stores them locally under $ZTFDATA/sedm/whatfiles/ as Parquet files, with a merged index kept at $ZTFDATA/sedm/whatfiles/stored_data.parquet.
First-use warning: The very first time you use the sedm module, ztfquery downloads what files for every night since SEDM operations began (June 2018). This can take several minutes depending on your connection. All subsequent runs only fetch the dates that are missing — typically just the most recent nights.
The index is managed by the PharosIO class, which SEDMQuery wraps. You can inspect it directly if needed: 
from ztfquery import sedm

# Load the merged index from the stored Parquet file (fastest)
pio = sedm.PharosIO.load_local(stored=True)

# Inspect the whatdata MultiIndex DataFrame
print(pio.whatdata)
To update the index and pull any missing nights: 
pio.update()
update() downloads missing what files, rebuilds the merged DataFrame, and writes the updated index back to disk.

​
Reading Cubes and Spectra with pysedm

ztfquery handles downloading; reading the data products requires pysedm, the dedicated SEDM data-reduction and analysis package.
1

Download the cube

from ztfquery import sedm

squery = sedm.SEDMQuery()
squery.download_target_cubes("ZTF18abqlpgq")
2

Get the local path

cube_paths = squery.get_target_cubes("ZTF18abqlpgq")
# cube_paths is a list; take the first result
cube_file = cube_paths[0]
3

Open the cube with pysedm

import pysedm

cube = pysedm.get_sedmcube(cube_file)
cube.show(interactive=True)
cube.show(interactive=True) launches an interactive viewer that lets you click on individual spaxels and inspect the corresponding spectrum.

​
Citation

If you use a SEDM spectrum obtained since July 2018, please cite the pysedm paper: Rigault et al. 2019, arXiv:1902.08526. pysedm is the pipeline responsible for all SEDM reductions from that date forward.

Build docs developers (and LLMs) love

Get started for freeTalk to us