NAME

uvotproduct - create level III science products from Level II UVOT data.

USAGE

uvotproduct infile=<filename> outfile=<filename> plotfile=<filename> srcreg=<filename> bkgreg=<filename> batpos=<string> xrtpos=<string> uvotpos=<string> groundpos=<string> reportfile=<filename>

DESCRIPTION

This tool creates level III science products from Level II sky image files. It is meant primarily for use in the Swift pipeline, but could also be of some use for initial data inspection by, e.g., Swift Burst Advocates.

The batpos, xrtpos, uvotpos, and groundpos parameters all use the same scheme for specifying a position/error circle. For available positions, they can either give the name of a region file containing a single included fk5 circle, for example

	fk5;circle(280.32,-23.5,5")
or a string of the form ra+dec~error, for example 280.32-23.5~5 (which would specify the same error circle as the preceding region file).

There is a known issue in uvotproduct that can cause the significances, upper limits, and magnitude errors to be incorrect for very faint sources. Users should use caution when considering reported detections with magnitude errors greater than approximately 0.3 mag.

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 magnitude history. This is a FITS file with a table extension for each filter containing the results of uvotmaghist for the images in that filter.

plotfile [filename]
Template for output magnitude history plot(s) or NONE. The extension of plotfile can be used to control the PGPLOT device. Given plotfile=x.y, a sequence of plots will be created based on the filter groups specified by plotfilters with names x1.y, x2.y, ...

srcreg [filename]
Source region file.

bkgreg [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 12.5" and outer radius 25". Additionally, 6" circular exclusion regions are applied for sources which are detected that overlap the annulus.

batpos [string]
The BAT position and error circle or NONE if it is not available. See the DESCRIPTION section for how to specify a region file or string.

xrtpos [string]
The XRT position and error circle or NONE if it is not available. See the DESCRIPTION section for how to specify a region file or string.

uvotpos [string]
The UVOT position and error circle or NONE if it is not available. See the DESCRIPTION section for how to specify a region file or string.

groundpos [string]
The BAT position and error circle or NONE if it is not available. See the DESCRIPTION section for how to specify a region file or string.

reportfile [filename]
Name for output report or NONE. The output report is a text file which includes a summary of the input files, region files used in processing, along with individual image and combined image results.

(expfile = NONE) [filename]
Exposure maps for sky images or NONE.

(timezero = TRIGTIME) [string]
Reference time for output. The special value TRIGTIME requires that the primary header of the first input file contains the TRIGTIME keyword and uses the corresponding value. Alternatively, the user can enter an arbitrary MET, for example, 123456789.0 or a UTC time formatted as YYYY-MM-DDTHH:MM:SS.

(plotmag = yes) [boolean]
If true, plotfile will use magnitudes; otherwise rates.

(plotfilters = WHITE,B,U,V:UVW1,UVW2,UVM2) [string]
Which filter(s) to include light curve plot(s). A comma (,) delimits filters within a plot. A colon (:) delimits plots.

(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. See also ssstype.
(ssstype = LOW) [LOW|MID|HIGH]
Small scale sensitivity CALDB query TYPE constraint.
(sensfile = CALDB) [filename]
Detector sensitivity file or CALDB or NONE.
(apercorr = CURVEOFGROWTH) [NONE|CURVEOFGROWTH]
uvotsource apercorr parameter.
(nsigma = 3.0) [real]
N sigma for determining faintest detection.
(exclude = DEFAULT) [string]
Extensions to exclude.
(frametime = DEFAULT) [string]
Frame time [s] or DEFAULT to use FRAMTIME keyword.
(fcprefix = NONE) [string]
Finding chart prefix or NONE. If this parameter is not NONE, then two jpg images will be produced starting with fcprefix. One will be an image from a DSS server. The other will be based on the earliest useful UVOT exposure with duration at least 50 [s]. The size of these images will depend on what positions are available. If only a BAT position is available, they will be 6' square; otherwise they will be 2' square.

The ds9 scripting works with version 5.

(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.

(rebin = DEFAULT) [string]
User specified rebinning parameters. The special value DEFAULT causes the values listed below to be used. The special value NONE disables rebinning. Available parameters (default value) are:

MIN_SIGMA (2) Neighboring points are combined until a signal-to-noise ratio (SNR) exceeding MIN_SIGMA is obtained (subject to limits on the range of times and consistency of values -- see below). Larger values of MIN_SIGMA produce fewer data points.

MAX_TIME_RATIO (2) The next data point will not be combined with the earlier data if the ratio of the (new) end time to the start time exceeds MAX_TIME_RATIO. In this case the earlier data will become a value in the rebinned light curve even though its SNR is low. Larger values of MAX_TIME_RATIO produce fewer data points.

MIN_TIME_RATIO (1.2) Neighboring data points will be combined until the ratio of the end time to start time exceeds MIN_TIME_RATIO even if the SNR of the combined data exceeds MIN_SIGMA. This allows significant detections to be combined if they are close together in time. Larger values of MIN_TIME_RATIO produce fewer data points. Setting MIN_TIME_RATIO to a value < 1 turns this off.

SNR_DIFF (2) A new data point will not be combined with earlier data if its value is significantly different (i.e., the differnce is signficant at the MIN_SIGMA sigma level). Larger values of SNR_DIFF produce fewer data points.

SNR_DIFF_ORPHAN (2) The initial rebinned light curve is processed in a second pass in an attempt to eliminate "orphans". An orphan is a data point with very low SNR following a point with a high SNR. They typically occur immediately before a gap in the light curve. The orphan is combined with the previous point if the resulting time span satisfies MAX_TIME_RATIO and the difference in the two values is less than SNR_DIFF_ORPHAN sigma. Larger values of SNR_DIFF_ORPHAN produce fewer points.

Each rebinning parameter is specified using key=value. Multiple parameters are specified using a comma delimited list.

(qdpfile = NONE) [string]
Template for QDP output file(s). Given qdpfile=x.y, a sequence of files will be created based on the filter groups specified by plotfilters with names x1.y, x2.y, ...

(subpixel = 8) [integer]
Sub-pixelling level. See uvotsource.
(gridfile = NONE) [filename]
Path for ds9 grid file or NONE.
(skipbad = no) [boolean]
Skip images for which photometry fails and exclude from results. See uvotsource.
(skipped = 0) [output integer]
Number of exposures excluded from results due to processing failures.
(expdeltaf = 0.01) [float]
Allowed variation in exposure times as a fraction of the mean exposure.
(forcephot = no) [boolean]
Perform photometry even if src/bkg region exposure validation fails.
(clobber = no) [boolean]
Standard HEAdas clobber parameter; controls whether the output files are permitted to overwrite existing files.

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

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

EXAMPLES

The following examples illustrate running uvotproduct

1. run uvotproduct prompting for all mandatory options:

      uvotproduct
2. run uvotproduct specifying filenames and source positions on command line:

      uvotproduct infile=@img.lis outfile=maghist.fits plotfile=maghist.cps batpos=23.33-41.83~120 xrtpos=23.334-41.839~5.0 uvotpos=23.334743-41.839381~1.0 reportfile=summary.txt chatter=5 

SEE ALSO

uvotmaghist, uvotsource

LAST MODIFIED

April 2023