Focus Diverse ePSFs

This module contains two functions that provide means to programmatically query the ACS/WFC Focus-Diverse ePSF Generator API.

psf_retriever() provides the user with the ability to perform downloads for a single image rootname, whereas
multi_psf_retriever() provides the ability to do so for multiple rootnames.

In all cases, the focus-diverse ePSFs will be downloaded to a location specified by the user.

Additionally, this module also contains a function, interp_epsf(), that allows users to interpolate the provided ePSF arrays to any arbitrary pixel coordinates, downsample the ePSF into detector space, or apply subpixel phase shifts.

We strongly recommend you read ACS ISR 2018-08 by A. Bellini et al. and ACS ISR 2023-06 by G. Anand et al. for more details on these ePSF models and tools before using them.

Examples

Define a folder location for downloaded data:

>>> download_location  = '/Users/username/download_folder/'

Retrieve a single 101x101x90 ePSF FITS file for the given rootname:

>>> from acstools.focus_diverse_epsfs import psf_retriever
>>> retrieved_download = psf_retriever('jds408jsq', download_location)

Retrieve ePSFs based on FLC images specified in an external text file (with one rootname per line):

>>> from acstools.focus_diverse_epsfs import multi_psf_retriever
>>> retrieved_downloads = multi_psf_retriever('input_ipsoots.txt', download_location)

Retrieve ePSFs using rootnames from Proposal ID 13376 obtained from astroquery:

>>> from astroquery.mast import Observations
>>> obsTable = Observations.query_criteria(
...     obs_collection = 'HST', proposal_id="13376", instrument_name = "ACS/WFC",
...     provenance_name = "CALACS")
>>> dataProducts = Observations.get_product_list(obsTable)
>>> dataProducts = dataProducts[
...     (dataProducts['productSubGroupDescription'] == 'FLC') &
...     (dataProducts['type'] == 'S')]
>>> obs_rootnames = list(dataProducts['obs_id'])
>>> retrieved_downloads = multi_psf_retriever(obs_rootnames, download_location)

Read the retrieved ePSFs from file into NumPy array:

>>> from astropy.io import fits
>>> ePSFs = fits.getdata(retrieved_download)

Interpolate a given ePSF to the given pixel location (0-indexed):

>>> from acstools.focus_diverse_epsfs import interp_epsf
>>> x = 2000  # near the middle of the detector along the X-axis
>>> y = 2000  # near the top of the WFC1 chip
>>> chip = "WFC1" # must specify we are interested in WFC1
>>> interpolated_epsf = interp_epsf(ePSFs, x, y, chip)

Similar to above but obtain the ePSF in detector space (instead of 4x supersampling):

>>> interpolated_epsf = interp_epsf(ePSFs, x, y, chip, pixel_space=True)

Similar to above but obtain the ePSF in detector space and with subpixel offsets:

>>> interpolated_epsf = interp_epsf(
...     ePSFs, x, y, chip, pixel_space=True, subpixel_x=0.77, subpixel_y=0.33)

Functions

`psf_retriever`(ipsoot, download_location[, ...])	Function to query API on AWS API Gateway for the ePSF FITS file that corresponds to a given image rootname.
`multi_psf_retriever`(input_list, ...[, ...])	Function to batch query the API on AWS API Gateway for multiple ePSFs simultaneously.
`interp_epsf`(ePSFs, x, y, chip[, ...])	Function to perform further spatial interpolations given the input ePSF array.