bat-burst-advocate 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 Swift BAT Calibration Database (CALDB) must be installed and set up. It is assumed that the input directory is structured as a standard Swift archive, as produced by the Swift Data Center (SDC) and the HEASARC archive. The following subdirectories are required: bat/event, bat/hk, auxil, and tdrss. The uvot and xrt subdirectories are not required, although there is no harm for them to be present. 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).
After initialization, bat-burst-advocate begins by extracting the various burst parameters from the TDRSS burst position message such as position, trigger start/stop time, and background start/stop time. If the TDRSS position message is not available, then the user must supply these values at the command line. As noted below, special processing is done for short bursts.
A quality map is created from the detector enable/disable map and the event data itself, by searching for noisy detectors. Various good time intervals are created. Only data from "near" the burst are retained, defined as within 'tnear' seconds of the burst trigger time ('tnear' is a parameter). Using this time selector, a new event file is extracted, covering only the time range of interest. The mask weight calculation (ray tracing) is done at this stage using the input celestial position, after which, the full event file is copied into separate pre-slew, slew, and post-slew time segments.
Once the near-trigger event file has been created, a search is performed for the "best" burst time interval. This involves searching light curves of several trial time bin sizes (currently 4 ms, 16 ms, 64 ms, 1 s, and 16 s) for the burst duration, using the Bayesian blocks algorithm of 'battblocks'. A set of criteria is used to decide whether to accept a particular trial duration estimate or not. If battblocks failed in any way, then that trial duration estimate is discarded. If the trial estimated duration is greater than 2 times the bin size, and 30% greater than the previous best estimate, then current trial estimate becomes the new best estimate. If 'battblocks' fails to detect the burst with any of the trial binnings, then the script falls back to the time interval values specified in the TDRSS message (or the command line). These time intervals -- T50, T90, and T100 -- form the best estimated durations of the burst, and are used to extract "burst" spectra and images. These intervals are also saved in the output gti subdirectory as standard GTI files.
At this stage, detector and sky images are made for the "burst" time interval, and pre-burst pointed data, if any. Here "pre-burst" means any pointed time interval before T100. If a slew occurs during the burst, then separate burst images are made from the pre-slew and post-slew pointings. Images are never made while the spacecraft is maneuvering. Pre-slew and post-slew partial coding maps are also created, which give an indication of the off-axis exposure level for these time intervals.
If a pre-slew image was successfully created, the burst was not an on-board "image" trigger, and the position came from the TDRSS position message, then bat-burst-advocate will attempt to refine the burst position. The pre-slew sky imge is used to estimate a refined centroid location.
Spectra are made for several different time intervals, including T50, T90, T100, and the peak 1 second flux interval. The total burst is also divided into separate pre-slew, slew and post-slew spectra, in case the user wishes to perform a more refined analysis. Response matrices are made for pre-slew and post-slew time intervals.
Light curves are extracted in several bin sizes and binnings. For the total energy range (15-350 keV), light curves are extracted with 4 ms, 64 ms, and 1 s binnings. Light curves in 4 energy bands are also created (15-25,25-50,50-100,100-350 keV) with 64 ms and 1 s binnings. Finally, 1-channel and 4-channel light curves are created using the Bayesian block time intervals determined by battblocks.
As a last step, a report file is generated which contains basic summary information about the burst analysis. The burst time intervals and position are reported, as well as the counts fluences in various bands.
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.
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.
As detailed above, this task creates several standard spectra and light curves which will often be useful to the observer. However, it is understood that the user may also want to make spectra or light curve products with different options from the standard ones. This section gives some suggestions of how this could be done.
The user is also urged to read the sections of the BAT software documentation on making spectra and light crves for more detailed information and caveats. Both BAT spectra and light curves are created with the 'batbinevt' task, but there are several other procedures that must be completed in order to have scientifically meaningful results. Recommended analysis techniques may change over time, so the user is urged to periodically consult the software documentation to be sure they are using the most up-to-date techniques.
A typical BAT spectrum can be created with the following 'batbinevt' command:
batbinevt infile='outdir/events/swNNNNNNNNNNNb_all.evt' \
outfile='custom_spectrum.pha' outtype=PHA timedel=0 timebinalg=u \
energybins='CALDB:80' detmask='outdir/auxil/swNNNNNNNNNNNb_qmap.fits' \
ecol=ENERGY weighted=YES outunits='RATE'
In this command, 'outdir' is the output directory as given on the batgrbproduct command line; and 'NNNNNNNNNN' is the Swift observation number (which should also be the name of the 'indir', if the data came from the archive). Of course the user is free to choose different time filtering or energy bins, as described in the BAT software documentation; this example uses the standard 80 energy bins. IMPORTANT NOTES: there are additional corrections that must be applied to a spectrum before it is scientifically meaningful. Please read the BAT software documentation before doing spectral fitting.
A custom light curve file can be constructed in a similar way:
batbinevt infile='outdir/events/swNNNNNNNNNNNb_all.evt' \
outfile='custom_lightcurve_1s.lc' outtype=LC timedel=1 timebinalg=u \
energybins='15-350' detmask='outdir/auxil/swNNNNNNNNNNNb_qmap.fits' \
ecol=ENERGY weighted=YES outunits='RATE'
Please see above for the meanings of 'outdir' and 'NNNNNNNNNN'. Of course the user is free to choose different time or energy bins, as described in the BAT software documentation; this example uses 1 second bins in the 15-350 keV range. Please consult the BAT software documentation for more information about constructing meaningful light curves.
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.
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).
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). bat-burst-advocate will perform a standard analysis and place the results in the directory 00154112000-results.
bat-burst-advocate 00154112000 00154112000-results
batmaskwtevt, batbinevt, batdetmask, battblocks, batfftimage, batcelldetect, bat-burst-advocate