NAME

batdrmgen - computes BAT detector response matrix (RSP) for a known
source position

USAGE

batdrmgen infile outfile hkfile

DESCRIPTION

batdrmgen is the BAT Detector Response Matrix (DRM) generator tool
that computes the full BAT instrument response to incident photons,
given the source position information read from an input PHA spectral
file. The output FITS file contains a matrix that represents the mean
response of a detector using mask-weighted analysis. Because BAT is
very wide-field, it is not practical to separate the response into
"ARF" and "RMF" components, and for this reason batdrmgen creates a
single response with these components combined (so-called "RSP").
This file should be used in spectral analysis with software like
XSPEC.

The batdrmgen tool accepts as input a pulse height spectrum file
produced by the BAT binning tool 'batbinevt'. BAT spectra are
required to have both a SPECTRUM extension and an EBOUNDS extension,
which describes the energy bin edges used to produce it.

BAT spectra are required to have specific keywords which describe the
position of the source in the field of view. Please note that,
as documented in the BAT software manual, users must run the tasks
'batupdatephakw' and 'batphasyserr' on their spectra before running
batdrmgen. These other tasks apply several instrument-related
corrections which must be in place before the response matrix is
computed.

The batdrmgen tool accepts both "Type I" and "Type II" spectral
files. The most common type of file, Type I files contain a single
spectrum (and are produced using the outtype=PHA1 option of
batbinevt). Type II files contain multiple spectra in a single
extension (and are produced using the outtype=PHA2 option of
batbinevt). The 'row' option of batdrmgen allows the user to select
which Type II spectrum to process.

Upon finishing, batdrmgen attempts to modify the input spectrum to
record the file name of the newly created response matrix. By
default, it uses the standard RESPFILE keyword for this purpose, but
if a column named RESPFILE is present, it will use the column (and
specified row) instead. This column behavior is useful for Type II
spectra, but note that such a column must exist before calling
batdrmgen, otherwise it falls back to using the keyword approach. The
spectral fitting package XSPEC will use either the RESPFILE column or
keyword to automatically load the response matrix.

THEORY of OPERATION

For each incident photon energy bin, batdrmgen computes the BAT
counts spectrum that would be measured if a mono-energetic stream of
photons of unit photon flux with an energy at the bin midpoint were
incident on the array. Repeating this calculation for each incident
energy bin produces an N × M matrix, where N is the number of
incident photon bins and M is the number of PHA counts bins. While the
incident photon energy bin edges can be defined by the user, the
output PHA counts spectrum bin edges are read from the EBOUNDS
extension in the input PHA file.

The BAT DRM is calculated using the set of quasi-physical
calibration parameters that are appropriate for the particular
position of the photon source. These parameters were determined from
least squares fits of the spectral model to actual ground calibration
data measured using radioactive gamma-ray sources that were mounted in
a variety of positions within the BAT field of view (FOV). The
calculation also makes use of the detector charge trapping parameters
measured during ground calibration tests. The angle dependent
calibration parameters and the detector charge trapping parameters are
stored in a calibration file managed by the CALDB utility.

Since batdrmgen models the signal loss due to charge trapping at
different absorption depths within the CZT detectors, it requires a
knowledge of the interaction depth probability distributions for
10-500 keV photons coming from anywhere within the BAT FOV. Simple
Monte Carlo simulations of the absorption of 10-500 keV photons in a 2
mm thick CZT detector were used to create 1000-element tables of the
probabilities of a photon interacting in each of the 2 mm/1000 = 2
micron thick CZT detector "slices." These 1000-element depth
distribution vectors were determined over a moderately dense grid of
energies and incident angles within the BAT FOV. The depth
distribution used for a particular source position and energy is
determined by interpolating within this table. This depth distribution
information is highly compressed and stored in a second calibration
file also managed using CALDB.

Users have the choice of 2 methods for DRM generation: The default
method, "MEAN", accesses calibration parameters that are averaged over
the entire BAT FOV. The alternative method is "TABLE", in which
batdrmgen accesses a table of calibration parameters for different
source positions and sorts the table with respect to the angular
separation between the source direction vector and the position vector
for each ground calibration measurement. batdrmgen then calculates the
weighted average of the parameter values from the three closest
calibration measurements. Thus, the ground calibration parameters
from measurements closer to the source position will be weighted more
heavily.

