NAME

xrtgrblc - Swift XRT GRB light curve extraction task

SYNOPSIS

xrtgrblc evtfiles=<event files> mkffiles=<makefilter files> xhdfiles=<xrt headers> attfiles=<attitude files> outdir=<output dir> outstem=<stem for output files> srcra=<source RA> srcdec=<source Dec> minenergy=<minimum energy> maxenergy=<maximum energy> splitenergy=<soft/hard split>

DESCRIPTION

This task extracts a number of different XRT light curves from a series of Swift gamma-ray burst (GRB) observations. It does so using a wide variety of HEASoft/Swift tasks, and relatively few inputs. It was designed to automate the somewhat cumbersome task of extracting a corrected, flux converted light curve from a potentially large set of Swift observations.

The process of extracting such a light curve observation is complicated by several factors:

To account for the above complications, this task is split into several main steps, described below.

Extraction Region Determination

First, the cleaned event data are separated by mode - either PC or WT. The PC mode event lists are combined into a single image, and a sliding cell detection (XImage detect) is run to detect both the GRB and any field sources in the field of view. Negative circular regions are generated for each field source, with radii equal to twice the half-box radius reported by XImage. The GRB source position is refined using xrtcentroid on this combined PC image, if asked to by the user. Spacecraft orbit separations are determined by running maketime on the input makefilter files, and selecting on the SETTLED, TEN_ARCMIN, VRD1 and ANG_DIST columns (see maketimeexpr parameter).

Next, the source and background light curve extraction regions are determined. For each orbit of the PC mode data, a light curve with 20 second time bins is extracted from a circular region of radius 40'' centered on the GRB. For each orbit of the WT mode data, a light curve with 4 second time bins is extracted from a box 15'' wide and 50'' long, rotated to match the spacecraft roll angle at the end of the orbit (i.e. aligned along the WT strip).

There are two methods that can be used to then determine the extraction regions from these preliminary light curves. First, if splitorbits='yes', and the Chi-Squared probability that the preliminary light curve is constant is < 15%, a sliding-cell type algorithm is applied to the light curves which chooses source and backgroud regions based on the weighted average count rate in a fixed number of non-zero bins (10 at the moment). The time duration that a certain region covers grows or shrinks, depending on how the count rate changes. If, on the other hand, the preliminary light curve is deemed to be constant, then the mean count rate for that orbit is used.

If splitorbits='no', then there is no sub-orbit interval splitting. If the light curve for this orbit is constant (see above), the region corresponding to the mean count rate is used. If the orbit light curve is not constant then the region corresponding to the maximum count rate in the orbit is used. This is done to allow for pileup to be properly accounted for in orbits that have high variability.

The count-rate dependent regions are as follows (cr=weighted mean count rate for sliding-cell, cr=mean count rate for roughly constant curve, cr=max count rate for splitorbits='no' and non-constant curve):

PC

WT

NOTE: The background region for the WT mode data is simply a 450'' x 15'' box along the WT strip. Subtracted from this is a box that is wider than the source extraction region. The higher the count rate, the larger the difference between the source extraction region and the box subtracted from the background region. The minimum difference is 20 pixels (10 per side).

Light Curve Extraction and Correction

Once the extraction regions and corresponding time ranges are determined, an source and background unbinned light curve, spectrum, event list and total counts are extracted for each region. An exposure map is also generated for each interval. The source and background exposure corrections are calculated as the ratio of the nominal exposure time to the mean exposure time per pixel in each region. If there are any counts in the full band (see the minenergy, maxenergy and splitenergy parameters), then to get PSF corrected rates, two ARFs are generated - one with the PSF correction applied and weighted by the exposure map, and one with neither correction. If the source is detected (see the detthresh parameter), a double absorbed power-law is then fit to the extracted spectrum, using both the PSF corrected, and non-PSF corrected ARFs. Galactic nH is assumed (and fixed) in the fit (see nhmap and usernh parameters).

If psfcorrmeth='xspec', then the ratio of the power-law normalizations gives the PSF correction. If psfcorrmeth='xrtlccorr', then the task xrtlccorr is run on the light curve and event file fo rthis interval to get the correction. In either case, the energy conversion factor is calculated using the model flux from the fitted spectrum, after setting the absorption terms to zero.

If this fit fails, or the source is not detected then the previously derived value for the flux conversion is used, and the PSF correction is taken as the average ratio of the PSF to non-PSF corrected spectral responses (no weighting applied). This is justified by the fact that if the fit fails, it is likely due to lack of spectral information, so any PSF correction will be an estimate anyway. If however, there is no previous good spectral fit, then the mean GRB flux conversion of 5e-11erg/cm**2/count is used.

