The Neil Gehrels Swift Observatory

Applying Energy Calibration to BAT Events

1. Overview:

Energy calibration is required for all subsequent BAT analysis. Typically, the SDC performs the energy calibration in their automatic pipeline. This task provides information on how to check for the appropriate calibration procedure and to re-run the calibration when necessary.

Read this thread if you want to: Check and/or recompute the energy calibration for BAT events.

Last update: 2006-09-08

2. Reasons to Re-run the Energy Calibration

2.1. Checking the event file for the correct ground calibration files

You can check the event file to see if its energy scale was correctly calibrated.

Run the command: 

fkeyprint sw00145675000bevshsp_uf.evt.gz GAIN

You should see the following results (among other entries): 

GAINAPP =                    T / Gain correction has been applied
GAINMETH= 'FIXEDDAC'           / Cubic ground gain/offset correction using DAC-b

If these keywords don't exist, or if GAINAPP is false or GAINMETH is not 'FIXEDDAC', then you should run the energy calibration tool.

3. Prerequisites

The SDC should be producing a gain/offset file for every observation. If it is not present, then you must locate the nearest one in time in the trend data in the archive. (see the Swift FTP site in /swift/data/trend/YYYY_MM/bat/bgainoffs).

In this case, let us recompute the energy scale for GRB 050713A (obsid 00145675 000) using the original event file.

4. Initial Steps

Change directories to the location of the event data. 

cd 00145675000/bat/event

If the event file is compressed, unzip it. The energy calibration task modifies the event file in place, and gzipped files cannot be modified. 

gunzip sw*.evt.gz

5. Compute Energy Calibration for BAT Events

The energy calibration task for events is called 'bateconvert'. Here is an example run, 

bateconvert infile=sw00145675000bevshsp_uf.evt \
  calfile=../hk/sw00145675000bcbo01deg00ab.fits.gz \
  residfile=CALDB pulserfile=CALDB fltpulserfile=CALDB \
  outfile=NONE calmode=INDEF

6. What to do if no gain/offset map is present

Gain/offset maps are produced by the BAT flight software periodically to record the pulse height scale of the electronics. While the BAT electronics appear to be quite stable, these regular calibration activities are intended to account for any systematic changes over time. Gain/offset maps are used to compute calibrated event energies from raw pulse heights during ground processing, as shown above.

It is important to understand that the calibration activities are not synchronized with the observing plan. The gain/offset map may have been produced during a previous observation.

Normally the SDC retrieves the proper gain/offset map for GRB data and includes it with the data set. If there are processing errors, or for non-GRB observations, the gain/offset maps may be missing. If that is the case, the gain/offset map must be found manually from the trend data.

Search in the BAT trend data by month. See /swift/data/trend/YYYY_MM/bat/bgainoffs on the HEASARC FTP site.

You want the next earliest gain/offset map produced before the event data in question. Since the trend data are not named by time but by observation, this is especially inconvenient. Rather than searching all the files in the given month, you can narrow your search. In the event file, look for the LDPGAIN and LDPOFFST keywords, 

ftlist sw00145675000bevshsp_uf.evt.gz K | grep LDP | grep Index

which produces the following 

LDPGAIN =                 171. / LDP Gain Index                                 
LDPOFFST=                 478. / LDP Offset Index

These are semi-unique identifiers of which map were used. If you convert these two index values to hexidecimal, you get gain=0x00ab, offset=0x01de. This tells you which kind of filenames to look for in the trend data. You would use a wildcard mask like this: 

ls sw*bcbo01deg00ab.fits*

Note how the offset index (01de) and gain index (00ab) have been incorporated into the file name. This command produces the following three files: 

sw00067672001bcbo01deg00ab.fits.gz  sw00145675000bcbo01deg00ab.fits.gz
sw00145581002bcbo01deg00ab.fits.gz

All of these files should have identical gain/offset contents. However, it is prudent to download each of them and use the one closest in time to the event data of interest according to its TSTART keyword.

7. Modifications