batmasktaglc - Compute background subtracted light curves from raw BAT mask tagged counts
batmasktaglc infile quadfile maskwt outfile [detmask] [ebounds]
batmasktaglc converts a raw "mask tagged" light curve, produced by the
BAT flight software, into a background subtracted mask weighted light
curve. The BAT flight software by itself produces "unbalanced" mask
weighted sums, which introduces a bias. This task must be used to
remove the bias.
The three basic inputs to the task are the raw mask tagged light
curve; the "quadrant rates" light curve; and the mask weight map used
by the flight software to create the raw mask tagged light curves.
Generally speaking, raw mask tagged light curves will be stored with
file names like: swNNNNNNNNNNNbmtCCCCCCCC_rw.lc.gz,
where NNNNNNNN is the observation and segment numbers, and
CCCCCCCC is the bat catalog number for the source. A given
observation may contain multiple mask tagged sources. The BAT can
produce mask tagged light curves for up to three sources
simultaneously. In addition, the sources chosen for mask tagging may
vary from pointing to pointing in the same observation. Gamma-ray
burst mask tagged light curves will have a catalog number of the form,
0002CCCC, where CCCC matches the last four digits of the
GRB trigger number in decimal.
The quadrant rates file is typically in the obsid/bat/rate directory,
with a file name, swNNNNNNNNNNNbrtqd.lc. It contains the total
rates in each quadrant of the instrument, in several energy bands.
A mask weight map is produced by the BAT every time the mask tagged
sources change (typically every pointing), and describes the weighting
each detector had in computing the mask tagged sums. Typically, the
maps should be attached to the raw mask tagged light curve file as
follow-on extensions. Thus, users should normally just set
"maskwt=INFILE". The extension name of the weight map should be
The tool basically backs out the light curve processing that was
carried out in the flight code to derive a background subtracted light
curve and appropriate statistical error bars. The output file is a
standard light curve file, containing TIME, RATE, ERROR and BACKGROUND
columns, each entry of which is a four-dimensional vector, with one
number for each of the energy ranges described in the EBOUNDS
The mask tagged light curves are invalid during spacecraft slews.
Mask tagged data during slews should be ignored.
The generation of the output file will fail if the file is too large
to fit the available memory.
- infile [filename]
- Name of the raw mask tagged rate file, as described above.
- quadfile [filename]
- Name of the input quadrant rate file.
- maskwt [string]
- Name of mask weight map file.
Normally, users should set the value to "INFILE" or "FILE", to
indicate that the mask weight map is attached to the raw mask tagged
- outfile [filename]
- Output light curve file name.
- (detmask = "none") [string]
- Optional input detector plane mask. This is used to exclude
detectors that are disabled from contributing to the light curves and
errors. This file should always be a flight code generated detector
mask which represents only detectors actually turned off, rather than
a mask derived from ground processing. Typically, these files are
found in files named like obsid/bat/hk/swNNNNNNNNNNNbdecb.fits.
- (ebounds = "INFILE")
- The location of the EBOUNDS file describing the energy ranges in
the light curves. The default is to use an EBOUNDS extension that is
part of the infile (use "INFILE" or "FILE"). One can also specify
"CALDB" if the EBOUNDS extension is not present.
- (corrections = "default") [string]
- Comma-separated list of corrections to apply to the mask
weighting, or "none" if no corrections are to be applied. Other
possible correction types are: "flatfield" (basic flat fielding
correction accounting for both cosine-type and r-squared-type
effects); "cosine" (cosine effects of off-axis illumination
only); "pcode" (partial coding effect only); "ndets" (correction for
disabled detectors). The "default" correction is pcode,flatfield,ndets.
- (detdiv = "YES") [string]
- Set to YES if you want the rate to be per detector (detdiv="YES") or for the whole
array (detdiv="NO"). The division is only applied if the corrections
parameter includes "ndets". Note that if no detector mask is supplied,
then the rate will be divided by the total number of detectors (32768).
- (scale = INDEF) [real]
- The user is allowed to supply a scale factor to correct for known
errors in how the raw mask-tagged light curve is calculated in the
flight software, before 2007-03-13, and corrected after that date. The
scale factor is multiplicative and scales all output counts by the
same factor. The default value of this parameter depends on time.
Before 2009-03-13, the scale factor was 1.3, which was determined
empirically for the average case. After that time, the scale factor
is 1.0. By specifying scale=INDEF (the default), the correction will
be determined based on the time of the observation. The user can
override the default with a more precisely determined scale factor.
- (clobber = NO) [boolean]
- If the output file already exists setting clobber=Yes causes the
existing output file to be overwritten.
- (chatter = 1) [integer 0 - 5]
- The chatter value controls the amount of output written to standard
output. Setting chatter = 5 causes detailed diagnostic output to be
written to standard output.
- (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
Note that when commands are issued on the Unix command line, strings
containing special characters such as '[' or ']' must be enclosed in
single or double quotes.
1. Generate a mask weighted light curve for GRB 050922B (trigger 156434).
batmasktaglc infile=sw00156434000bmt00026434_rw.lc.gz \
quadfile=sw00156434000brtqd.lc.gz maskwt=FILE \
outfile=grb050922b.lc ebounds=CALDB clobber=YES
Note that mask weighted data during slews should be ignored.