NAME

batgrbproduct - standard BAT GRB processing

USAGE

batgrbproduct indir outdir

DESCRIPTION

batgrbproduct performs standard processing for gamma-ray bursts detected by the Swift BAT instrument. It performs the following activities:

NOTE: the scripts batgrbproduct and bat-burst-advocate are identical. The first name has been preserved for historical reasons, and the second name for consistency with the product scripts of the UVOT and XRT.

By default it is assumed that the TDRSS position message is present. This message provides information about the position of the burst and the initial time interval of the burst. However, the user can override these values using command line parameters. If the RA and Dec values are set to BLIND, then sky images are made, but no further analysis is done, and it is up to the user to search the image to find new sources.

PREREQUISITES - the user must have the standard FTOOLS (6.0.5 or later) installed and set up. Also, the CALDB must be installed and set up. It is assumed that the input directory structure is the same as that produced by the Swift Data Center (SDC). The event by event data should already be energy-calibrated by either the SDC or running bateconvert manually (i.e. the PI and ENERGY columns should be filled).

SUMMARY OUTPUTS

Upon finishing, the output directory contains a text file called process.log. This file contains all the commands executed and detailed output transcripts. Users can check this file to: (a) diagnose problems; and (b) to get ideas on how to use the software to make their own custom science products.

The output directory also contains report.txt, which is text file with a summary report giving basic statistics and factual information about the trigger that was analyzed.

The task concludes by printing to the console a detailed inventory of files it created, including the name and a brief description for each file.

OUTPUT DIRECTORIES

The output files are arranged by type into several directories. The following list describes each directory. Each file name contains code phrases which are also described.

outdir/lc
Light curves. File names with "1chan" and "4chan" have 1 and 4 energy bins respectively. Time binnings can be 1 second ("1s"), 64 millisecond ("64ms") and 4 millisecond ("4ms"). The light curves cover the full range of event data.
outdir/pha
Spectra and response matrices. Spectra are computed for the total burst interval, the T50/T90 intervals, the peak flux interval (1 second), and also for the pre-slew, slew, and post-slew intervals. Response matrices are computed for the pre-slew and post-slew intervals.
outdir/dpi
Detector images. Detector images are made in the pre-burst, pre-slew and post-slew time intervals. Pre-burst means an image created before any detectable emission. Images with 1 and 4 energy bins are created.
outdir/img
Sky and partial coding images. Sky images are made in the same time intervals as detector images, but only for the 1-channel images. Small "postage-stamp" images are also created (suffix ".postimg"), centered on the burst position. Partial coding maps are made for the pre-slew and post-slew intervals.
outdir/gti
Duration information. Various good time interval files are generated. Files with "acs" are spacecraft-attitude related ("acs_10am", "acs_sett", "acs_slew" corresponding to the 10-arcmin, settled, and slewing flags, respectively). Files with "grb" select events near the GRB (within 1500 seconds), including the pre-slew, slew and post-slew intervals. The "tdrss" file contains time intervals transcribed from the TDRSS position message. Files with "bb" are Bayesian blocks produced with the battblocks task on light curves with different time binnings.
outdir/auxil
Auxiliary information. The file with "qmap" is a detector quality map. The file with "output.cat" contains a revised position based on a fit to all pre-slew data. The "output.reg" file is a region file suitable for use within DS9 or FV. The "evaux" file is an auxiliary ray-tracing file.
outdir/events
Event files. Intermediate event files are stored here. Since they are re-created each time the task is run, the files in this directory can be deleted if desired.

SHORT BURSTS

For short burst triggers (triggers shorter than or equal to 64 milliseconds), the BAT flight software reports the incorrect burst trigger time in the BAT TDRSS position message (the keyword containing the trigger start time is named TRIGTIME). The value in the telemetry is the start of a 320 millisecond interval which contains the end of the trigger interval. Thus, in principle, the end of a short burst trigger could have fallen anywhere within a 320 millisecond interval starting at TRIGTIME.

For short bursts this behavior can cause problems. First of all, the automatic burst-finding algorithm in battblocks cannot always find short, faint bursts, which causes the algorithm to fall back to the time intervals reported in the position message. Since these time intervals are incorrect, the result can appear to be a non-detection.

There are several ways to work around this problem. The first way is to examine the light curve and manually adjust the trigger start and stop time to cover the true interval of the burst (using the trigtime and trigstop parameters to this task).

There are also two automatic ways to work around this problem, using the 'shortfix' parameter. If 'shortfix' is set to 'scaledmap', this task will use the BAT "scaled map" product to determine the burst intervals. The scaled map is a detector plane image which contains the exact time intervals of the burst trigger with no ambiguity. If 'shortfix' is set to 'expand' then the trigger interval will be automatically expanded to at least 320 milliseconds so that the true burst interval will be included. This method unavoidably adds extra noise to the analysis, so it should be avoided if possible. The default value of 'scaledmap,expand' causes this task to first check for a scaled map, and only if one is not present, use the expand method.

