ztforce

ztforce — forced PSF photometry on ZTF science images.

Submodules

• ztforce._constants
• ztforce.cache
• ztforce.config
• ztforce.exceptions
• ztforce.image
• ztforce.lightcurve
• ztforce.pipeline
• ztforce.psf
• ztforce.utils
• ztforce.ztf_images

Exceptions

ConfigError	Bad or missing credentials / configuration.
FITSDownloadError	FITS file download failed after maximum retries.
NoImagesFoundError	No ZTF science images cover the requested position.
PSFBuildError	PSF model could not be built or parsed for an image.
WCSError	WCS creation or coordinate transformation failed.
ZTForceError	Base class for all ztforce exceptions.

Classes

ZTForceConfig	All runtime configuration for a ztforce session.
Lightcurve	Per-source forced-photometry lightcurve in absolute AB magnitudes.

Functions

build_config(→ ZTForceConfig)	Build a ZTForceConfig by resolving credentials in priority order.
run_forced_photometry(, data_dir, config, max_epochs, ...)	Run forced PSF photometry at (ra, dec) for all requested bands.
run_forced_photometry_batch(, data_dir, config, ...)	Run forced photometry for a list of SkyCoord targets in parallel.

Package Contents

class ZTForceConfig

All runtime configuration for a ztforce session.

irsa_user: str = ''

irsa_pass: str = ''

cutout_size_arcmin: float = 2.0

max_retries: int = 3

retry_base_delay: float = 1.0

retry_jitter: float = 0.5

default_gain: float = 6.2

build_config(irsa_user: str | None = None, irsa_pass: str | None = None, config_path: str | pathlib.Path | None = None, **overrides) → ZTForceConfig

Build a ZTForceConfig by resolving credentials in priority order.

Resolution order (highest first): 1. Direct parameters passed here 2. Environment variables ZTFORCE_IRSA_USER / ZTFORCE_IRSA_PASS 3. ~/.ztforce/config.toml [credentials] section

Raises ConfigError listing all sources tried if credentials are not found.

exception ConfigError

Bases: ZTForceError

Bad or missing credentials / configuration.

exception FITSDownloadError

Bases: ZTForceError

FITS file download failed after maximum retries.

exception NoImagesFoundError

Bases: ZTForceError

No ZTF science images cover the requested position.

exception PSFBuildError

Bases: ZTForceError

PSF model could not be built or parsed for an image.

exception WCSError

Bases: ZTForceError

WCS creation or coordinate transformation failed.

exception ZTForceError

Bases: Exception

Base class for all ztforce exceptions.

class Lightcurve(ra: float, dec: float)

Per-source forced-photometry lightcurve in absolute AB magnitudes.

ra

dec

_rows: list[dict] = []

cache_key: str = ''

add_epoch(obsjd: float, band: str, flux: float, flux_err: float, mag: float, mag_err: float, zero_point: float, flags: int, x_fit: float | None = None, y_fit: float | None = None, mag_limit: float | None = None, image_id: str | None = None) → None

Append one exposure’s measurement.

property df: pandas.DataFrame

All epochs as a DataFrame, sorted by obsjd.

property bands: list[str]

Unique bands present, in canonical g/r/i order.

get_band(band: str) → pandas.DataFrame

Return epochs for a single band, sorted by obsjd.

stack(jd_min: float | None = None, jd_max: float | None = None, bands: list[str] | None = None) → pandas.DataFrame

Inverse-variance-weighted stack of detections within a JD window.

Returns a DataFrame indexed by band with columns:

flux_stack, flux_err_stack, mag_stack, mag_err_stack, n_epochs.

rolling_stack(window: float, window_unit: str = 'days', bands: list[str] | None = None, step: float | None = None) → pandas.DataFrame

Rolling IVW stack in a sliding window.

Returns a long-format DataFrame with columns:

obsjd_center, band, flux_stack, flux_err_stack, mag_stack, mag_err_stack, n_epochs.

save(path: str | pathlib.Path) → None

Save to an Astropy ECSV file preserving all columns and metadata.

classmethod load(path: str | pathlib.Path) → Lightcurve

Load from an Astropy ECSV file saved by save().

__len__() → int

Number of epochs.

__repr__() → str

Short representation.

run_forced_photometry(ra: float, dec: float, bands: tuple[str, Ellipsis] | list[str] = ('g', 'r', 'i'), data_dir: str | pathlib.Path | None = None, config: ztforce.config.ZTForceConfig | None = None, max_epochs: int | None = None, force_recompute: bool = False, show_progress: bool = True, download_workers: int = 8, _tqdm_position: int = 0, _tqdm_leave: bool = True, _download_executor: concurrent.futures.ThreadPoolExecutor | None = None) → dict[str, ztforce.lightcurve.Lightcurve]

Run forced PSF photometry at (ra, dec) for all requested bands.

Downloads ZTF science image cutouts from IRSA, fits the source amplitude at the fixed sky position using the per-image DAOPhot PSF sidecar, and returns calibrated AB-magnitude lightcurves. Results are cached on disk; repeated calls for the same position return immediately without any network access.

Parameters:

• ra – Right ascension in decimal degrees (J2000).

• dec – Declination in decimal degrees (J2000).

• bands – ZTF bands to process. Any subset of ("g", "r", "i").

• data_dir – Root directory for the on-disk cache. Defaults to ~/.ztforce/cache when None.

• config – Credentials and runtime settings. Built from environment variables / ~/.ztforce/config.toml when None.

• max_epochs – If set, process only the most recent max_epochs exposures per band. Useful for quick tests.

• force_recompute – If True, ignore any cached lightcurve and redownload + recompute from scratch, overwriting the cache.

• show_progress – If True (default), display a tqdm progress bar.

• download_workers – Number of concurrent epoch downloads. Ignored when a shared _download_executor is supplied by the batch wrapper.

Returns:

Dict mapping band label ("g", "r", "i") to a Lightcurve. Bands with no available images are omitted.

run_forced_photometry_batch(targets: list[astropy.coordinates.SkyCoord], bands: tuple[str, Ellipsis] | list[str] = ('g', 'r', 'i'), data_dir: str | pathlib.Path | None = None, config: ztforce.config.ZTForceConfig | None = None, n_workers: int = 4, download_workers: int = 8, show_progress: bool = True) → list[dict[str, ztforce.lightcurve.Lightcurve]]

Run forced photometry for a list of SkyCoord targets in parallel.

Each target is processed by a dedicated thread; results are returned in the same order as targets. A single shared download thread pool (capped at download_workers) is used across all active source workers so that concurrency is bounded at one level only.

Parameters:

• targets – Sky positions to process.

• bands – ZTF bands to process. Any subset of ("g", "r", "i").

• data_dir – Root directory for the on-disk cache.

• config – Credentials and runtime settings.

• n_workers – Number of targets to process concurrently.

• download_workers – Total number of concurrent epoch downloads shared across all active source workers.

• show_progress – If True (default), display tqdm progress bars.

Returns:

List of band → Lightcurve dicts, one per target.