The background subtracted light curve is converted to both corrected count rate, as well as flux using the per-interval conversion factors determined above. The synchronous raw rate, net light curve (source - background), corrected light curve, flux light curve and scaled background light curve are saved to single FITS file for each mode.

Binning and Hardness Ratios

Binning can be done in two ways (or not at all - see bincurve parameter). The first way is binning stricly on counts (bintype=0), whereby the raw light curve is binned to a minimum of minbincnts counts per bin. The binning algorithm will try not to cross what are considered gaps in the GTI coverage. This gap interval can be customized with the gapintv parameter, which is specified in seconds. If there are not enough counts to make a bin between gaps, then gaps may be spanned by time bins. If the algorithm is not able to make a bin from an orbit, but the previous and following orbits do have good bins, then either the bin will be dropped (cutlowbins=yes), or the low count bin will be included in the final products (cutlowbins=no).

The second binning method (bintype=1) is a step-binning one, where the number of counts per bin depends on the net rate (source - scaled background), and the signal-to-noise in that bin. The rates and corresponding counts per bin can be specified using the pcsteprates and wtsteprates parameters. These are comma separated lists of "<max rate>:<counts/bin> pairs. If the rate is less than or equal to <max rate>, then <counts/bin> will be used for that bin. Every time a count is added to a bin, the bin rate, and signal-to-noise are checked, and the required counts for that bin adjusted accordingly. The same rules for gaps and the gap interval as above apply to this method also, except that the gaps are only spanned if there are neither enough counts nor enough signal-to-noise.

For either method, if there are counts left over at the end of the light curves that cannot make a bin, and the signal to noise of the remaining interval is below detthresh, an upper limit is found for the remaining time. This is a Bayesian upper limit as described in Physical Review D 54, 1991 page 166 equation 28.40. See the NOTE below for an explanation of how these are indicated in the FITS light curves.

After applying either of the above methods, the bin boundaries are then applied to the net, corrected, flux, and background light curves. If band splitting is requested, then the binning method is only applied to the hard band, and those bins are applied both to the hard and soft curves. This is done, since in general, there will be more soft photons detected than hard, and the bins need to match to get a hardness ratio. The hardness ratio is simply then calculated as the ratio of corrected hard rate to corrected soft rate. If binning is requested, there will be another extension in the output FITS light curves, with EXTNAME='RATEBIN'. The column names and descriptions (see OUTPUT below), are identical to those for the unbinned light curves in the EXTNAME='RATE' extension.

OUTPUT

File Format

The FITS light curves have the following columns in the 'RATE' extension and, if binning is requested, the 'RATEBIN' extension:

TIME, XAX_E, TIMEDEL, FRACEXP
Standard timing data columns
RATERAW, ERRORRAW
Raw (non-background subtracted) rate and error
RATENET, ERRORNET
Net (source - scaled background) rate and error
RATECOR, ERRORCOR
Corrected rate and error
RATEFLUX, ERRORFLUX
Flux rate and error
RATEBKG, ERRORBKG
Scaled background rate and error

If band splitting is specified there will be a light curve for each band as above. If binning is also done, there will be a single light curve containing both the binned hard curves, and the binned soft curves, as well as the hardness ratio. The soft band columns are named as above, except that each column name has a "1" as a suffix. A similar thing is done for the hard band columns, with "2" as the suffix. The hardness ratio column, and respective error column are named RATIO and RATIOERROR respectively.

Each light curve will also have a GTI extension, indicating the Good Time Intervals used in the light curve extraction.

NOTE: Upper limits are indicated (at the time of this writing) by a NULL or INDEF in all of the ERROR* columns (except ERRORBKG). In this case the RATE* columns indicate the detthresh-sigma Bayesian upper limit.

Filenames, etc.

The number of output files depends on both the clean and splitenergy parameters. The minimum set of output files occurs when clean='yes' and splitenergy<=0.0. As an example, if outdir=./test, outstem=GRBTEST, minenergy, and maxenergy are 0.3, and 10.0 respectively, then the minimum set of output files would be:

./test/GRBTEST_xpcetsra.lc
PC mode source light curves (0.3-10 keV)
./test/GRBTEST_xpcetsr.pha
Average PC mode source PHA
./test/GRBTEST_xpcetbg.pha
Average PC mode background PHA
./test/GRBTEST_xpcet.arf
Weighted average PC mode ARF
./test/GRBTEST_xwtetsra.lc
WT mode source light curves (0.3-10 keV)
./test/GRBTEST_xwtetsr.pha
Average WT mode source PHA
./test/GRBTEST_xwtetbg.pha
Average WT mode background PHA
./test/GRBTEST_xwtet.arf
Weighted average WT mode ARF
./test/GRBTEST_info.fits
FITS table containing light curve, spectral, detection and region information

