NAME

uvotpipeline - run UVOT analysis software

USAGE

uvotpipeline <obsid>

DESCRIPTION

This tool runs the UVOT data analysis software on Swift observation data.

uvotpipeline can be used to carry out processing as is done at the Swift Data Center and allows user tailoring of the processing. The UVOT aspect correction software depends on access to a suitable reference catalog.

The processing flow of uvotpipeline is:

  1. check inputs

    2. Resolve parameters. Determine source position and nominal pointing.

  2. process events

    3. Run coordinator and uvotscreen on input event files.

  3. make images

    4. Run uvotimage on processed event files and input raw images to create raw images. Optionally flat-field and mod8 correct the raw images. Optionally make raw quality maps. Make sky versions of the raw images; Make detector coordinate images for grism files. Optionally make exposure maps. Optionally make LSS maps.

  4. aspect correct images

    5. Run uvotskycorr on all sky images to determine aspect corrections. Apply aspect corrections to sky images, exposure maps, and quality maps. Create a UVOT attitude file which takes into account the aspect corrections.

  5. make products

    6. Sum sky images, exposure maps, quality maps, LSS maps. Run uvotdetect to make source lists for the summed images. Run uvotproduct if a source position was provided.

PARAMETERS

sequence [string]
Swift observation number. An 11 digit string made up of an 8 digit target followed by a 3 digit observation segment. For example, 01234567001.
(indir = DEFAULT) [string]
Directory holding input to uvotpipeline. The value DEFAULT is treated as the value of the sequence parameter. This is intended for the use case where uvotpipeline is run on a directory downloaded from the Swift archive which is in the current directory. uvotpipeline is not sensitive to the organization of files in the input directory: all files may be in a single directory, or the input may be organized consistently with the Swift archive structure for observations, or some alternate organization may be used.
(outdir = DEFAULT) [string]
Directory to which processing results are sorted and collected. This directory will be organized like the Swift archive but will only include selected/processed auxil and uvot files. The value DEFAULT is treated as sequence.out. As a precaution, clobber will only remove a file or empty directory.
(tmpdir = DEFAULT) [string]
Directory under which intermediate files are written. The value DEFAULT is treated as sequence.tmp. In an error occurs during processing, the files which have been created are left under tmpdir. If no errors are encountered during processing and cleanup is true, then this directory will be removed at the end of processing. As a precaution, clobber will only remove a file or empty directory.
(steminputs = DEFAULT) [string]
The prefix of files in the input directory. The value DEFAULT is treated as swsequence.
(stemoutputs = DEFAULT) [string]
The prefix of files that will be output. The value DEFAULT is treated as swsequence.
(filters = ALL) [string]
A comma-separated list of UVOT filters or filter codes to process. The value ALL means to process data for all filters.
(attfile = DEFAULT) [file]
The attitude file to use for processing. The value DEFAULT requests that the jump-corrected attitude file (swsequencepat.fits) be used if it is found in the input; otherwise use the spacecraft attitude file (swsequencesat.fits).
(runcoordinator = yes) [boolean]
Controls whether the coordinator tool is run on event files.
(coordrandomize = yes) [boolean]
Controls the coordinator randomize parameter.
(coordseed = yes) [integer]
Controls the coordinator seed parameter.
(saofile = DEFAULT) [file]
The attitude/orbit file to use for event screening. The value DEFAULT corresponds to the swsequencesao.fits file from the input.
(screenevt = no) [boolean]
Controls whether uvotscreen is run on event files. If screening is enabled, then the saofile parameter is used as the uvotscreen attorbfile.
(aoexpr = T) [string]
The attitude/orbit screening expression passed to uvotsceen.
(evexpr = QUALITY.EQ.0) [string]
The event screening expression passed to uvotsceen.
(flatfield = no) [boolean]
Perform flat-fielding?
(mod8corr = yes) [boolean]
Perform modulo 8 noise correction?
(keepcorr = no) [boolean]
Keep intermediate corrected files? If keepcorr is false, the flat-fielded and mod-8 noise corrected files are discarded after processing.
(flagqual = no) [boolean]
Run uvotflagqual? If enabled, then for each UVOT raw image file (uff_rw.img), corresponding maps of quality flags in raw (uff_rqf.img) and sky (uff_sqf) coordinates are created.
(lssmaps = no) [boolean]
Run uvotskylss? If enabled, then for each UVOT sky image file (uff_sky.img), corresponding LSS maps in sky (uff_lss.img) coordinates are created.
(makeuatfile = yes) [boolean]
Controls whether a UVOT attitude file is created.
(maskopt = 0) [integer]
Exposure mask options.
(catspec = usnob1.spec) [file]
The star catalog specification for aspect correction. See the catspec help (fthelp catspec) for additional information.
srcra = NONE [NONE|degrees|hexra|OBJECT]
Source R.A.

