NAME

batgse2dph - Convert FITS files generated by the BAT "blue rack" GSEs into Detector Plane Histograms (DPH).

USAGE

batgse2dph infile outfile calfile residfile pulserfile

DESCRIPTION

This tool reads in an ascii list (infile) of FITS files generated by the "Blue rack" GSE and combines them detector by detector to create a standard BAT Detector Plane Histogram (DPH) (outfile).

The default for this program is to correct the counts in each detector for the deadtime in each particular detector module side (sandwich). The correction is applied by adding up the total number of counts in each sandwich and multiplying by the dead time per count to derive the deadtime for that sandwich. The default dead time per count is 100 usec, but this can be changed using the deadpercount parameter. The deadtime is then subtracted from the exposure time (read from the "EXPOSURE" keyword in the GSE FITS files) to derive the livetime (i.e., livetime = exposure - deadtime). The counts in each detector are multiplied by the ratio exposure/livetime. Since this ratio is always greater than or equal to one, the counts written to the output file will always be greater than or equal to the actual counts recorded by the GSE. The deadtime correction can be turned off if deadapp is set to "NO."

The output file consists of 4 extensions:

PARAMETERS

infile [filename]
Name of an ascii file containine the names of the sixteen FITS files to be used in generating the dpi file. The names must be qualified with the name of the directory in which they are located if necessary.

outfile [filename]
Output file name. Precede it with an exclamation point, !, (or \! on the Unix command line), to overwrite a preexisting file with the same name (or set the clobber parameter to YES). The contents of the output file are described above in the general description of the tool.

(calfile = CALDB) [string]
Name of the calibration file. This is a required parameter. This file is expected to contain the linear gain and offset derived in flight. Since batgse2dph is used with ground gse data (not flight data), this file must be derived from ground measurements. A file that is valid for all ground data taken after 3/3/03 is provided with the CALDB database. The calibration file is used for both LINEAR and CUBIC energy conversion. The file must exist and must include a "BAT_MAP" extension with "GAIN" and "OFFSET," columns containing calibration parameters in the proper format.

(residfile = CALDB) [string]
Name of the file containing the residuals between a quadratic pulser gain fitting and a linear fitting. This file is typically derived from ground processing. This file is used for the CUBIC energy conversion. The file must exist and must include a "BAT_MAP" extension with "GAIN3", "GAIN2", "GAIN", and "OFFSET" columns containing calibration parameters in the proper format. If CALMODE=LINEAR then the residfile need not exist and residfile can be set to NONE.
(pulserfile = CALDB) [string]
Name of the file that contains the pulser DAC to energy calibration coefficients, or "CALDB" to search CALDB. These are the best known coefficients derived from ground calibration efforts. This file is used for the CUBIC energy conversion. The file must exist and must include a "BAT_MAP" extension with "GAIN," "OFFSET," columns containing calibration parameters in the proper format. If CALMODE=LINEAR then the calfile need not exist and calfile can be set to NONE.
(binfile = CALDB:80) [string]
Name of a FITS file with a standard EBOUNDS extension. This file dictates the binning of the GSE data. User can specify CALDB:80 for the standard 80 survey bins or CALDB:4 for the standard 4 light curve bands.
(calmode = CUBIC) [string]
The mode by which an energy is assigned to each ADU channel: LINEAR, QUADRATIC or CUBIC. If calmode=LINEAR, a linear relationship between energy and ADU channel is used. If calmode=QUADRATIC, a more precise quadratic relationship is used. If calmode=CUBIC, a still more precise cubic relationship is used.
(rebin = NO) [boolean]
If "YES", counts in a given ADU channel are distributed into multiple bins if necessary. If "NO", counts in a given ADU channel are placed in a single new bin. The latter is less precise but simpler, and it is sufficient if the ADU bin size is smaller than the size of the new bins.
(deadpercount = 100) [real]
The dead time (in microseconds) resulting from each count recorded by an XA-1 (a DM side). This value is used to compute the total dead time and peform deadtime correction.
(deadapp = YES) [boolean]
If "YES", deadtime correction is applied (counts are multiplied by EXPOSURE/LIVE_TIME). If "NO", no deadtime correction is applied.
(clobber=NO) [boolean]
If "NO", existing output file is not overwritten. If "Yes", existing output file is overwritten.
(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.
(history = NO) [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

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. Generate a dph from GSE data: 

      batgse2dph cg21_x_ba133_030304_23.list cg_21_x_ba133_030304_23.dph
2. Generate a dph from GSE data using the 4 survey bands: 

      batgse2dph cg21_x_ba133_030304_23.list cg_21_x_ba133_030304_23.dph 
      binfile=CALDB:4

LAST MODIFIED

February 2005