HEADAS help file

NAME

uvotgrblc - extracts magnitude and flux light curves from aspect corrected UVOT sky images
SYNOPSIS

uvotgrblc @skyimgs.txt @expmaps.txt @sumimgs.txt @sumexps.txt <outdir> <outstem> <RA> <Dec> <sigma>
`DESCRIPTION`




This task extracts calibrated magnitude, flux density and integrated flux light
curves from a set of level II input sky images. For each filter, a FITS light
curve is generated which contains magnitudes, fluxes and all correction factors
that have been applied. By default, plots of the magnitude light curves, the
integrated flux light curves, and an image of the GRB FOV obtained from the sky
image with the highest S/N, are generated. If coordinates are given for the BAT
and/or XRT also, then a finding chart image will be plotted also.


The light curve extraction for each filter consists of several steps:


     Field sources are detected in each input sum image with
    uvotdetect
    

    
 The background region for each OBSID is chosen among three annulli
    centered on the GRB position, excluding any detected field sources that
    intersect with these annuli. The region with the lowest count rate is
    chosen for that OBSID. The annulli inner and outer radii are as follows:
    
        Inner: 15"
Outer: 27"
        Inner: 27"
Outer: 35"
        Inner: 35"
Outer: 42"
    
    
    
 A preliminary source rate is extracted from a 3" aperture in 
    each exposure of each input sky image. If there is no preliminary 
    detection at the specified sigma threshold (see sigmacust
    parameter) in two or more consecutive images, then these images are
    summed to increase signal to noise.
    
    
 The non-aperture corrected light curves are extracted using an
    aperture sized according to the source intensity, and distance and
    intensity of closest neighbors. The aperture is chosen to be either 3", 4"
    or 5". The extraction of the source data is done using the task
    uvotsource.
    
    
 If the GRB aperture is <5", and apermeth='FIELDSTARS',
    then the aperture correction is calculated using the median aperture
    correction for the three "best" field stars. For each star, the rate in a
    standard 5" aperture is compared to that in an aperture the same size as
    for the GRB. If there are no stars that meet the "best" criteria, or
    apermeth='CURVEOFGROWTH', then the aperture correction is
    calculated using the CURVEOFGROWTH option to
    uvotsource. 
    
    
 Flux densities are converted to integrated flux using conversion
    factors estimated by integrating a power-law spectrum (alpha = 1, where
    alpha is defined as S_nu = nu^-alpha), convolved with the filter instrument
    response.


The "best" field stars, mentioned above, used for FIELDSTARS aperture
correction are selected using the following criteria:

    The magnitude must be > 23 for the filter in question in order to
    reject bad sources sometimes "detected" with sextractor
    
    
The raw count rate must be between 0.5 and 5.0 count/s
    
    
The distance from the GRB must be > 20" and < 200"
    
    
The size of the largest axis as reported by uvotdetect, must be less than 7"
    
    
The ratio of the major to minor axes as reported by uvotdetect must
    be less than 1.5 (i.e. the source must be roughly circular)
    
    
The closest neighbor to the source must be > 5" + source radius,
    where source radius is proportional to count rate
    
    
The mean exposure in the 5" around the source must be >
    fldexpthresh*nominal exposure


The last requirement removes sources at the chip edges, which suffer from
false detections, and poor source characterization.

If the option skysummed = 'yes', then the input list of sky images
is treated a list of summed images, and the photometry is only performed on each
the first extension of each image (assumed to be summed).

The flux density to flux conversion factors are as follows 
(units = erg cm^-2 s^-1 mJy^-1):

    V     => 8.240 × 10-13
    B     => 1.405 × 10-12
    U     => 2.286 × 10-12
    UVW1  => 3.587 × 10-12
    UVM2  => 3.355 × 10-12
    UVW2  => 5.030 × 10-12
    WHITE => 1.085 × 10-11

If dogrbsearch='yes' (EXPERIMENTAL), then the above steps are
not performed.  Instead, sources are detected in each snapshot of each filter,
and a master list of sources for each filter is generated. This list is then
compared to a simple USNO-B1 catalog search (LWP perl module and www access
required). Any sources which are not cataloged have aperture photometry
performed on them in the earliest snapshot of each filter. A finding chart
image is produced with the GRB candidates circled. In this case, the only
output is a single FITS table containing the photometry of each source from
uvotsource and a single plotted image.


