uvotimsum - sum UVOT sky images or exposure maps


uvotimsum infile=<filename> outfile=<filename> method=<string> pixsize=<float> expmap=<filename> exclude=<string> maskfile=<filename> weightfile=<filename> clobber=<boolean> history=<boolean> cleanup=<boolean> chatter=<integer>


It is sometimes desirable to sum UVOT exposures to improve the signal-to-noise, or to detect faint sources. This tool simplifies summing a multiple extension FITS image file. It determines the range on the sky of the input images, checks that the input image filters match and calculates time related keywords.

The input exposures are assumed to be in SKY coordinates. No attempt is made to align individual exposures to a common frame of reference. Use uvotskycorr to do this. The output pixel size is set to "pixsize" degrees. If "pixsize" is less than or equal to zero then the output pixel size is equal to size of the largest input pixel. The user can exclude exposures using the "exclude" keyword.

Two rebinning methods are available. GRID assumes that all images are oriented in the same direction. This means that image rotations are ignored during image rebinning. XIMAGE makes no assumptions about image rotation. Both rotation and translation are performed during the rebinning.

This tool will sum exposures with different frame times within the constraints of the flexframetime and ignoreframetime parameters. If images with differing frame times are summed, the UVOT photometry tools will yield questionable photometry on the summed images. For this reason, by default only slight variation in the input image frame times is allowed. If images with differing frame times are summed, the frame time of the sum is estimated as the exposure time weighted mean of the input frame times.

The primary output HDU contains keywords taken from the primary input HDU. The first extension of the output contains the summed image.


infile [filename]
FITS input image(s). The input extensions should have UVOT image keywords. This may be a comma-delimited list of names, or the name of a text file containing a list of file names, one per line, preceded by an '@' character.

outfile [filename]
Name of output file.

Summing method. The COUNT and GRID methods are synonyms which can be used for summing scalar [usually count or rate] images. Only use method=XIMAGE on scalar images. Use method=EXPMAP to sum exposure maps. Use method=LSSMAP to sum LSS maps. Use method=VARIANCE to sum counts images weighted by the square of the weights from weightfile. Note that expmap=yes overrides the method.

(pixsize = 0) [real, deg]
Output pixel size. If no positive number is specified (the default), the largest input pixel size is used.

(expmap = no) [boolean]
Sum as exposure maps? Changing the size of pixels does not affect exposure times, but does affect photon counts. expmap=yes is subsumed by method=EXPMAP.

(exclude = DEFAULT) [string]
Comma delimited list of HDU names or numbers (or numbered ranges) to exclude from the sum. See the help file on filenames for a detailed description of specifying input extensions (section B.2).

The special value ASPCORR:NONE can be used to exclude extensions that do not have the ASPCORR keyword. The special value DUPEXPID can be used to exclude all but the largest of input HDUs sharing the same EXPID- this avoids including IMAGE&EVENT mode exposures twice in the sum. The special value SETTLING can be used to exclude extensions with OBS_MODE=SETTLING. The special values OVERLAP:(WEAK|STRONG) will exclude any images which do not overlap the transitive closure of images overlapping the primary image (which is determined by finding the image which has the largest overlapping exposure or number of overlapping images). The special value DEFAULT is treated as exclude=ASPCORR:NONE,DUPEXPID,SETTLING.

(maskfile = NONE) [string]
A FITS file containing one mask per extension matching the extensions in the "input" file.

The mask file can be created by running uvotexpmap with the "maskfile" parameter. The mask uses "1"s to indicate a pixel to be included in the summed image and "0"s for pixels to be excluded.

(weightfile = NONE) [string]
An ASCII file containing lines of the form

where the primary HDU is number 0 and the first extension is 1. Entries are optional- HDUs with no corresponding entry are assumed to have weight unity (1.0).

When a weight file is provided, outfile is written with EXPOSURE = 0 to indicate that photometry is not appropriate.

(flexframetime = 0.02) [real]
How flexible to be in allowing variation in the input frame times. Frame time is given by the FRAMTIME keyword in each input HDU. If FRAMTIME is missing, a frame time of 11.032 [ms] is assumed for that HDU. flexframetime is expressed as a fractional (unitless) value, with the default corresponding to 2%. See also the ignoreframetime parameter.

(ignoreframetime = no) [boolean]
Ignore the frame time variation in the input?

Use ignoreframetime=true to sum input images regardless of the frame times.

(weightzero = no) [boolean]
Use default weight zero when calculating a weighted sum (see weightfile parameter). When calculating a weighted sum, if no weight is provided for an HDU, the default weight is 1 if weightzero=no, or 0 if weightzero=yes.

(clobber = no) [boolean]
Overwrite existing output file?

(history = yes) [boolean]
Write parameters to history keywords?

(cleanup = yes) [boolean]
Remove temporary files?

(chatter = 3) [enumerated integer]
Standard HEAdas chatter parameter.


1. Run uvotimsum specifying input file and output pixel size, overwriting the output file (which will be prompted for) if necessary

      uvotimsum infile=swuv.img pixsize=0.0001 clobber=yes
2. Run uvotimsum excluding HDU 3, the HDU named RALPH, and HDUs 6-14 from the output sum

      uvotimsum exclude=3,RALPH,6-14
3. Run uvotimsum to produce an exposure map corresponding to the output of example 2

      uvotimsum infile=swuv_ex.img expmap=yes exclude=3,RALPH,6-14
4. Run uvotimsum with a weightfile

Say we have an image file with two extensions and want the sum of 2.5 times the first extension and 0.5 times the second extension. Create the file weights.txt with contents

      1: 2.5
      2: 0.5
and issue the command
      uvotimsum infile=swuv_ex.img weightfile=weights.txt


farith, performs simple arithmetic operations on two images

uvotexpmap, creates UVOT exposure maps and mask files

ximage, has the ability to interactively sum images


April 2023