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. They can either be 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 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]
- 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.
- plotfile [filename]
- Name for output magnitude history plot or NONE. The extension of plotfile can be used to control the PGPLOT device.
- 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]
- A region file name or a string ra+dec~error giving the BAT position/error circle.
- xrtpos [string]
- A region file name or a string ra+dec~error giving the XRT position/error circle.
- uvotpos [string]
- A region file name or a string ra+dec~error giving the UVOT position/error circle.
- groundpos [string]
- A region file name or a string ra+dec~error giving a ground position/error circle.
- reportfile [filename]
- Name for output report 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.
- (zerofile = CALDB) [filename]
- Zero points file or CALDB.
- (coinfile = CALDB) [filename]
- Coincidence loss file or CALDB.
- (psffile = CALDB) [filename]
- PSF file or CALDB.
- (lssfile = NONE) [filename]
- Large scale sensitivity file or NONE.
- (apercorr = NONE) [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) [boolean]
- 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 available non-SETTLING V or WHITE exposure. 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 scripting involved only works with ds9 version 4.
- (centroid = no) [boolean]
- Perform centroiding? See uvotsource centroid parameter.
- (fwhmsig = 3) [real]
- Percentage uncertainty in FWHM of PSF. See uvotapercorr fwhmsig parameter.
This parameter is only used if apercorr=CURVEOFGROWTH.
- (clobber = no) [boolean]
- Standard HEAdas clobber parameter; controls whether the output files
are permitted to overwrite existing files.
- (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 2008