PARAMETERS

infile [filename]

Name of the PHA FITS input file containing the binned and
mask-weighted
BAT data as well as header keywords containing the source position and
other
information relevant to the response calculation.

outfile [filename]

Name of the output FITS response file (*.rsp) that will contain
the N × M OGIP-compatible response matrix, usable with XSPEC.

hkfile [filename]

Name of the DAP Housekeeping file that contains detector bias voltage
(column: BHVMon_Level) and electronic threshold (column: DM_HK_Vthr)
values for the time interval of interest. If
"NONE" is specified, batdrmgen uses the values specified by the hv_def and
vthr_def parameters.

At present, batdrmgen uses this file simply to check the hv values,
make certain they are nominally 200V, and warn the user if they are
not. Therefore, the default value of "NONE" is perfectly
acceptable.

(row = 1) [integer]

If the input PHA file is a "Type II" spectrum (one spectrum per row of the PHA file), the row parameter specifies which row of the file contains the spectrum for which a response matrix is computed. For a "Type I" spectrum (single spectrum extension) the row parameter is ignored, but should be set to 1.

(calfile = CALDB) [filename]

Name of the FITS file that contains the spectral parameters
for the response function. The default value is "CALDB" thus allowing
the file to be managed by the CALDB utility.

(depthfile = CALDB) [filename]

Name of the FITS file that contains the compressed
photon interaction depth distribution generated by Monte Carlo
simulations. The default value is "CALDB" thus allowing the file to be
managed by the CALDB utility.

the program reads in a FITS
file containing the bin edges (see description of the efile parameter
below);

"LIN"

linear binning

"LOG"

logarithmic binning.

Both LIN
and LOG allow the user to specify the number of bins (see nphoton_bins
below)
and the energy range (see elimit_lo and elimit_hi listed below. )

(detmask = NONE) [string]

Name of a "mask weight" map
(with dimensions of 286x173) which indicates which detectors
were used to accumulate the spectrum. At present, this parameter is
not used.

(method = MEAN) [string]

Computation method for DRM.
The default method ("MEAN") accesses calibration parameters that are
averaged over the entire BAT FOV. The alternative method is "TABLE",
in which batdrmgen accesses a table of calibration parameters for
different source positions and sorts the table with respect to the
angular separation between the source direction vector and the
position vector for each ground calibration measurement. batdrmgen
then calculates the weighted average of the parameter values from the
three closest calibration measurements. Thus, the ground calibration
parameters from measurements closer to the source position will be
weighted more heavily.

File name
for the user-specified FITS file containing the user's custom incident
energy bin edges (used for escale = FILE as discussed above). The
default value, "CALDB" indicates that the default incident bin edges
will be used. This default bin edges have the energy range of 10 keV to
1000 keV divided into 200 logarithmically-spaced bins with bin edge
adjustment made for the absorption edges of CdZnTe (26.711 keV for the
Cd K edge and 31.814 for the Te K edge). As indicated, the file
containing the default input bin edges is managed by the CALDB
utility.

(hv_def = 200.0) [real]

The default detector bias voltage setting, in volts.
This value is used if no hkfile is
specified. If an hkfile is specified and some of the values contained in it
are NULL, this value
is substituted in place of the null values.

(vthr_def = 12.0) [real]

The default XA1 threshold setting, in millivolts.
This value is used if no hkfile is
specified. If an hkfile is specified and some of the values contained in it
are NULL, this value
is substituted in place of the null values.

(fudge = INDEF) [string]

A string
specifying which correction should be applied to the response matrix
calculation. Possible values are:

INDEF

Apply default correction (equivalent to CRAB)

CRAB

Apply correction derived by fitting the residuals of
the uncorrected matrix to an on-axis crab spectrum

NONE

Do not apply a correction

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes"
will cause it to be overwritten.

If history = YES, then a set of HISTORY keywords will be written
to the header
of the specified HDU in the output file to record the value of all the
task parameters that were used to produce the output file.