The Neil Gehrels Swift Observatory

Apply Aspect Correction to UVOT Data

Overview:

Aspect correction is essential to obtain correct sky coordinates of UVOT sources, and to ensure that individual exposures are added without offsets. This thread gives a brief instruction on how to use the Swift FTOOLS aspect correction tool.

Read this thread if you want to: Apply an aspect correction to UVOT data.

Last update: July 19, 2021

Aspect corrections (i.e., shifts and rotations) can be applied to UVOT sky coordinate images using the Swift tool "uvotskycorr". As in other threads, we will use Swift observations of GRB 050525A (sequence 00130088000) as an example.

Make sure that you have installed the WCSTools on your machine, which are needed to run the UVOT aspect correction. In particular, make sure that the WCSTool "scat" is installed.

The "uvotskycorr" tool needs to be run twice to obtain aspect corrected UVOT images:

  1. First, the aspect corrections need to be computed by comparing UVOT source positions with those of catalogued sources.
  2. In the next step the computed aspect corrections need to be applied to the images.

You can obtain a list of the parameters and default settings of the "uvotskycorr" task by typing:

$ plist uvotskycorr

Help on "uvotskycorr" is available by typing:

$ fhelp uvotskycorr

The parameters for "uvotskycorr" are:

what
Whether to find corrections (what=ID) or apply corrections (what=SKY)
skyfile
Input SKY image file name(s)
corrfile
Input corrections file. If "what=SKY" the aspect corrections to be applied will be read from this file. If "what=ID" then set "corrfile=NONE".
attfile
Input attitude file
outfile
Output file name. If "what=ID" the aspect corrections will be written to this file. If "what=SKY" then set "outfile=NONE".
(starid)
Parameters to pass to the star identification routine. See the fhelp page for "tristarid" for dettails of these parameters.
(catspec)
Star catalogue descriptor file for "scat". See the fhelp page for "catspec" for details about this file.
(options)
Options for the aspect correction process. See the fhelp page for "uvotskycorr" for details about these options. In general "options=NONE" will work well.
(flagfile)
Optional data quality file(s). Generated by "uvotflagqual"
(cleanup)
Delete temporary files?
(history)
Write history keywords?
(clobber)
Overwrite existing files?
(chatter)
Standard HEAdas chatter parameter (min=0,max=5)

Optional parameters are given in parenthesis.

The "what" parameter switches between computing ("what=ID") and applying ("what=SKY") aspect corrections. If aspect corrections are computed, the "outfile" parameter specifies the file used to write the aspect corrections to. That file is read in the next step, when the aspect solutions are applied to the image(s) ("what=SKY"). The "starid" parameters set the values passed to a subroutine which control the star identification settings. The default parameters for "starid" are optimized, and usually give best results. Users can learn more about these parameters from the fhelp page for "tristarid" by typing:

$ fhelp tristarid

Star catalogue information is required to perform the aspect correction. The "catspec" parameter gives the name of the catalogue descriptor file. This file describes how catalogue information is to be loaded. It can point to a local catalogue installed on your computer or one that is to be queried over the Web. More information on how to access the catalog information is available here:

$ fhelp catspec

For example, one can set "catspec=usnob1.spec" to read the parameter file usnob1.spec, which looks like this:

# partition summary
type => StarID::SearchCat
fields => ID,RA,DEC,MAGB1,MAGR1,MAGB2,MAGR2,MAGN,PM,NI,SG,DIST
data => USNOB1
catalog/type => Indexed
catalog/n => 4

subtype => ub1
sort => m3
envvar => UB1_PATH
# USNO B1 server from Harvard:
location => http://tdc-www.harvard.edu/cgi-bin/scat
limit => 2000
filter.match.arcsec => 20

In this case the USNO-B1.0 star catalogue is retrieved over the Web from Harvard.

The scat tool and catspec values can be checked by running scat with the envvar and location for some sky position, for example:


	$ export UB1_PATH=http://tdc-www.harvard.edu/cgi-bin/scat
	$ scat -c ub1 123.456 -32.123 J2000 -d -y 2021 -r 100 -n 3
	0578.0215636 123.4261458 -32.1303306   10.59  10.45  10.55  10.45  10.42 10  0  0  94.77
	0579.0217499 123.4716042 -32.0999333   15.70  14.59  15.33  14.33  13.55  0  5  0  95.71
	0578.0215637 123.4264375 -32.1337139   17.52  99.99  99.99  99.99  13.80  0  2  0  98.03
	$

1. Calculate the Aspect Correction:

To aspect-correct V-band UVOT images for our example (GRB 050525A), the aspect solution has to be calculated first:

$ uvotskycorr what=ID skyfile=00130088000/uvot/image/sw00130088000uvv_sk.img corrfile=NONE attfile=00130088000/auxil/sw00130088000sat.fits outfile=00130088000/out/CORR.00035227003.ALL starid="mag.err=5 rot.error=60" catspec=usnob1.spec options=NONE flagfile=NONE

This command reads the input image and the spacecraft attitude file, and writes the output into a directory which needs to be created first. In addition, we opted to pass two parameters to the star identification subroutine. These are: allow a tolerance of 5 magnitudes between the UVOT magnitudes and the catalogued magnitudes of the sources ("mag.err=5") and allow a rotation of the UVOT image of up to 60 arcmin ("rot.error=60"). The "catspec" parameter gives the location of the star catalogue as described above. You can give a comma-delimited list of UVOT images to be aspect-corrected or you can provide a file which lists all of the images to be aspect-corrected using the "skyfile=@<file>" syntax.

2. Apply the Aspect Correction:

To apply the aspect corrections "uvotskycorr" needs to read in the aspect solution file that was created above.

$ uvotskycorr what=SKY skyfile=00130088000/uvot/image/sw00130088000uvv_sk.img corrfile=00130088000/out/CORR.00035227003.ALL attfile=00130088000/auxil/sw00130088000sat.fits outfile=NONE catspec=usnob1.spec

3. Check the Aspect Correction:

Check which header extensions were modified by "uvotskycorr" by inspecting the headers of the file extensions. The FITS keyword ASPCORR is set to ASPCORR = DIRECT if the aspect correction was found and applied.

$ ftlist sw00130088000uvv_sk.img K include="EXTNAME,ASPCORR"

Next, all individual exposures, except the settling images (header extensions 1 and 2 in our example), and except the file extensions which were not successfully aspect corrected (none in our example), need to be added by running the command "uvotimsum":

$ uvotimsum sw00130088000uvv_sk.img uvv_sum.fits exclude=1,2 chatter=1

Open the summed image, "uvv_sum.fits", with DS9 or FV and visually inspect the image to see the improvement in the aspect solution.

The images below give the uncorrected (left) and corrected (right) summed V-band images of GRB 050525A. The XRT error position of GRB 050525A is marked by a circle with a radius of 6-arcsec as reported in GCN Circulars. Note that the uncorrected image shows significant offsets between individual exposures. These offsets have been corrected for in the aspect-corrected image. The afterglow candidate for the GRB (marked by two lines) is much fainter in the uncorrected image due to the offsets of the individual exposures. The aspect-corrected image also shows updated centroid positions of all UVOT sources, which also appear more point-like.

uncorrectced and aspect corrected V-band image