NAME

uvotcoincidence - performs coincidence loss correction

USAGE

uvotcoincidence infile=<filename> coinfile=<filename> ratecol=<string> errcol=<string> frametime=<real> deadtimecorr=<boolean> history=<bool> chatter=<enumerated integer>

DESCRIPTION

Given a count rate in units of counts per second, and a 1-sigma error in the same units, uvotcoincidence will find the corresponding coincidence loss correction factors and rates.

Normally I/O is performed through a FITS table which must be prepared by the user. Requirements are to provide a minimum of two columns with arbitrary names containing numeric values. One column contains a count rate, the other contains the associated 1-sigma error. The table may contain any number of rows or other columns, the task will perform the conversion on all data rows. The output is written to the same FITS table. Five columns are created or updated:

       COI_FACTOR       correction factor
       COI_FACTOR_ERR   1-sigma error associated with COI_FACTOR
       COI_RATE         CoI corrected rate in units of count/s
       COI_RATE_ERR     1-sigma error associated with COI_RATE
       SATURATED        boolean; true indicates saturation

PARAMETERS

infile [filename]
FITS input table containing at least two numeric columns, one containing count rates in units of counts per second, the other containing 1-sigma measurement error in the same units. Output data will be appended to the same table. If infile=NONE, the values of the ratecol and errcol parameters are operated on directly.

coinfile [filename]
Name of file containing coincidence loss correction calibration. The special value CALDB causes the CALDB to be queried for the proper file.

(ratecol = RATE) [string]
Name of the table column in infile containing the count rates. Each row must contain a numeric value. If infile=NONE, pass a single rate through this parameter.

(errcol = RATE_ERR) [string]
Name of the table column in infile containing the 1-sigma count rate error. Each row must contain a numeric value. If infile=NONE, pass a single rate error through this parameter.

(frametime = DEFAULT) [string]
Frame time [s]. Used for calculating dead time correction. The special value DEFAULT results in the value of the FRAMTIME keyword being used if it is present in the source table, otherwise, the value 0.0110322 [s] is used.

(deadtimecorr = yes) [boolean]
Input already dead time corrected? deadtimecorr=yes means that the dead time correction has already been applied in the exposure time. deadtimecorr=no means that uvotcoincidence will apply the dead time correction.

(history = yes) [boolean]
If yes, a HISTORY keyword will be written to the header of infile containing the uvotcoincidence arguments.

(chatter = 1) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task. Setting 1 is mute, while setting 5 is the most wordy.

EXAMPLES

The following examples illustrate running uvotcoincidence

1. run uvotcoincidence specifying source list and rate columns on the shell command line. countrates.fits is a FITS file containing a table in HDU number 1. (note that the first extension in the file, often an empty primary extension, is designated HDU number 0, by convention). The tool will look for table columns names RATEX (containing the source count rate) and RATEX_ERR (the 1-sigma error attached to RATEX) to propogate through the magnitude and flux conversion.

        uvotcoincidence infile=countrates.fits+1 ratecol=RATEX errcol=RATEX_ERR
2. run uvotcoincidence specifying a single rate and error for conversion on the command line:

        uvotcoincidence infile=countrates.fits+1 ratecol=13.4 errcol=1.13
3. run uvotcoincidence specifying the coincidence loss calibration file on the command line:

        uvotcoincidence infile=countrates.fits+1  \
        coinfile=/caldb/data/swift/uvota/bcf/phot/swucntcorr20041120v105.fits

SEE ALSO

uvotdetect, uvotflux, uvotsource, uvotmaghist, uvotproduct, uvotapercorr

LAST MODIFIED

May 21, 2007