PARAMETERS


    skyimg [filename]
    
Input list of aspect corrected UVOT sky images. This can be either a
    comma separated list of files, or an @file containing a list of files (one
    per line). Only one sky image per OBSID/FILTER combination is supported.
    

    
expimg [filename]
    
Input list of exposure maps, one for each sky image. This can be either a
    comma separated list of files, or an @file containing a list of files (one
    per line).
    
    
    
sumsky [filename]
    
Input list of summed images - these should be created with
    uvotimsum using the images in the skyimg
    parameter. This can be either a comma separated list of files, or an @file
    containing a list of files (one per line).
    NOTE: If skysummed='yes' then this parameter is ignored!
    

    
    
sumexp [filename]
    
Input list of exposure maps, one for each summed image. This can be either a
    comma separated list of files, or an @file containing a list of files (one
    per line).
    NOTE: If skysummed='yes' then this parameter is ignored!
    

    
    
outdir [string]
    
Output directory. This should not already exist, unless the
    clobber parameter is set to 'yes'.
    
    
    
outstem [string]
    
Stem for output filenames
    
    
    
srcra [HH:MM:SS.SS, HH MM SS.SS or DDD.DD]
    
RA of the GRB. The more accurate this is, the better.
    
    
    
srcdec [DD:MM:SS.SS, DD MM SS.SS or DDD.DD]
    
Dec of the GRB.
    
    
    
sigmacust [float]
    
Detection threshold (sigma).
    

    
(skysummed) [bool]
    
Are the sky images summed? If 'yes', then the list in the
    skyimg parameter is copied into the sumimg
    parameter, and similarly for the expimg and
    sumexp parameters. This is useful if, say, you are working
    with AGN, and do not care about variation from snapshot to snapshot.
    

    
(apermethod) [FIELDSTARS|CURVEOFGROWTH]
    
If set to 'FIELDSTARS', then the method described in DESCRIPTION is
    used to get the aperture correction for each. If set to 'CURVEOFGROWTH',
    then the curve of growth method is used (see fhelp for
    uvotsource).
    

    
(fixedaper) [bool]
    
If set to 'yes', value of aperture parameter is used for
    the aperture radius.
    

    
(aperture) [int (3|4|5)]
    
If fixedaper is set to 'yes', then the value of this
    parameter (in arcsec) is used for the aperture size for all source
    photometry.
    

    
(appendcurves) [bool]
    
If set to 'yes' (default), then all light curves will be merged into a
    multi-extension fits table, with one extension per filter.
    

    
(object) [string]
    
Used as object name in plotting, and OBJECT keyword in output FITS files.
    If set to 'DEFAULT', then the first OBJECT keyword found in the input list
    of sky images will be used.
    
    
    
(centroid) [bool]
    
If set to 'yes', then uvotcentroid will be called on each input 
    summed image. If at least one good centroid is found, then the average
    centroided position will be used (after two rounds of 1.5-sigma rejection).
    

    
(dogrbsearch) [bool]
    
If set to 'yes' (EXPERIMENTAL), then instead of extracting a light curve for a single
    source, detected sources are compared with the USNO-B1 catalog, and
    aperture photometry is performed for each un-cataloged source in the
    earliest snapshots of each filter (see DESCRIPTION above).
    NOTE: Requires LWP perl module to be in your perl library path
    

    
    
(autobkg) [bool]
    
Determine background region automatically (see DESCRIPTION section).
    Otherwise, use region file specified in bkgreg parameter. The
    default is 'yes'. Ignored if dogrbsearch='yes'.
    
    
    
(bkgreg) [filename]
    
Custom background region file. Any region file format that is supported
    by uvotsource and XImage can be used. Ignored if
    autobkg='yes'. Ignored if dogrbsearch='yes'.
    

    
(bkgfield) [bool]
    
If set to 'yes', then detected field sources in each filter will be 
    excluded from the background region defined by the bkgreg 
    parameter. Ignored if autobkg='yes' or dogrbsearch='yes'.
    
    
    
