NAME

batdrmgen-multi - generate multiple response matrices for BAT spectra

USAGE

batgeneric infile outroot hkfile ...

DESCRIPTION

batdrmgen-multi is a convenience routine which creates a many BAT response matrices by calling batdrmgen multiple times.

The input must be a "type II" spectrum, with one spectrum per row of the FITS file. The standard tool 'batupdatephakw' must have already been run on the spectrum file, so that special BAT ray tracing is available for each spectrum in the file.

The file must have the following standard spectral keywords:

HDUCLAS1= 'SPECTRUM'           / Contains spectrum
HDUCLAS2= 'NET     '           / Spectrum is background subtracted
HDUCLAS4= 'TYPE:II '           / Multiple PHAs in this HDU
These keywords indicate that the input file is a "type II" spectrum.

During the run, batdrmgen-multi will attempt to modify the input spectral file, if possible. It will create a column called RESPFILE, which will contain the name of the response matrix for each row. If a RESPFILE keyword exists, it will be deleted in order to prevent confusion.

The output will be a series of BAT response matrices, one for each requested row of the input file. The files will be named according to the 'outroot' parameter, as outroot_n.rsp, where n is the corresponding row number of the spectrum.

If batdrmgen fails because the source was outside of the BAT field of view, this is not strictly an error. If the source is outside of the BAT field of view, then there will be zero counts, and the response would have received zero weighting. In this case, batdrmgen-multi will note the issue and then carry onward.

For rows of the spectrum file where batdrmgen was not run successfully, either because the user chose specific rows, or if the source is outside of the field of view, then the corresponding RESPFILE entries will be 'NULL'. It is the user's responsibility to disregard those entries when processing the data downstream.

PARAMETERS

infile [filename]
Name of input spectrum file, a "type II" BAT spectrum file. If the file is writeable, then the RESPFILE keyword/column will be changed, as noted above.

outroot [string]
"Root" name of all output response matrices. Multiple response matrices may be created, with the format outroot_n.rsp.

hkfile = 'NONE' [string]
Name of BAT DAP housekeeping file. Passed to batdrmgen.

(opts = 'NONE') [string]
A list of additional options to pass to batdrmgen, or 'NONE'. The string should be a list of space-separated options, for example opts='calfile="CALDB" depthfile="CALDB"'.

(rows = "-") [string]
List of row numbers to process. Entries must be comma-separated. The entries can be single row numbers, or row ranges. For example, rows="1,3,7-10" will process rows 1, 3, 7, 8, 9, and 10. The string "-" indicates to process all rows.

(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.

(history = YES) [boolean]
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.

EXAMPLES

1. Create response matrices for rows 1,8,9,10 of myspec.pha. The outputs will be generated in myspec_1.rsp, myspec_8.rsp, myspec_9.rsp, and myspec_10.rsp.

  batdrmgen-multi infile=myspec.pha outroot=myspec hkfile=NONE rows=1,8,9,10

SEE ALSO

batdrmgen, batbinevt

LAST MODIFIED

Feb 2009