Astrometry

To make full use of the WFSS data, it is necessary to take contemporaneous data in a standard imaging mode at the same position on the sky (colloquially called pre-imaging, post-imaging, or direct imaging). These data are used to deduce the exact position of the WFSS data by comparing to either existing imaging or a standard astrometric catalog (ie. Gaia; see Mack et al. 2022). Therefore, it is critical to ensure that any tweaks to the world-coordinate system (WCS) of the direct imaging are propagated to the corresponding WFSS imaging. Therefore slitlessutils provides functionality to sync the WCS between the direct and WFSS data.

The standard tools for updating the WCS keywords (ie. drizzlepac and tweakreg) record previous WCS solutions in the WCSNAME* keywords, where WCSNAME refers to the active solution and earlier solutions are encoded with alphabetic characters (e.g. WCSNAMEA). This last token is referred to as the key, and so one must specify the starting (key0) and the ending (key) key.

For much of the HST data, the direct imaging has been matched to some existing astrometric catalog (often Gaia dr3), but the WFSS data is left at a less-refined state.

Important

Astrometric corrections for the WFSS data from HST are almost always needed.

The corrections can be either downgrading the astrometry in the direct image to match that in the WFSS, or upgrading the WFSS to match that of the direct image.

Note

It is the responsibility of the user to verify that the WCS in the WFSS and direct image(s) are on the same astrometric reference, which is usually (but not always) answered by the WCSNAME keyword. However, if the WCS solutions are inconsistent, then any subsequent spectral extraction or modeling will be assuredly incorrect.

Listing WCS (list_wcs())

This is a convenience function to list the WCS information for a collection of dispersed and direct images. This is often run as a command-line tool:

$ listwcs flt

This will list the WCSs for all the flt files in the current-working directory.

Downgrading WCS (downgrade_wcs())

Here we roll back the “active” WCS in a direct image to an earlier version, which is meant to match that of the WFSS data. This is usually the simpler option, but it will hamper using other (likely deeper) direct imaging for selecting the spectral traces for extraction. In this case, we simply take the CRVAL and CD keywords from a previous WCS solution and replace them in the active solution, but there is a direct API for this:

import slitlessutils as su

newfile = su.core.preprocess.astrometry.downgrade_wcs('a_direct_image_file_flt.fits', key='A')

will replace the WCS solution from WCSNAMEA into the active solution (ie. WCSNAME), and return the name of the file that contains this WCS. One can also pass a list of filenames to downgrade_wcs(), which would then return a list of filenames.

Warning

We expect this method will change as the astrometry description changes.

Upgrading WCS (upgrade_wcs())

Here we find the affine transformation between any two WCSs from the direct image, and apply it to the equivalent WCS in the grism image. For this, slitlessutils loads the CD matrix from a astropy WCS object as:

\[\begin{split}\mathrm{CD} = \left(\begin{array}{cc} \mathrm{CD}1\_1 & \mathrm{CD}1\_2 \\ \mathrm{CD}2\_1 & \mathrm{CD}2\_2 \end{array}\right)\end{split}\]

If the initial and final CD-matrices for the direct image are \(\mathrm{CD}_{0,d}\) and \(\mathrm{CD}_{1,d}\) (respectively), then the affine transformation matrix is given as:

\[A_d = \mathrm{CD}_{1,d} \mathrm{CD}^{-1}_{0,d}\]

This transformation matrix is then applied to the CD matrix from the WFSS image (\(\mathrm{CD}_0\)):

\[\mathrm{CD}_1 = A_d\, \mathrm{CD}_0\]

Similarly, we must adjust the CRVAL keywords, which are loaded from the WCS object as:

\[\begin{split}\mathrm{CRVAL} = \left(\begin{array}{c}\mathrm{CRVAL}1 \\ \mathrm{CRVAL}2\end{array}\right)\end{split}\]

Again, if \(\mathrm{CRVAL}_{0,d}\) and \(\mathrm{CRVAL}_{1,d}\) refer to the CRVAL-vectors for the initial and final WCS solution from the direct image, then the perturbation vector is:

\[\Delta \mathrm{CRVAL}_d = \mathrm{CRVAL}_{1,d} - \mathrm{CRVAL}_{0,d}\]

which can be applied to the CRVAL vector from the WFSS image with the same WCS key used to instantiate \(\mathrm{CRVAL}_0\):

\[\mathrm{CRVAL}_1 = \mathrm{CRVAL}_0 + \Delta \mathrm{CRVAL}_d\]

This affine tweaking is implemented in the convenience function upgrade_wcs():

import slitlessutils as su

newfile = su.core.preprocess.astrometry.upgrade_wcs('direct_image_reference_flt.fits', 'wfss_image_flt.fits')

This will compute the affine transformation between WCSNAME and WCSNAMEA from direct_image_reference_flt.fits and apply it to the WSCNAMEA astrometry in wfss_image_flt.fits. It writes the updated image to a new file, whose name is returned as newfile. The second argument can also be a list or tuple, and each of those images will be similarly tweaked, and in which case newfile will be a similar list.

Note

In both above cases, a new file will be written if inplace==False and newfile==None, and rules for generating this name are given in utils.py.