ztforce.pipeline

Orchestration: forced PSF photometry with source-level batch parallelism.

Functions

_cache_key(→ str)

12-hex-char hash of the parameters that affect photometry output.

_download_epoch(→ tuple[pandas.Series, pathlib.Path, ...)

Download the FITS cutout and PSF sidecar for one epoch.

_process_one_epoch(→ dict)

Run forced PSF photometry for one epoch. Returns a result dict.

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.

Module Contents

_cache_key(config: ztforce.config.ZTForceConfig, max_epochs: int | None) → str[source]

12-hex-char hash of the parameters that affect photometry output.

_download_epoch(row: pandas.Series, tmp_dir: pathlib.Path, ra: float, dec: float, config: ztforce.config.ZTForceConfig) → tuple[pandas.Series, pathlib.Path, pathlib.Path][source]

Download the FITS cutout and PSF sidecar for one epoch.

Raises on failure so the caller can skip this epoch.

_process_one_epoch(fits_fpath: str, psf_fpath: str, ra: float, dec: float, band: str, image_id: str, config: ztforce.config.ZTForceConfig) → dict[source]

Run forced PSF photometry for one epoch. Returns a result dict.

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][source]

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]][source]

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.