ztforce 0.1.2

Forced PSF photometry on ZTF science images

ztforce

Forced PSF photometry on ZTF science images — measures flux at a fixed sky position in every available epoch, even below the detection threshold, producing a calibrated AB-magnitude lightcurve.

Installation

pip install ztforce

Python 3.10–3.13 is supported.

Credentials

ztforce downloads ZTF science images from IRSA and requires an IRSA account (free at irsa.ipac.caltech.edu). Set your credentials in one of three ways:

Environment variables (recommended for scripts/CI):

export ZTFORCE_IRSA_USER=your_username
export ZTFORCE_IRSA_PASS=your_password

Config file at ~/.ztforce/config.toml:

[credentials]
irsa_user = "your_username"
irsa_pass = "your_password"

Direct argument:

from ztforce import build_config
config = build_config(irsa_user="your_username", irsa_pass="your_password")

Quick start

from ztforce import run_forced_photometry

# Measure flux at a fixed position across all ZTF g- and r-band epochs.
# A tqdm progress bar tracks downloads and PSF fitting; results are cached
# on disk so repeated calls return instantly.
lcs = run_forced_photometry(ra=210.08, dec=-6.88, bands=["g", "r"])

lcs["g"].df              # pandas DataFrame of all epochs
lcs["g"].stack()         # inverse-variance weighted stack of detections
lcs["g"].save("my_source_g.ecsv")   # save to ECSV

Batch processing

from astropy.coordinates import SkyCoord
from ztforce import run_forced_photometry_batch

targets = SkyCoord(ra=[210.08, 130.13], dec=[-6.88, 19.70], unit="deg")

# Processes targets in parallel; downloads are shared across all workers.
results = run_forced_photometry_batch(targets, bands=["g", "r"], n_workers=4)

results[0]["g"].stack()  # stacked photometry for first target, g-band

Related services

Several official ZTF services offer complementary photometry — ztforce fills a gap none of them cover:

Service	What it does	Why you'd use ztforce instead
ZTF Forced Photometry Service (ZFPS) (Masci et al. 2023)	Forced PSF photometry on ZTF difference images at user positions	Science-image photometry avoids subtraction artifacts; no account/queue required; runs locally
ZTF DR lightcurves (IRSA)	Catalog lightcurves for sources detected in ZTF data releases	Forced photometry works for transients and sub-threshold sources not in any catalog and at any arbitrary position
ZuberCal	Ubercalibrated PSF photometry catalog for PS1-matched ZTF sources	Only covers sources detected in PS1; ztforce works at any arbitrary position

ztforce is designed for cases where the source may not appear in any existing catalog — supernovae, kilonova, flares, or any transient — and you need calibrated flux measurements at a fixed sky position across every available epoch, including non-detections.

Dev Guide - Getting Started

Before installing any dependencies or writing code, it's a great idea to create a virtual environment. LINCC-Frameworks engineers primarily use conda to manage virtual environments. If you have conda installed locally, you can run the following to create and activate a new environment.

>> conda create -n <env_name> python=3.11
>> conda activate <env_name>

Once you have created a new environment, you can install this project for local development using the following commands:

>> ./.setup_dev.sh
>> conda install pandoc

Notes:

1. ./.setup_dev.sh will initialize pre-commit for this local repository, so that a set of tests will be run prior to completing a local commit. For more information, see the Python Project Template documentation on pre-commit
2. Install pandoc allows you to verify that automatic rendering of Jupyter notebooks into documentation for ReadTheDocs works as expected. For more information, see the Python Project Template documentation on Sphinx and Python Notebooks