uvotapercorr - aperture correction for SWIFT-UVOT source count rates.


uvotapercorr cntrate=<float> ratesig=<float> aperad=<float> fwhmsig=<float> filter=<string> psffile=<filename> chatter=<enumerated integer>


The Swift/UVOT photometry aperture used to derive the photometric zero points is a circle of radius 5 arcsec (see Poole et al. 2008, MNRAS, 383, p627 for details). This aperture contains approximately 85% of the photons from a point source, and keeps background contamination to a reasonable level. It is large enough to smooth out the ubiquitous modulo-8 fixed-pattern image noise which results from the electronic oversampling of UVOT detector pixels. In cases where UVOT point sources are faint and approach the background-limited detection threshold, it is desirable to perform source detection using smaller apertures. While making the aperture radius smaller than 5 arcsec increases the signal-to-noise, and consequently the detection probability, the drawback is that counts within the wings of the source point-spread function (PSF) are ignored and the brightness of the source underestimated. Uvotapercorr is a tool to calculate and add the neglected photons within the PSF wings to small-aperture count rates so that magnitude conversions can be performed accurately.

The method adopted in this tool is a quick-and-dirty approach with a number of critical caveats which are discussed below. The mean PSFs for each broadband filter are characterized as encircling energy functions in tables within the Swift/UVOT CALDB; see $CALDB/data/swift/uvota/cpf/psf/ and the release note at . The U, B, and V PSFs are all similar in form and width. The UVW1, UVM2 and UVW2 PSFs are generally narrower in the core with broader wings compared to the optical filters. The PSFs are employed to extrapolate count rates measured within a small aperture to count rates predicted from within the 5 arcsec aperture used to derive the photometric zero points. This is achieved cheaply by a linear interpolation of the PSF table, which provides the fraction of total energy within the user-provided circular aperture radius, "aperad". The fraction is a simple scaling quantity which is applied to both the user-supplied count rate, "cntrate" and count rate uncertainty, "raterr" in order to provide an aperture-corrected count rate.

This procedure is a useful approximation if the extraction aperture is circular and centered precisely on the centroid of the PSF. Any deviation from these criteria will yield unquantified systematic errors.

There are systematic problems to be aware of. The full-width at half-maximum (FWHM) of the PSF is dependent on the temperature of the UVOT focusing rods. Their temperature varies slightly with time because the voltage on the heaters changes through the spacecraft orbit. This can cause variations in the shape of the PSF. Currently this variation has not been well-characterized. Until this occurs it remains the user's responsibility to add a systematic uncertainty to the width of the PSF which is propagated into the corrected count rate uncertainty. Current functionality assumes that the form of the PSF is constant over time, i.e., the ratio of counts in the line core and line wings remains constant, but the width of the entire profile is scaled by a variable quantity during a sequence of exposures. The PSFs characterized in the Swift/UVOT CALDB are considered to be 'typical'.

To characterize the systematic uncertainty added by variable PSFs to the corrected count rate, the user provides an argument, "fwhmsig", which estimates the fractional rms variation of the FWHM of point sources. The appropriate value for "fwhmsig" is under investigation. At present the UVOT team recommends 15% based on fitting Gaussians to observed UVOT PSFs.

Users may wish to set "fwhmsig" to zero and add their own estimate of the uncertainty in the shape of the PSF to the uncertainty in the aperture-corrected count rate. Users should be aware that the size and shape of the UVOT PSF may vary with time and filter, so using a single value "fwhmsig" for all exposures may not be appropriate. The uncertainty in the FWHM of the PSF is propagated through the calculation and is added in quadrature to the corrected uncertainty in the count rate. Note that a systematic uncertainty of x% in the FWHM of the PSF corresponds to a systematic uncertainty of less than x% in the aperture-corrected count rate. For example, for the V filter "fwhmsig=10" corresponds to a systematic error of 2.3% in the aperture-corrected count rate. The value of "fwhmsig" does not affect the value of the aperture correction, only its error.

Another systematic to be aware of is that the PSF is a function of count rate. Significant photon coincidence losses will result in flatter PSFs. A detailed characterization of this effect is pending, but it will result in the CALDB PSFs becoming increasingly obsolete at high count rates. For most small aperture cases, coincidence loss is not an issue in the sense that if an object is bright enough to have significant losses then the 5 arcsec aperture should be used to extract count rates. The PSF is fully-sampled in a 5 arcsec aperture and no aperture correction will be necessary. However the one exception is background limited cases where the sky is bright, which often occurs when observing through the WHITE filter. Currently the aperture correction systematics attached to such ocurrances are unquantified.

It is suggested that the current tool provides a useful 1st-order count rate correction for rapid-response analysis of gamma ray bursts and targets of opportunity. However, a more rigorous approach is recommended for longer-term analysis activities where aperture corrections are conducted using e.g., curve of growth methods for each individual exposure in a sequence.


cntrate [float]
The count rate (counts/sec) from a SWIFT-UVOT detected point source. Background count rates must have been subtracted prior to running this tool.
ratesig [float]
The statistical 1-sigma measurement uncertainty attached to the source count rate (counts/sec).
aperad [float]
The radius (in arcsec) of the CIRCULAR aperture used to extract the count rate.
fwhmsig [float]
The systematic rms uncertainty (percent) in the FWHM of the PSF. This may be caused by voltage variations during the observing sequence, or other effects. "fwhmsig" is a relatively nebulous quantity until it can be formally characterized by the UVOT team. A negative value is treated as a request for the recommended value.
filter = WHITE|U|B|V|UVW1|UVM2|UVW2 [string]
The UVOT filter through which the field was observed. In the general case, the filter information is stored both in the image filename, as it is extracted from the Archive or Quick-Look database, and in the "filter" keyword within the header items of each image or event table. At present the WHITE PSF is unavailable, so the B PSF is used if WHITE is requested.
psffile = "CALDB" [filename]
The path+name of a FITS table containing CALDB-compliant PSF data. This is a simple two-column table containing encircled enery fraction (in column REEF) vs PSF radius in arcseconds (in column RADIUS). If a FITS HDU (extension) number is provided, the tool will open that HDU directly and use its contents. If no HDU is provided, the tool will search each extension in the FITS file until the keyword "filter" matches argument 'filter' above. However, the easiest way to use this function is to download the UVOT caldb from If 'CALDB' is then provided as the argument to "psffile", software will select the correct file and extension for you.
aperate [float]
The aperture-corrected count rate (count/s). This is not an input argument. While the corrected count rate is reported to STDOUT at the end of the task, it is convenient to have this quantity stores as an argument. This can be retrieved by the user or scripts with the pget task, e.g., "pget uvotapercorr aperate".
apersig [float]
The 1-sigma error on the aperture corrected count rate (count/s). This also is not an input argument. It can be retrieved by the user or scripts with the pget task, e.g., "pget uvotapercorr apersig".
(chatter = 1) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task. Setting 1 is mute except for the final result reported to STDOUT, while setting 5 is the most wordy.


The following examples illustrate running uvotapercorr

1. run uvotapercorr prompting for all mandatory arguments:


2. run uvotapercorr specifying all control arguments on the command line:

      uvotapercorr cntrate=20.3 ratesig=1.2 aperad=3.0 fwhmsig=12 filter=WHITE psffile=CALDB chatter=5




June 17, 2008