PSF Generation

Functions included here relate to the creation of PSFs, which will later be drizzled by the HST, JWST, or Roman pipeline functions.

These functions can also be used on their own to create single frame PSFs in python using consistent syntax. See this example for more details.

spike.psfgen.acsepsf(coords, img, imcam, pos, plot=False, verbose=False, writeto=True, clobber=False)

Generate ACS/WFC Focus-Diverse ePSFs from STScI web tool.

Works for only most popular filters: F435W, F475W, F502N, F555W, F606W, F625W, F658N, F660N, F775W, F814W, F850LP

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – Only available for ‘ACS/WFC’.
pos (list) – [X, Y, chip, filter] as output from spike.tools.checkpixloc. If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions. This is in addition to the .psf file saved by PSFEx. No 2D PSF model is saved by PSFEx by default, but this can be toggled in the tools.pypsfex arguments.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)

spike.psfgen.effpsf(coords, img, imcam, pos, plot=False, verbose=False, mask=True, writeto=True, clobber=False, fov_arcsec=6, norm=1., starselect='DAO', starselectargs={'fwhm': 10}, thresh=125, usermask=None, maskval=None, epsfargs={'oversampling': 1, 'progress_bar': True, 'maxiters': 10})

Generate PSFs using the empirical photutils.epsf routine.

NOTE: For frames with fewer stars, this method is prone to artifacts. This can be ameliorated by using a lower detection threshold, but the overall quality of the output PSF may be lower.

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – Specification of instrument/camera used to capture the images (e.g., ‘ACS/WFC’, ‘WFC3/IR’, ‘WFPC’, ‘WFPC2’, ‘MIRI’, ‘NIRCAM’, ‘NIRISS/Imaging’). For ‘WFPC’ and ‘WFPC2’, the camera is selected by-chip and should not be specified here.
pos (list) – Location of object of interest (spatial and spectral). [X, Y, chip, filter] If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
mask (bool) – If True, uses data quality array to mask some pixels.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
fov_arcsec (float) – “Diameter” of model PSF image in arcsec.
norm (float) – Flux normalization for output PSF model.
starselect (str) – ‘DAO’, ‘IRAF’, or ‘peak’, which use DAOStarFinder, IRAFStarFinder, and find_peaks from photutils respectively.
starselectargs (dict) – Keyword arguments for the chosen star detection method.
thresh (float) – Threshold for star detection (in multiples of standard deviations). Note that the output ePSF is incredibly sensitive to this parameter, as it sets which stars are used to build the model.
usermask (arr) – If mask = True, used in addition to the DQ array to mask bad pixels. Must be the same dimensions as the data array.
maskval (float) – Value to assign to masked pixels. If None, default set by star seletion method. Otherwise, can be np.nan or number. Default for ‘IRAF’ is np.nan, default for ‘DAO’ is 0.
epsfargs (dict) – Keyword arguments for the EPSFBuilder. Default in spike is to not oversample the PSF, but the regridding is all handled during the creation of the coord-specific model.

Returns:

ePSF model PSF

spike.psfgen.jwpsf(coords, img, imcam, pos, plot=False, verbose=False, writeto=True, clobber=False, fov_arcsec=6, sample=4, regrid=True, image_mask=None, pupil_mask=None, savefull=False, **calckwargs)

Generate JWST and Roman PSFs using WebbPSF/STPSF. Note: reference to the WebbPSF name is maintained here in lieu of STPSF to avoid confusion with the generation of empirical STDPSFs.

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – Specification of instrument/camera used to capture the images (e.g., ‘MIRI’, ‘NIRCAM’, ‘NIRISS/Imaging’). If ‘NIRISS’ specified alone, assumes the imaging mode.
pos (list) – Location of object of interest (spatial and spectral).[X, Y, chip, filter] If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions. This is in addition to the 2D PSF models saved by WebbPSF (which will be saved as img_psf.fits).
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
fov_arcsec (float) – “Diameter” of model PSF image in arcsec.
sample (float) – Factor by which to oversample the PSF.
regrid (bool) – If True, will (interpolate and) regrid model PSF to image pixel scale.
image_mask (str) – Image mask argument for WebbPSF.
pupil_mask (str) – Pupil mask argument for WebbPSF.
savefull (bool) – If True, save the full multi-extension WebbPSF/STPSF output.
**calckwargs – Additional arguments for calc_psf() – see https://stpsf.readthedocs.io/en/latest/usage.html#. Should be fed to spike.psf.jwst/roman in kwargs as a dictionary called calckwargs.