(extinct) [bool]
    
Do extinction correction? If set to 'yes', NED is queried for the
    E(B-V) value corresponding to the GRB coordinates. The extinction is
    calculated using the extinction law from Cardelli et al (1998), with
    R_V=3.1 and coefficients from Roming et al (2008, in preparation).
    Ignored if dogrbsearch='yes'.
    NOTE: No correction factor will be applied to the white
    filter.
    
NOTE: Requires LWP perl module to be in your perl
    library path
    


    
(fldexpthresh) [real]
    
Minimum fraction of exposure time required for field sources. That is,
    if a field source has a mean exposure <
    fldexpthresh*total_exposure, it will not be considered a good
    source for the aperture correction calculation. Ignored if
    apermeth='CURVEOFGROWTH' or dogrbsearch='yes'.
    

    
(doplots) [bool]
    
Produce light curve and image plots? Default is 'yes'
    
    
    
(plotftype) [string]
    
PGPLOT device to use for plotting. Only file type devices are currently
    supported, e.g. /gif. Default is '/gif'.
    
    
    
(logxplot) [bool]
    
Log scale time axis for light curve plots?  Ignored if
    dogrbsearch='yes'.
    
    
    
(usetargid) [bool]
    
If set to 'yes', then plots will be labelled with the value of the 
    first TARGID keyword found in the input FITS images. The TARGID keyword
    will also be written to the output FITS light curves.
    
    
    
(usetrigtime) [bool]
    
If set to 'yes', then plots and light curves will be offset by either 
    the value of the trigtime parameter (if > 0.0), or the 
    first found value of the TRIGTIME keyword in the input FITS images.
    
    
    
(trigtime) [float]
    
GRB BAT trigger time, in MET [s]. If <=0.0, then the output light
    curve time axes will be in MET [s].  Ignored if
    dogrbsearch='yes'.
    

    
(trigfrombat) [bool]

    
Is the trigger time (either the trigtime parameter or the
    value of the TRIGTIME keywords) from a BAT trigger? This parameter affects
    plotting only.
    

    
(xrtsrcra) [HH:MM:SS.SS, HH MM SS.SS or DDD.DD]
    
XRT source RA. If provided, then a finding chart image will be
    displayed adjacent to the FOV image, in the output image file.
    If set to 'NONE' (default), then it will be ignored
    
    
    
(xrtsrcdec) [DD:MM:SS.SS, DD MM SS.SS or DDD.DD]
    
XRT source RA. If provided, then a finding chart image will be
    displayed adjacent to the FOV image, in the output image file.
    If set to 'NONE' (default), then it will be ignored
    

    
(xrterrrad) [real]
    
XRT error radius in arcminutes. Used to plot XRT error circle in
    finding chart, and as a constraint on GRB candidate searching if
    dogrbsearch='yes'.
    

    
(batsrcra) [HH:MM:SS.SS, HH MM SS.SS or DDD.DD]
    
BAT source RA. If provided, then a finding chart image will be
    displayed adjacent to the FOV image, in the output image file.
    If set to 'NONE' (default), then it will be ignored
    
    
    
(batsrcdec) [DD:MM:SS.SS, DD MM SS.SS or DDD.DD]
    
BAT source RA. If provided, then a finding chart image will be
    displayed adjacent to the FOV image, in the output image file.
    If set to 'NONE' (default), then it will be ignored
    

    
(baterrrad) [real]
    
BAT error radius in arcminutes. Used to plot BAT error circle in
    finding chart, and as a constraint on GRB candidate searching if
    dogrbsearch='yes'.
    

    
(cleanup) [bool]
    
Clean up temporary files and intermediate files?
    
    
    
(chatter) [int] [0,5]
    
Chattiness level. 0 means essentially nothing will be printed. 5 is 
    debugging mode with tons of output. Default is 2.
    
    
    
(clobber) [bool]
    
Clobber output files. If outdir directory exists, and
    clobber is set to 'no', then this task will exit with an
    error.
    

OUTPUT

The number of output files depends on the number of filters represented in
the input sky image list, the choice of the doplots parameter, and
the value of the appendcurves parameter.  The maximum set of
output files, for outdir=./test, appendcurves='no',
and outstem=GRBTEST would be:

    ./test/GRBTEST_uvvsrab.lc
    