uvotproducts is only run if a source position is specified. The source position can be provided in degrees or hexagesimal. The value OBJECT takes the source position from the RA_OBJ, DEC_OBJ keywords.

srcdec = NONE [NONE|degrees|hexdec|OBJECT]
Source declination.

uvotproducts is only run if a source position is specified. The source position can be provided in degrees or hexagesimal. The value OBJECT takes the source position from the RA_OBJ, DEC_OBJ keywords.

(srcrad = 3) [float]
Source region radius in arcsec.
(pntra = POINT) [POINT|degrees]
Nominal pointing R.A. The value POINT indicates to use the of the attfile RA_PNT keyword.
(pntdec = POINT) [POINT|degrees]
Nominal pointing declination. The value POINT indicates to use the value of the attfile DEC_PNT keyword.
(pntroll = POINT) [POINT|degrees]
Nominal pointing roll. The value POINT indicates to use the value of the attfile PA_PNT keyword.
(srcreg = SOURCE) [NONE|SOURCE|file]
Source region to use to when creating a light curve.

The value SOURCE indicates to use a circular region defined by the srcra, srcdec, and srcrad parameters.

The value NONE indicates there is no source region.

Or, a source region file can be provided.

(bkgreg = DEFAULT) [DEFAULT|file]
Background region to use when creating a light curve.

The value DEFAULT will be passed to uvotproduct unchanged.

Or a background region file can be provided.