Returns:

WebbPSF model PSF

spike.psfgen.psfex(coords, img, imcam, pos, plot=False, verbose=False, writeto=True, clobber=False, savepsfex=False, seconf=None, psfconf=None, regrid=True, mask=True, maskparams={})

Generate PSFs using PSFEx.

NOTE: For frames with fewer stars, this method is prone to artifacts, which is exacerbated by using a lower detection threshold. (Also important to note that using the parallel option with PSFEx may require additional attention to ensuring files do not overwrite each other given the default naming scheme for .cat and .psf files and subsequent steps to rename them.)

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
imcam (str) – Specification of instrument/camera used to capture the images (e.g., ‘ACS/WFC’, ‘WFC3/IR’, ‘WFPC’, ‘WFPC2’, ‘MIRI’, ‘NIRCAM’, ‘NIRISS/Imaging’). For ‘WFPC’ and ‘WFPC2’, the camera is selected by-chip and should not be specified here.
img (str) – Path to image for which PSF is generated.
pos (list) – [X, Y, chip, filter] as output from spike.tools.checkpixloc. If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions. This is in addition to the .psf file saved by PSFEx. No 2D PSF model is saved by PSFEx by default, but this can be toggled in the tools.pypsfex arguments.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
savepsfex (str) – If ‘fits’ or ‘arr’ save 2D model to that format.
seconf (str) – Path to SExtractor configuration file if not using default.
peconf (str) – Path to PSFEx configuration file if not using default.
regrid (bool) – If True, will (interpolate and) regrid model PSF to image pixel scale.
mask (bool) – If mask, apply mask generated by spike.tools.mask_fits to remove bad pixels.
maskparams (dict) – Any additional parameters to pass to spike.tools.mask_fits.

Returns:

2D PSFEx PSF model

spike.psfgen.stdpsf(coords, img, imcam, pos, plot=False, verbose=False, writeto=True, clobber=False, fov_arcsec=6, norm=1, regrid=True)

Coordinate-specific PSFs from STDPSF model grids for HST, JWST.

Makes use of https://www.stsci.edu/~jayander/HST1PASS/LIB/PSFs/STDPSFs/ and https://www.stsci.edu/~jayander/JWST1PASS/LIB/PSFs/STDPSFs/.

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – Specification of instrument/camera used to capture the images (e.g., ‘ACS/WFC’, ‘WFC3/IR’, ‘WFPC’, ‘WFPC2’, ‘MIRI’, ‘NIRCAM’, ‘NIRISS/Imaging’). For ‘WFPC’ and ‘WFPC2’, the camera is selected by-chip and should not be specified here. If ‘NIRISS’ specified alone, assumes the imaging mode.
pos (list) – Location of object of interest (spatial and spectral).[X, Y, chip, filter] If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
fov_arcsec (float) – “Diameter” of model PSF image in arcsec.
norm (float) – Flux normalization for output PSF model.

Returns:

STDPSF model PSF

spike.psfgen.tinygillispsf(coords, img, imcam, pos, plot=False, verbose=False, keep=False, writeto=True, clobber=False, specchoice='blackbody', listchoice='G5V', temp=6000., specalpha=1., specbeta=1., fov_arcsec=6., despace=0., sample=1., linearfit=False, regrid=True)

Generate HST PSFs using TinyTim and the parameter changes laid out in Gillis et al. (2020), which were tested on ACS imaging. As such, this method is not recommended for instruments other than ACS or cameras other than WFC.

