NAME

USAGE

DESCRIPTION

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 "MASK_TAG_WEIGHT".

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

IMPORTANT NOTES

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.

PARAMETERS

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 light curve.

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

EXAMPLES

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

LAST MODIFIED