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>
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.
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 background 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). There are two lists of regions for each of the PC and WT modes, and these lists can be selected by the user with the pcreglist and wtreglist parameters. The regions that differ between the two lists are indicated by a double asterisk (**).:
PC Region List #1 (pcreglist=1)
PC Region List #2 (pcreglist=2)
WT Region List #1 (wcreglist=1)
WT Region List #2 (wcreglist=2)
Once the extraction regions and corresponding time ranges are determined,
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
for this interval to get the correction. Additionally, a mean
correction or a time-dependent correction can be selected using
the lccorravg parameter. In
either psfcorrmeth 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 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.
The FITS light curves have the following columns in the 'RATE' extension and, if binning is requested, the 'RATEBIN' extension:
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.
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
./test/GRBTEST_xpcetsr.pha
./test/GRBTEST_xpcetbg.pha
./test/GRBTEST_xpcet.arf
./test/GRBTEST_xwtetsra.lc
./test/GRBTEST_xwtetsr.pha
./test/GRBTEST_xwtetbg.pha
./test/GRBTEST_xwtet.arf
./test/GRBTEST_info.fits
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
./test/GRBTEST_xwte2sra.lc
./test/GRBTEST_xpcetsrrb.lc
./test/GRBTEST_xwtetsrrb.lc
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).
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.
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.
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).
xrtlccorr will be run
with createinstrmap = no, and a single PSF correction
factor will be calculated for and applied to each orbit's light
curve. When set to 'no', xrtlccorr will be run with
createinstrmap = yes, pcnframe = 4,
and wtnframe = 10, and a time-dependent PSF
correction factor will be applied to each orbit's light curve.
Using the time-dependent PSF correction factor may be more
accurate in times when the attitude has not stabilized but
requires more processing time to calculate. The lccorravg
parameter has no effect when psfcorrmeth is not set to
'xrtlccorr'.
xrtcentroid to refine position? The input
RA/Dec for xrtcentroid will be taken from the
srcra and srcdec parameters.
xrtcentroid box, in arcminutes. This
is only queried if usecentroid is 'yes'.
usecentroid is set to 'yes') for a detected field source to be
considered a field source.
minpccnts
counts, the flux conversion and PSF correction will be treated as if the
spectral fit failed (see Light Curve Extraction and Correction)
minwtcnts
counts, the flux conversion and PSF correction will be treated as if the
spectral fit failed (see Light Curve Extraction and Correction)
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.
bincurve is 'yes', and
bintype=0.
pcsteprates parameter.
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'.
minbincts per bin? Only
queried if bincurve is 'yes'.
minbincts per bin? Only
queried if bincurve is 'yes'.
nh FTOOL. 0 = LAB map,
1 = Dickey & Lockman Map, -1 = Neither (user specified Nh).
nhmap=-1
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 parameter or the
value of the TRIGTIME keywords) from a BAT trigger? This parameter affects
plotting only.
April 2014