Users should be aware that the TRIGTIME keyword in all of the output results will contain the adjusted trigger start time and not the telemetered value. This is true if the trigger time is specified on the command line using the trigtime/trigstop parameters, or if it is adjusted automatically via the 'shortfix' parameter.

ERRORS

Most error conditions are reported on the console. Please note that not all bursts are the same, and the Swift spacecraft response is not the same. For example, there may not be a slew to the burst, in which case, there won't be "slew" and "post-slew" spectra or images. Also, if the burst does not extend past the end of the slew (if there is one), there will not be a post-slew spectrum. The task will report these failures to produce spectra and images as errors, but they are benign.

For certain kinds of bursts -- namely short hard bursts -- the task is not always able to find the time interval of the burst. In those cases, the task falls back to the trigger interval reported in the telemetry (or, the adjusted trigger time as described above).

PARAMETERS

indir [string]
Input directory containing Swift data. This directory must have the standard Swift archive layout. Files in the input directory will not be modified.
outdir [string]
Output directory which will contain the processing results. The output files are organized by file type: events, pha (spectra), lc (light curves), gti (good time intervals), auxil (miscellaneous). Also a summary report is created (report.txt), and a detailed processing log (process.log).
ra = "BAT" [string]
RA of the source (degrees). A value of "BAT" or "XRT" means that the BAT or XRT TDRSS position should be used. A value of "BLIND" means to do the analysis blind, without concentrating on any one position in the field of view. When "BLIND", then the trigtime/trigstop/backstrt/backstop parameters must be specified.

dec = "BAT" [string].
Declination of the source (degrees). See "ra".

trigtime = 0.0 [real]
Start time of the foreground interval containing the burst in mission elapsed time. A value of 0 indicates to use the times from the TDRSS position message, and a non-zero value overrides the TDRSS message.

trigstop = 0.0 [real]
Stop time of the foreground interval containing the burst in mission elapsed time. A value of 0 indicates to use the times from the TDRSS position message, and a non-zero value overrides the TDRSS message.

backstrt = 0.0 [real]
Start time of the background interval before the burst in mission elapsed time. A value of 0 indicates to use the times from the TDRSS position message, and a non-zero value overrides the TDRSS message.

backstop = 0.0 [real]
Stop time of the background interval before the burst in mission elapsed time. A value of 0 indicates to use the times from the TDRSS position message, and a non-zero value overrides the TDRSS message.

shortfix = "scaledmap,expand" [string]
Specify a method to work around the problem of incorrect BAT trigger times for short bursts (see detailed description above). The value should be either "scaledmap" (use BAT scaled map to determine burst interval), "expand" (expand the short burst interval to at least 320 milliseconds), or "scaledmap,expand" (try both methods).

date_obs = "INDEF" [string]
User override of the DATE-OBS keyword in event files. This parameter is useful if the input data has an invalid date, like '2001-01-01' or 'TBD'. In that case, set date_obs='YYYY-MM-DD' where YYYY-MM-DD is the date of the observation. A value of "INDEF" indicates that the DATE-OBS keyword should not be changed (although it will still be checked for validity).

(tbkgsub = YES) [boolean]
If set, then the task instructs battblocks to perform background subtraction during the "background" intervals before and after the GRB before estimating the T50/T90 durations. If not set, then it is assumed that the light curves are already background subtracted (via mask weighting). Caveats: setting tbkgsub=YES may cause problems if the light curve doesn't have a true quiescent background interval; setting tbkgsub=NO may cause problems if the light curve is not fully background subtracted.

(pcodethresh = 0.0) [real]
Minimum partial coding threshold. Set this value to a number greater than 0 in order to exclude noisy data when a GRB passes out of the BAT field of view. A value of 0.0 includes all data; A value of 1.0 includes only data when the source is in the (small) BAT fully coded field of view.

(chatter = 1) [integer, 0 - 5]
Currently ignored.

(history = YES) [boolean]
Currently ignored.

EXAMPLES

1. Run the BAT GRB product script on BAT trigger 154112 (GRB 050908). The BAT GRB data are archived in a directory called 00154112000 (the "000" refers to segment number 0). batgrbproduct will perform a standard analysis and place the results in the directory 00154112000-results. 

     batgrbproduct 00154112000 00154112000-results

SEE ALSO

batmaskwtevt, batbinevt, batdetmask, battblocks, batfftimage, batcelldetect, batgrbproduct

LAST MODIFIED

Nov 2007