The Neil Gehrels Swift Observatory

Complete GRB Processing Script

1. Overview:

This recipe describes how to run automatic GRB processing script, batgrbproduct. This script produces light curves, spectra and summary reports that many common users would want. It also produces a detailed log of commands executed, which users can cut and paste to make their own products.

Read this thread if you want to: Make a standard set of GRB products.

Last update: 2007-01-10

2. Introduction

In late 2006, a new version of the BAT software became available which includes the task batgrbproduct. This task generates standard products for a GRB observation, using conservative data filtering and sensible defaults. The BAT team recommends that most users start with this script for their analysis of a GRB. The BAT team itself uses this script to produce the results posted on GCN circulars. The batgrbproduct script performs the mask weighting operation (ray-tracing), creates a quality map, and generates light curves spectra and response matrices with various binnings. Sky images are produced, and if possible, a refined GRB position is derived from these positions.

The task also produces a detailed log file which users can consult when they want to make their own custom light curves or spectra.

3. Prerequisites

It is assumed that the correct energy calibration has been run on the event file. Please see the section on applying an energy calibration to BAT event data for more information.

4. Change to Data Directory

Change to the directory containing the observation, but not into the observation directory itself. Extract the observation data if needed. For example, if the observation directory was /data/grbs/00145675000, then issue the following command, 

cd /data/grbs

5. Creating GRB Products Automatically

To run the script, issue the following command, 

  batgrbproduct indir=./00145675000 outdir=./00145675000-results

where

The script will print diagnostic output to the console as it runs, and may take tens of minutes to an hour to complete, depending on the speed of your computer and hard drive. When the script finishes, it should print an inventory of the results.

6. Results

The results are stored in the 'outdir' directory you specified on the command line. A summary of the results of the analysis is stored in the file report.txt in that directory.

Light curves, spectra and images are stored in the lc, pha and img subdirectories, respectively. Response matrices are generated for the pre-slew and post-slew time intervals. Burst duration measures are reported in report.txt, and also are contained in the gti subdirectory.

More information about the results can be found in the documentation for the batgrbproduct.

7. When Things Go Wrong

There are several situations where batgrbproduct may not be able to perform a totally automatic analysis.

If the burst is very faint, especially a short hard burst, the automatic software is not always able to select the right time interval. If that is the case, the script defaults to the time interval reported in the TDRSS position message, which may not always be appropriate. Users may always override the default time interval by hand, using the trigtime/trigstop/backstrt/backstop parameters. The user can also override the default position by using the 'ra' and 'dec' parameters. By default, batgrbproduct uses the reported BAT position, and not the XRT position.

The Swift spacecraft does not always respond in the same way to a GRB. For example, a slew does not always occur to the burst. In that case, there will be no post-slew images or spectra. There will also be no post-slew spectrum if the burst emission does not extend past the slew to the source. Warning messages will be produced, but they can be safely ignored.

Finally, it is worth mentioning that a burst occasionally is observed already emitting when it enters the BAT field of view. In that case, the automatic duration measures will of course be unreliable. To improve the operation of the script, you should set tbkgsub=NO for those kinds of bursts.

8. Making Your Own Custom Products

batgrbproduct makes a standard set of light curves and spectra which will satisfy many users. However, some users need custom products that are not made automatically. These might be light curves with different binning, or spectra with different time cuts. batgrbproduct does not directly support custom options, but it does produce a detailed log of each command called process.log. This file also contains the result of the command.

You should scan through process.log using your favorite text editor, and locate the light curve or spectrum which most closely matches your need. Then copy the command from the file to the command line and modify it as needed.

9. Spectral Fitting

For more tips, warnings and otherinformation on spectral analysis with BAT, please see the BAT Spectrum and Response section.

10. Modifications

2007-01-09 - initial draft