(timezero = DEFAULT) [see uvotproduct]
This parameter is passed to uvotproduct.
(uvotpos = NONE) [see uvotproduct]
This parameter is passed to uvotproduct.
(batpos = NONE) [see uvotproduct]
This parameter is passed to uvotproduct.
(xrtpos = NONE) [see uvotproduct]
This parameter is passed to uvotproduct.
(groundpos = NONE) [see uvotproduct]
This parameter is passed to uvotproduct.
(fcprefix = DEFAULT) [DEFAULT|NONE|string]
Controls what is passed to the uvotproduct fcprefix parameter. The value DEFAULT is treated as swsequenceufc. The value NONE is passed unchanged. Other strings are pased unchanged.
(nsigma = 3) [float]
Detection threshold.
(teldef = CALDB) [file]
Input Telescope definition file. Specify the name of a file or CALDB to retrieve from the calibration database.
(alignfile = CALDB) [file]
Input spacecraft alignment calibration.
(badpixlist = CALDB) [file]
Input bad pixel table. Specify the name of a file or CALDB to retrieve from the calibration database.
(flatfile = CALDB) [file]
Input flat field calibration. Specify the name of a file or CALDB to retrieve from the calibration database.
(zerofile = CALDB) [file]
Zero points file. Specify the name of a file or CALDB to retrieve from the calibration database.
(coinfile = CALDB) [file]
Coincidence loss correction file. Specify the name of a file or CALDB to retrieve from the calibration database.
(psffile = CALDB) [file]
Radial encircled energy function (PSF) file. Specify the name of a file or CALDB to retrieve from the calibration database.
(lssfile = CALDB) [file]
Large-scale sensitivity correction file. Specify the name of a file or CALDB to retrieve from the calibration database. The special value NONE indicates to skip this correction.
(sssfile = NONE) [file]
Small-scale sensitivity correction file. Specify the name of a file or CALDB to retrieve from the calibration database. The special value NONE indicates to skip this correction.
(ssstype = LOW) [LOW|MID|HIGH]
Small scale sensitivity CALDB query TYPE constraint.
(sensfile = CALDB) [file]
Detector sensitivity loss correction file. Specify the name of a file or CALDB to retrieve from the calibration database. The special value NONE indicates to skip this correction.
(apercorr = CURVEOFGROWTH) [CURVEOFGROWTH|NONE]
Aperture correction calculation algorithm. NONE or CURVEOFGROWTH. CURVEOFGROWTH assumes a point source.
(skipbad = yes) [boolean]
Skip images for which photometry fails and exclude from results. See uvotsource.
(subpixel = 8) [integer]
Sub-pixelling level. See uvotsource.
(expmapusebp = no) [boolean]
Controls whether uvotexpmap is passed the bad pixel map. If the bad pixel map is fed into the exposure map, then NULLs will be output for pixels which are impinged on by any bad pixels.
(expmapusesss = no) [boolean]
Controls whether uvotexpmap is passed the small scale sensitivity file. If the small scale sensitivity is fed into the exposure map, then NULLs will be output for pixels which are impinged on by bad SSS pixels.
(swiftround = round=0.01) [string]
Controls swiftround parameters. The value NONE disables the swiftround step of processing. Otherwise, sky images and exposure maps are rounded using any provided parameters.
(cleanup = yes) [boolean]
Standard HEAdas cleanup parameter; controls whether temporary files are removed at the end of processing.
(clobber = no) [boolean]
Standard HEAdas clobber parameter; controls whether to overwrite pre-existing output files.

The outdir and tmpdir locations will only be removed if they are empty directories or not directories.

(chatter = 1) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task.

EXAMPLES

The following examples illustrate running uvotpipeline

1. run uvotpipeline providing only the directory holding an archive sequence: 

      uvotpipeline 00123456001

2. run uvotpipeline processing only data taken in the B and V filters: 

      uvotpipeline 00123456001 filters=B,V

3. run uvotpipeline screening events using the Swift makefilter file: 

      uvotpipeline 00123456001 saofile=00123456001/auxil/sw0123456001s.mkf.gz \
			evtscreen=yes aoexpr='(SAA_FLAG.EQ.0).AND.STLOCKFL

4. run uvotpipeline with a source position so a light curve and related products are created: 

      uvotpipeline 00123456001 srcra=01:23:45.67 srcdec=-12.345

5. run UVOT pipeline twice: first generating an aspect corrected UVOT attitude, then reprocessing with the just created attitude: 

	OBS=01032024000

	SRCRA=NONE
	SRCDEC=NONE

	# clean old directories
	rm -rf $OBS.out
	rm -rf $OBS.tmp
	rm -rf $OBS.phase1

	uvotpipeline $OBS outdir=$OBS.phase1 srcra=$SRCRA srcdec=$SRCDEC swiftround=NONE |& tee $OBS.phase1.log
	if [ $? -ne 0 ]; then
	    echo "phase 1 failed"
	    exit 1
	fi

	uvotpipeline $OBS indir=$OBS.phase1 srcra=$SRCRA srcdec=$SRCDEC attfile=$OBS.phase1/auxil/sw${OBS}uat.fits |& tee $OBS.phase2.log
	if [ $? -ne 0 ]; then
	    echo "phase 2 failed"
	    exit 1
	fi

6. run uvotpipeline including quality maps and preserving mod8 correction: 

      uvotpipeline 00123456001 flagqual=yes keepcorr=yes

SEE ALSO

LAST MODIFIED

December 2021