NOTE:There may be more than one source and background spectrum for each mode. This can happen if the input event files for a given mode were filtered using different GRADE selections, or if the substrate voltage is different between the event files. In either case, the proper RMF will be different, neccessitating separate PHA files. The files will be numbered (e.g. GRBTEST_xpcetsr1.pha) if and only if there is more than one PHA for that mode. Otherwise, the above convention will be used.

If energy band splitting is requested, with splitenergy=2.0, there will be corresponding the following additional files:

./test/GRBTEST_xpce1sra.lc
PC mode source light curves (0.3-2 keV)
./test/GRBTEST_xwte2sra.lc
WT mode source light curves (2-10 keV)
./test/GRBTEST_xpcetsrrb.lc
binned PC mode hardness ratio time series
./test/GRBTEST_xwtetsrrb.lc
binned WT mode hardness ratio time series

Lastly, if clean='no', then most intermediate files will not be removed, and if cleanspec='no' then files needed for the followup task xrtgrblcspec will not be removed. The list of files is too long to list here, but the filenames should be fairly self-explanatory (although they may not be).

PARAMETERS

evtfiles [filename]
List of cleaned event files to extract light curve from. This can either be a comma separated list of event files, or the name of a text file containing a list of filenames (one per line) preceded by an '@' character.

NOTE:These should have been processed with the xrtpipeline task, specifying the (RA, Dec) of the GRB. Otherwise, for WT mode, xrtgrblc may not correctly identify the GRB.

mkffiles [filename]
List of makefilter files (e.g. sw00000000000s.mkf), one for each cleaned event file. This can either be a comma separated list of files, or the name of a text file containing a list of filenames (one per line) preceded by an '@' character. These should be the makefilter files produced by xrtpipeline.

xhdfiles [filename]
List of XRT header housekeeping files (e.g. sw00000000000xhd.hk), one for each clean event file. This can either be a comma separated list of files, or the name of a text file containing a list of filenames (one per line) preceded by an '@' character. These are typically found in the xrt/hk subdirectory of an observation

attfiles [filename]
List of Swift attitude files (e.g. sw00000000000sat.fits), one for each clean event file. This can either be a comma separated list of files, or the name of a text file containing a list of filenames (one per line) preceded by an '@' character. These are typically found in the auxil subdirectory of an observation.

outdir [filename]
Output directory used for writing light curves, as well as various scripts and intermediate files (of which there are many). If clobber is not set, and this directory already exists, the task will fail.

CAUTION: If clobber is set, and this directory already exists, then this task will overwrite files as needed in this directory.

outstem [string]
This is the base name for all output files.

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.

psfcorrmeth (xspec|xrtlccorr) [string]
Method to use to get PSF corrections for each interval. If xspec, then the PSF correction is found using the ratio of Xspec fit normalizations for each interval. If xrtlccorr, then the task xrtlccorr is used to determine the PSF correction for each interval (see fhelp xrtlccorr).

object [string]
Object name, or DEFAULT to use OBJECT keyword from input event files. This will be written to the OBJECT keywords in the output data.

(usecentroid) [bool]
Run the task xrtcentroid to refine position? The input RA/Dec for xrtcentroid will be taken from the srcra and srcdec parameters.

centroidhbox [real]
Half-box width of xrtcentroid box, in arcminutes. This is only queried if usecentroid is 'yes'.

(detthresh) [float]
Detection threshold (sigma). If signal to noise in a given interval is below this level, data from the corresponding time range will not be included in the final products.

(fldsrcdist) [float (degrees)]
Minimum distance in degrees from input RA/Dec (or centroided RA/Dec if usecentroid is set to 'yes') for a detected field source to be considered a field source.

(minpccnts) [float]
Minimum PC mode raw counts required for spectral analysis of each interval. If a PC mode interval has less than minpccnts counts, the flux conversion and PSF correction will be treated as if the spectral fit failed (see Light Curve Extraction and Correction)

(minwtcnts) [float]
Minimum WT mode raw counts required for spectral analysis of each interval. If a WT mode interval has less than minwtcnts counts, the flux conversion and PSF correction will be treated as if the spectral fit failed (see Light Curve Extraction and Correction)

(pcframetime) [float]
Time bin duration for "unbinned" PC mode light curves. If <= 0.0, the FRAMTIME or TIMEDEL keyword from input event files will be used.