Note that the Gillis et al. (2020) code will be downloaded to your working directory. If keep = False (default), it will be removed after use.

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – ‘ACS/WFC’ is the only recommended instrument/camera combination for this PSF generation method.
pos (list) – Location of object of interest (spatial and spectral).[X, Y, chip, filter] If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
keep (bool) – If True, retains make_psf.py (Gillis et al. 2020)
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions. This is in addition to the 2D PSF model saved by TinyTim.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
specchoice (str) – ‘list’, ‘blackbody’, ‘plaw_nu’, ‘plaw_lam’ – if ‘list’, must also specify listchoice; if ‘blackbody’, must also specify temp; if ‘plaw_nu’, must also specify specalpha; and if ‘plaw_lam’, must also specify specbeta.
listchoice (str) – One of ‘O5’, ‘O8F’, ‘O6’, ‘B1V’, ‘B3V’, ‘B6V’, ‘A0V’, ‘A5V’, ‘F6V’, ‘F8V’, ‘G2V’, ‘G5V’, ‘G8V’, ‘K4V’, ‘K7V’, ‘M1.5V’, ‘M3V’
temp (float) – Temperature of blackbody spectrum in K.
specalpha (float) – Spectral index alpha for F(nu)~nu^alpha.
specbeta (float) – Spectral index alpha for F(lambda)~lambda^beta.
fov_arcsec (float) – “Diameter” of model PSF image in arcsec.
despace (float) – Focus, secondary mirror despace in micron. Scaled by 0.011 and added to the 4th Zernike polynomial.
sample (float) – Factor by which to undersample the PSF. Default is not to undersample.
linearfit (bool) – Use linear fit rather than Gillis et al. amended Zernike polynomials.
regrid (bool) – If True, will (interpolate and) regrid model PSF to image pixel scale.

Returns:

TinyTim model PSF using amended Gillis et al. (2020) parameters

spike.psfgen.tinypsf(coords, img, imcam, pos, plot=False, verbose=False, writeto=True, clobber=False, ebmv=None, av=None, wmag=None, jitter=None, major=None, minor=None, angle=None, specchoice='blackbody', listchoice='G5V', temp=6000., specalpha=1., specbeta=1., fov_arcsec=6., despace=0.)

Generate HST PSFs using TinyTim. All of the options from TinyTim are easily available here except custom filters and subsampling, as they complicate use with spike. If you would like a subsampled Tiny Tim PSF model, please use spike.psfgen.tinygillispsf() instead.

Parameters:

coords (str or astropy skycoord object) – Coordinates of object of interest.
img (str) – Path to image for which PSF is generated.
imcam (str) – Specification of instrument/camera used to capture the images (e.g., ‘ACS/WFC’, ‘WFC3/IR’, ‘WFPC’, ‘WFPC2’). For ‘WFPC’ and ‘WFPC2’, the camera is selected by-chip and should not be specified here.
pos (list) – Location of object of interest (spatial and spectral). [X, Y, chip, filter] If None, will find location based on coordinates and instrument/camera.
plot (bool) – If True, saves .pngs of the model PSFs. (Not affected by clobber; images with the same name are overwritten by default.)
verbose (bool) – If True, prints progress messages.
writeto (bool) – If True, will write 2D model PSF (differentiated with ‘_topsf’ suffix) and will amend relevant image WCS information/remove extraneous extensions. This is in addition to the 2D PSF model saved by TinyTim.
clobber (bool) – If True, will overwrite existing files with the same name on save. (Default state – clobber = False – is recommended.)
ebmv (float) – Interstellar extinction, specified by reddening in mag. If specified, av should not be.
av (float) – Interstellar extinction, specified by visual extinction in mag. If specified, ebmv should not be.
wmag (float) – Fraction of wavelengths to use in generating polychromatic PSFs (if wmag > 1, uses more than the default; if wmag < 1, uses fewer).
jitter (float) – Symmetric jitter in mas.
major (float) – Axisymmetric major axis jitter in mas.
minor (float) – Axisymmetric minor axis jitter in mas.
angle (float) – Angle of offset for axisymmetric jitter.
specchoice (str) – ‘list’, ‘blackbody’, ‘plaw_nu’, ‘plaw_lam’ – if ‘list’, must also specify listchoice; if ‘blackbody’, must also specify temp; if ‘plaw_nu’, must also specify specalpha; and if ‘plaw_lam’, must also specify specbeta.
listchoice (str) – One of ‘O5’, ‘O8F’, ‘O6’, ‘B1V’, ‘B3V’, ‘B6V’, ‘A0V’, ‘A5V’, ‘F6V’, ‘F8V’, ‘G2V’, ‘G5V’, ‘G8V’, ‘K4V’, ‘K7V’, ‘M1.5V’, ‘M3V’
temp (float) – Temperature of blackbody spectrum in K.
specalpha (float) – Spectral index alpha for F(nu)~nu^alpha.
specbeta (float) – Spectral index alpha for F(lambda)~lambda^beta.
fov_arcsec (float) – “Diameter” of model PSF image in arcsec.
despace (float) – Focus, secondary mirror despace in micron. Scaled by 0.011 and added to the 4th Zernike polynomial.

Returns:

TinyTim model PSF