NAME

uvotlc - create level III light curve from Level II UVOT data.

USAGE

uvotlc infile=<filename> outfile=<filename> qualfile=<filename> expfile=<filename> srcra=<string> srcdec=<string>

DESCRIPTION

This tool creates a UVOT light curve from Level II sky image files, sky quality maps, and exposure maps.

The sky image, quality map, and exposure map for a given exposure are matched based on HDU names. By default, only aspect corrected sky images are processed. Aspect corrected images are indicated by an ASPCORR keyword with value <> NONE. If exposure (quality) maps are provided, then the dimensions of each of these images for a given exposure must be identical to the sky image in order for processing. The user can force processing of sky images lacking suitable quality and/or exposure maps using the forcephot parameter.

The source position is given by the srcra and srcdec parameters which can be in degrees or sexagesimal. The background region defaults to an annulus around the source position with exclusion regions for sources detected in the deepest aspect corrected exposure for each filter.

The light curve includes quality indicators based on the quality map and photometry findings. The QUALFLAG column holds flags found by uvotflagqual in the source region. The PHOTFLAG column holds flags found by uvotlc and uvotsource when attempting photometry.

The user can control aspects of the light curve processing through the qualprof and qualmod parameters.

PARAMETERS

infile [filename]
Input sky images file(s). A comma separated list of files or @filename to load the file names from a file containing one file name per line.

outfile [filename]
Name for output light curve. This is a FITS file with a table extension containing a row for each input exposure for which uvotsource is successfully run. The quality columns flag records with questionable results.

qualfile [filename]
Input quality maps. A comma separated list of files or @filename to load the file names from a file containing one file name per line.

The special value NONE allows producing output without quality maps.

Quality maps must be in sky coordinates and match the dimensions of the input sky images. Quality maps in raw coordinates are created by uvotflagqual. Quality maps in sky coordinates are created by running swiftxform on the raw ones.

expfile [filename]
Input exposure maps. A comma separated list of files or @filename to load the file names from a file containing one file name per line.

The special value NONE allows producing output without exposure maps.

Exposure maps must be in sky coordinates and match the dimensions of the input sky images. Exposure maps are produced by uvotexpmap.

(bkgreg = DEFAULT) [filename]
Background region file or DEFAULT. The special value DEFAULT automatically creates a region file based on an annulus around the source position with inner radius BKG_REG_INNER_arcsec and outer radius BKG_REG_OUTER_arcsec. Additionally, circular exclusion regions are applied for sources which are detected that overlap the annulus. The radius of the exclusion regions is controlled by the BKG_EXCLUSION_RADIUS_arcsec parameter.

srcra [degrees|sexra]
Source R.A.

The source position can be provided in degrees or sexagesimal.

srcdec [degrees|sexdec]
Source declination.

The source position can be provided in degrees or sexagesimal.

(srcaper = 5) [arcsec]
Source aperture radius [arcsec].

(zerofile = CALDB) [filename]
Zero points file or CALDB.
(coinfile = CALDB) [filename]
Coincidence loss file or CALDB.
(psffile = CALDB) [filename]
PSF file or CALDB.
(lssfile = CALDB) [filename]
Large scale sensitivity file or CALDB or NONE.
(sssfile = CALDB) [filename]
Small scale sensitivity file or CALDB or NONE.
(ssstype = LOW) [LOW|MID|HIGH]
Small scale sensitivity CALDB query TYPE constraint.
(sensfile = CALDB) [filename]
Detector sensitivity file or CALDB or NONE.
(qualprof = DEFAULT) [filename]
Quality profile.

This file contains one or more settings for the quality profile. Comments start with the hash (#) character. Blank lines are allowed. Lines of the form KEY VALUE set parameter KEY to VALUE.

Most values are a single number. The exception is that parameters which map a source magnitude to a radius are formatted as mag1~radius1,mag2~radius2,...magn~radiusn,~defaultradius. The set of parameters which can be controlled and their values can be listed by setting the 'profile' parameter to value 'list'. As of this writing, this yields:

	SRC_APERTURE_RADIUS_arcsec 5
	SRC_MIN_EXPOSURE_s 5
	SRC_CONFUSION_SAME_arcsec 1
	SRC_CONFUSION_MAG_arcsec 12~20,14~15,16~10,18~7,[default] ~5
	BKG_REG_OUTER_arcsec 25
	BKG_REG_INNER_arcsec 12.5
	BKG_EXCLUDE_MAG_arcsec 12~20,14~15,16~10,18~7,[default] ~5
	MIN_BKG_AREA_arcsec2 100
	BKG_DETECT_NSIGMA 2.5
	MAX_COI_STD_FACTOR 1.1
	MAX_COI_STD_FACTOR_ERR 0.1
(qualmod = NONE) [string]
Quality profile modifications.

This parameter can be used to modify one or more parameters in the quality profile. The format is semicolon delimited KEY=VALUE.

(apercorr = CURVEOFGROWTH) [NONE|CURVEOFGROWTH]
uvotsource apercorr parameter.
(nsigma = 3) [real]
N sigma for determining faintest detection.
(exclude = DEFAULT) [string]
Extensions to exclude from light curve.
(frametime = DEFAULT) [string]
Frame time [s] or DEFAULT to use FRAMTIME keyword.
(centroid = no) [boolean]
Perform centroiding? See uvotsource centroid parameter.

(fwhmsig = -1) [real]
Percentage uncertainty in FWHM of PSF. See uvotapercorr fwhmsig parameter. This parameter is only used if apercorr=CURVEOFGROWTH.

(subpixel = 8) [integer]
Sub-pixelling level. Passed to uvotsource.
(syserr = no) [boolean]
Include systematic errors?
(skipbad = yes) [boolean]
Skip images for which photometry fails. See uvotsource.
(skipped = 0) [output integer]
Returns the number of HDUs not included in output.
(expdeltaf = 0.01) [float]
Allowed variation in exposure times as a fraction of the mean exposure. Passed to uvotsource.
(forcephot = no) [boolean]
Attempt photometry even for questionable inputs.

This forces processing of exposures even if there is no quality or exposure map. The forcephot parameter is also passed to uvotsource.

(clobber = no) [boolean]
Standard HEAdas clobber parameter; controls whether the output files are permitted to overwrite existing files.

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

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

EXAMPLES

The following examples illustrate running uvotlc

1. run uvotlc prompting for all mandatory options:

      uvotlc
2. run uvotlc specifying the source position and providing input files indirectly on command line:

      uvotlc srcra=23.334743 srcdec=-41.839381 infile=@u_sk.list outfile=lc.fits qualfile=@u_sqf.list expfile=@u_ex.list
3. run uvotlc specifying the source position on a single image without exposure or quality maps:

      uvotlc srcra=23.334743 srcdec=-41.839381 infile=sw12345uvv_sk.imv outfile=lc.fits qualfile=NONE expfile=NONE
4. run uvotlc prompting for required parameters and requesting a listing of the quality profile

      uvotlc qualmod=profile=list

SEE ALSO

uvotsource

LAST MODIFIED

April 2023