(wtframetime) [float]
Time bin duration for "unbinned" WT mode light curves. If <= 0.0, the FRAMTIME or TIMEDEL keyword from input event files will be used. You should note that the WT mode frame time is ~1e-3, so the unbinned light curves may be large if this parameter is set to 0.0. Also, the unbinned light curves will likely not be well sampled at all.

minenergy [float]
The minimum energy in keV to consider in generating the light curves.

maxenergy [float]
The maximum energy in keV to consider in generating the light curves.

splitenergy [float]
Where to split soft and hard bands. If 0.0 or <= minenergy, no band splitting will be done. If binning is also requested (see bincurve parameter), then the hardness ratio curves will be the ratio of the binned, corrected count rate from splitenergy to maxenergy to the binned, corrected count rate from minenergy to splitenergy. The binning for hard/soft bands is done only on the hard band, then the bins are applied to the soft band.

(splitorbits) [bool]
If set to 'no', then extraction regions, psf corrections, and flux conversions will be done on a per-orbit basis. If set to 'yes', each orbit may be split into sub-orbit intervals, based on count rate (see way above).

(maketimeexpr) [string]
This is the expression used to determine spacecraft orbits. It is unlikely that the user will need or want to change this. In fact, changing this parameter might lead to erroneous results, particularly with WT mode data.

(bincurve) [bool]
Create binned light curves also? Default is 'yes'.

(bintype) [int]
0 => bin strictly on counts.
1 => use step binning.

minbincts [int]
Minimum number of counts per bin in binned light curve. This parameter is only queried if bincurve is 'yes', and bintype=0.

pcsteprates [string]
PC mode step binning max rate/count per bin pairs. This should be a comma separated list of <max rate>:<counts> pairs, e.g.:
    1.0:20,2.0:30,3.0:40
This would then bin the curves to 20 count/bin if the rate is <= 1.0, 30 count/bin if the rate is > 1.0 and <= 2.0, etc.

wtsteprates [string]
WT mode step binning max rate/count per bin pairs. See the pcsteprates parameter.

cutlowbins [bool]
Cut bins that are below minbincts per bin? If set to 'no', and either cutlowbinspc or cutlowbinswt is set to 'yes', then low bins will only be cut in specific modes. If set to 'yes', then all low bins will be cut. Only queried if bincurve is 'yes'.

cutlowbinspc [bool]
Cut PC mode bins that are below minbincts per bin? Only queried if bincurve is 'yes'.

cutlowbinswt [bool]
Cut WT mode bins that are below minbincts per bin? Only queried if bincurve is 'yes'.

(gapintv) [real]
Minimum time not covered by GTI to be considered a gap. The binning algorithms will try not to cross gaps when binning.

(nhmap) [int] [-1,1]
Which HI map to use for the nh FTOOL. 0 = LAB map, 1 = Dickey & Lockman Map, -1 = Neither (user specified Nh).

usernh [real]
User specified Nh value to use, in units of cm^-2. Queried if nhmap=-1

(maxredchisq) [real]
Maximum reduced Chi-Squared of per-interval power-law fit to spectrum. If the reduced Chi-Squared of the fit is higher than this, then the previously derived conversion factors are used.

(minredchisq) [real]
Minimum reduced Chi-Squared of per-interval power-law fit to spectrum. If the reduced Chi-Squared of the fit is lower than this, then the previously derived conversion factors are used.

(usetrigtime) [bool]
Offset light curves by TRIGTIME? If set to yes, then all output light curves will be offset by the either the value of the trigtime parameter (if > 0), or by the first TRIGTIME keyword encountered in the input event files. If set to 'no', then the output lightcurves will be offset by the earliest TSTART keyword in the input event files. This parameter will also minimally affect plotting.

(trigtime) [real]
MET trigger time of burst in seconds. If 0.0, then the TRIGTIME keyword of the event files will be used. This will be the TIMEZERO in output light curves.

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

(plotcurves) [bool]
Make plots of various light curves? If set to 'yes', then gif plots of the corrected, flux and hardness ratio curves will be produced, as well as the QDP files used to create them.

(plotftype) [string] (default = '/gif')
Type of plot file to create. This must be a variant of the following PGPLOT file devices: GIF (e.g. '/gif'), Postscript (e.g. '/ps'), X-window plot file (e.g. '/wd'), or PPM (e.g. '/ppm'). The sub-types of these are also supprted (e.g. '/vgif', '/cps', 'vwd', etc.)

(clean) [bool]
Clean up temporary files and intermediate files?

(cleanspec) [bool]
Clean up files required for xrtgrblcspec? These files are basically the per-interval source/background event files, PHA files and ARFs.

(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 existing output files?

NOTES

LAST MODIFIED

July 2009