Mask Weighting BAT Event Files
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
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.
You have a refined position for the GRB. Mask weighting is only valid for one position on the sky, so if you have a new position, you need to re-calculate the weights.
You are interested in another source than the GRB.
To capture improvements in the newer software (see below).
To make an auxiliary raytracing file.
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.
We will practice the mask weighting on GRB 050713A (obsid 00145675 000).
Here is what is needed:
Known position of the GRB (RA and Dec)
Attitude file (obsid/aux/swNNNNNNNNNNNsat.fits.gz)
BAT event data (in obsid/bat/event/swNNNNNNNNNNNbevshsp_uf.evt.gz);
BAT quality map (in obsid/bat/hk/swNNNNNNNNNNNbcbdq.hk.gz)
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.
If the event file is compressed, unzip it. The mask-weighting task modifies the event file in place, and gzipped files cannot be modified.
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
infile gives the event file name
attitude gives the attitude file name
ra and dec give the revised sky position of the GRB (see above)
detmask is a quality filter which excludes disabled and noisy detectors; this is important so than an accurate accounting of the number of illuminated detectors can be computed
rebalance=YES means that the resulting light curves will be background-subtracted
corrections=default applies the default corrections to the mask weights
auxfile gives the output auxiliary raytracing file, to be used for spectral analysis
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).
2005-12-04 - first revision
2006-04-12 - formatting changes
2006-09-08 - mention cleaned event lists
2007-01-08 - add discussion of new event filtering in batmaskwtevt 1.16
2007-01-25 - remove mention of cleaned event lists (no longer needed)
2007-10-03 - corrected wrong path in example command