NAME

USAGE

DESCRIPTION

This task makes a light curve from UVOT event files. It performs region selection and background subtraction. The user can supply custom time bins using the gtifile parameter. Both source and background regions must be supplied. Complex region files are permitted.

The user can specify one file on the command line, or an "@" style batch file listing multiple files. Event files taken with different UVOT filters should never be mixed in one call to uvotevtlc.

To make sure the UVOT events have been converted to sky positions using the best available Swift spacecraft attitude, the task 'coordinator' should first be run on the event file, with an aspect-corrected attitude file that contains the ajumpapp keyword set to 'T'.

This task calls the batbinevt task to actual perform the light curve binning. The user has a choice of binning styles via the "timebinalg" parameter. Binning can be either "U"niform, indicating constant bin sizes, or "G"TI, meaning the user choses the bin edges explicitly with a good time interval file. Each separate good time interval will be turned into one output light curve time bin. The good time interval file is also used for time-based filtering of UVOT events.

Output lightcurves contain the keyword TIMEPIXR which indicates the reference point for light curve time bins. For light curves, the start, stop and center times of each bin can be calculated as:

   TIME_START = TIME - TIMEPIXR*TIMEDEL
   TIME_STOP  = TIME + (1-TIMEPIXR)*TIMEDEL
   TIME_CENT  = TIME + (0.5-TIMEPIXR)*TIMEDEL

Since for uvotevtlc TIMEPIXR should always be 0.5, the TIME column marks the center of each bin, and TIME_START and TIME_STOP are one-half of a bin width away. If variable size time bins are requested, then TIMEDEL will be a column instead of a keyword, but the above expressions still hold.

Region-based filtering is done using standard region files (this uses the region filtering capability built into CFITSIO). The user should supply both source and background regions. uvotevtlc computes the net rate (RATE) by subtracting the mean background level, derived from the background region, from the source rate, derived from the source region. The background rate (RATE_BKG) is reported in units of counts per second per square arcsec, and is scaled by the source region size before subtraction. The source and background region sizes are stored in the REGAREA and BREGAREA keywords, respectively (in units of square arcsec). The region areas are computed empirically by testing how many UVOT pixels in the entire field of view successfully pass the filtering criteria.

If the parameter 'uvotmag' is set to YES, then UVOT count rates are converted to magnitudes using the uvotcoincidence and uvotflux tasks.

uvotevtlc makes several scratch data files. Users should have enough free space to accomodate these files. The actual size of the scratch data varies depending on the size of the source and background region, but should never be more than the size of the original event files (when they are uncompressed).

PARAMETERS

infile [filename]

The name of the input events file, or an @-file listing the event files to be entered.

outfile [filename]

The name of the output light curve file

srcreg [filename]

The name of the source region file. Complex regions are permitted.

bkgreg [filename]

The name of the background region file. Complex regions are permitted.

(gtifile = "NONE") [string]

The name of a GTI file. When timebinalg='g', this file should be a GTI which contains custom time bins, one bin per good time interval. No matter what the time binning algorithm, gtifile is always used for time filtering of the events.

(timedel = 0) [real]

The time bin size in seconds if timebinalg='u'. A bin size of "0" indicates the full dataset should be summed.

(timebinalg = "g") [string]

The time binning algorithm. Either "u" for uniform time binning (constant time bin size specified by 'timedel'); and "g" for custom time binning (specified by 'gtifile').

(tstart = "INDEF") [string]

Optional global start time (MET seconds), or INDEF to use the input file's start time.

(tstop = "INDEF") [string]

Optional global stop time (MET seconds), or INDEF to use the input file's stop time.

(uvotmag = "YES") [boolean]

If YES, then run the 'uvotcoincidence' and 'uvotflux' tasks to compute calibrated magnitudes for the light curve samples. The default/CALDB parameters are used in the calls to these tasks, and deadtimecorr is set to "NO" (since the raw rates produced by uvotevtlc are not corrected for deadtime).

(frametime = "DEFAULT) [string]

UVOT frame time, in seconds, or DEFAULT. This parameter is used by uvotcoincidence to estimate dead time and coincidence loss.

(uvotmag_params = "NONE") [string]

Any additional parameters to be used when calling the uvotmag task. This string must specify only uvotmag hidden parameters, excluding 'deadtimecorr', which is always set to NO.

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]

Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.

(history = YES) [boolean]

If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Creates a light curve using custom time bins specified by absolute.gti

     uvotevtlc sw00176918992uvvpo_uf.evt event.lc src.reg bkg.reg gtifile=absolute.gti

SEE ALSO

batbinevt