light curve for V filter
    
    
./test/GRBTEST_ubbsrab.lc
    
light curve for B filter
    
    
./test/GRBTEST_uuusrab.lc
    
light curve for U filter
    
    
./test/GRBTEST_uw1srab.lc
    
light curve for UVW1 filter
    
    
./test/GRBTEST_um2srab.lc
    
light curve for UVM2 filter
    
    
./test/GRBTEST_uw2srab.lc
    
light curve for UVW2 filter
    
    
./test/GRBTEST_uwhsrab.lc
    
light curve for WHITE filter
     
    
./test/GRBTEST_uuve7srab.qdp
    
QDP/PLT file containing magnitude and integrated flux light text light
    curves for all filters

    
./test/GRBTEST_pco1.pco
    
PCO file containing QDP/PLT commands for plotting magnitude light
    curves

    
./test/GRBTEST_pco2.pco
    
PCO file containing QDP/PLT commands for plotting integrated flux light
    curves

    
./test/GRBTEST_uuve7srfb.gif
    
gif plot of all integrated flux light curves on a single Time-Flux plot

    
./test/GRBTEST_uuve7srmb.gif
    
gif mosaic plot of magnitude light curves

    
./test/GRBTEST_uuvsri1.gif
    
gif plot of GRB FOV.


If coordinates for the BAT or XRT are entered (see parameters batsrcra,
batsrcdec, xrtsrcra, xrtsrcdec), then there will
be a single extra plot of the earliest, most sensitive image named:


    ./test/GRBTEST_uuvsri2.gif
    
gif plot of earliest/most sensitive FOV


If appendcurves='yes', then instead of the seven '.lc' files above,
there would be a single light curve FITS file:


    ./test/GRBTEST_uuvetsrab.lc
    
light curve for all filters, one per extension



The FITS light curves have numerous columns, nearly all of which are documented
in the uvotsource fhelp file. The main differences are in how
upper limits are indicated. In the output light curves from this task, an upper
limit is indicated by an INDEF or NULL in the MAG_ERR, FLUX_AA_ERR,
FLUX_HZ_ERR, and INT_FLUX_ERR columns. In this case, the upper limit in each
unit system is the corresponding intensity column.


There are additional columns in the output light curves as well. They are as follows:

    TIME
    
Center of time bin, measured from BAT trigger time, if available. If
    BAT trigger time is not specified, or not found, then this is the MET [s]
    time of the bin center
    
    
XAX_E
    
Half-width of time bin
    
    
TIMEDEL
    
Full-width of time bin
    
    
FRACEXP
    
Fraction exposure of time bin. This is simply
    EXPOSURE/TIMEDEL.
    
    
SIGMA
    
Significance of detection, or non-detection
    
    
BKG_INNER_RADIUS
    
Inner radius of background annulus (NULL if autobkg set to
    'no')
    
    
BKG_OUTER_RADIUS
    
Outer radius of background annulus (NULL if autobkg set to
    'no')
    
    
APERTURE
    
Size of GRB extraction aperture in arcsec
    
    
OBS_ID
    
OBS_ID that this data point came from
    
    
EXPID
    
Exposure ID (or range of exposure IDs) that this data point came from
    
    
AP_SRC_RA
    
RA of field star used for aperture correction (-999 if CURVEOFGROWTH)
    
    
AP_SRC_DEC
    
Dec of field star used for aperture correction (-999 if CURVEOFGROWTH)
    
    
AP_SRC_RATE5
    
Raw count rate of field star (count/s) used for aperture correction in
    5" aperture. AP_FACTOR = AP_SRC_RATE5 / AP_SRC_RATE

    
AP_SRC_RATE
    
Raw count rate of field star (count/s) used for aperture correction in
    same aperture as GRB extraction. AP_FACTOR = AP_SRC_RATE5 / AP_SRC_RATE
    
    
AP_SRC_DIST
    
Distance of field star used for aperture correction from GRB in arcsec



NOTES

Currently a working CALDB must be setup in order to run this task.

LAST MODIFIED
Feb. 2009