The Neil Gehrels Swift Observatory

Mask Weighting BAT Event Files

1. Overview:

Mask weighting (also known as ray-tracing) is the fundamental operation required to produce background-subtracted light curves and spectrum from the BAT. This task shows you how to check the event file for how it was ray-traced; how to make a new set of mask weights; how to make an auxiliary ray tracing file.

Read this thread if you want to: Check or re-raytrace a BAT event file for use in light curve or spectral analysis.

Last update: 2007-10-03

2. Introduction

Mask weighting is required for all BAT light curve and spectral analysis. This is the first operation needed before background-subtracted light curves or spectra can be analyzed.

The BAT has a coded-aperture imaging system, which means that does not contain any focussing optics, and point sources on the sky are not imaged to a single point on the BAT detector array. BAT imaging and spectroscopy involves cross-correlating the detected shadow pattern with the expected shadow pattern. The first step in this process for GRB analysis is to determine the degree of shadowing for each event recorded during the GRB via ray tracing, and convert shadowing fraction into a weight. At a later step, these weights can be summed to produce a light curve or spectrum.

BAT mask weights are only valid for a given position on the sky! If you are interested in a different (or revised) position, then you must re-run the mask weighting.

3. Reasons to Re-run the Mask Weighting

The Swift Data Center runs the mask weighting tool in the automated pipeline. In principle, you will not need to re-run it yourself. However, in practice, there are several reasons you may want to.

3.1. Checking the event file for the position

You can check the event file to see if it was mask-weighted with the proper position of the GRB.

Run the command: 

fkeyprint sw00145675000bevshsp_uf.evt.gz BAT_

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

BAT_RA  =             320.5402 / [deg] Right ascension of source
BAT_DEC =              77.0751 / [deg] Declination of source

If these lines do not exist, or they contain the incorrect position, then you will need to re-run the mask-weighting task.

3.2. Checking for old software versions

The SDC has used several versions of the software throughout the mission life-time, and they are not always the best versions. Versions of the software before HEASOFT 6.0.3 contained an error which affects the flux determination of far off-axis bursts. HEASOFT 6.1.2 introduced some new filtering techniques which should slightly improve sensitivity. You can check which version of the software was used with the following command: 

fkeyprint sw00145675000bevshsp_uf.evt.gz BATCREAT

You should see the following result: 

# EXTENSION:    1
BATCREAT= 'batmaskwtevt 1.11'   / BAT Program that modified this FITS file

If you see a version earlier than 1.11, then you should definitely re-run the mask-weighting task. If you see a version earlier than 1.16, then you might consider re-running the mask weighting task, which could gain a slight improvement in sensitivity.

3.3. What is an auxiliary raytracing file?

An auxiliary raytracing file contains information about the position of the GRB and the mask geometry as a function of time within the BAT field of view. This information is needed to make an accurate spectral response before, during and after the spacecraft is slewing to the burst. As of late 2005, the SDC has started to make an auxiliary raytracing file for each observation. Before that time, the file will not be present, and you will need to re-run the mask-weighting tool in order to produce one.

4. Prerequisites

We will practice the mask weighting on GRB 050713A (obsid 00145675 000).

Here is what is needed:

In this case, let us enter the revised position as reported by Castro-Tirado (GCN 3584): RA=320.5397083, Dec=+77.074861, and apply the mask weighting operation to the original event list.

5. Initial Steps

Change directories to the location of the event data. 

cd 00145675000/bat/event

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

gunzip sw*.evt.gz

6. Compute Mask Weights for BAT Events

The mask-weighting task for events is called 'batmaskwtevt'. Here is an example run, 

  batmaskwtevt infile=sw00145675000bevshsp_uf.evt \
    attitude=../../auxil/sw00145675000sat.fits.gz \
    ra=320.5397083 dec=+77.074861 \
    detmask=../hk/sw00145675000bcbdq.hk.gz \
    rebalance=YES corrections=default \
    auxfile=sw00145675000bevtr.fits clobber=YES

This analysis may take some time (several minutes), as each event needs to be ray-traced. The speed of the task depends on the number of slews that occur during the observation (i.e. more slews require more intensive calculations).

7. Modifications