NAME
batgse2dpi - Convert FITS files generated by the BAT "blue rack" GSEs
into Detector Plane Images (DPI).
USAGE
batgse2dpi infile outfile histmode
DESCRIPTION
This program 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 Image (DPI)(outfile).
There are several options to how the input files are used and these
are described below under the discussion of the histmode and
windows input parameters.
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 primary HDU of the output file is the DPI, which is a two-dimensional
image with one number per detector and zeros in the gaps between sandwiches.
The second ("LIVETIME") HDU is a binary table containing, for each of the
256 BAT detector module sides, the EXPOSURE, LIVE_TIME and DEAD_TIME.
PARAMETERS
- input [filename]
- Name of an ascii file containing 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 locate 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.
- histmode [string]
- "total" for HITSMAP extension processing, "window" for SPECTRUM
processing. This parameter takes advantage of the two ways in which
detector information is stored in the files generated by the GSE.
If histmode="total," then the tool reads in the HITSMAP extensions of the
input files. These extensions contain a single number for each detector:
the total number of counts (i.e., the spectrum is collapsed). In this
case the tool simply sorts these count numbers into the DPI format (and
applies the deadtime correction if desired.)
If histmode="window," then the tool reads in the SPECTRUM extensions of the
input files. These extensions contain a 4096 element vector for each
detector: the spectrum in ADU units (uncorrected for gain or offset).
In this case the tool requires a file containing, for each detector, a
range, or window, of ADU channels to be used to cut the spectrum, to, for
instance remove low energy noise channels or isolate a single calibration
line. It is the responsibility of the user to provide the correct window
values and to do the necessary conversions from energy to ADU channel. The
window may simply range from 0 to 4096, if no spectral cut is desired for
one or more detector.
- (windows = "") [filename]
- Name of FITS file containing the range of the counts values to be
used for each of the 128 detectors in SPECTRUM extensions. An existing
file in the correct format must be provided if histmode="window." The
format of the file is a binary table with one row per detector, and columns
giving BLOCK, DM, SIDE, and DET, along with WINDOW_LOW and WINDOW_HIGH in
ADU channels.
- (detmask = "") [string]
- Default value is "none". Name of the detector mask file if one is
to be generated. This is a rather crude detector mask, which only masks
out entire sandwiches or blocks, rather than individual detectors.
- (deadpercount = )[real]
- Value between 0 and 1000000 microseconds used to compute deadtime.
Default value is 100 microseconds.
- (deadapp = ) [boolean]
- "YES" apply deadtime correction. "NO" do not apply correction.
- (clobber = NO) [boolean]
- "NO" do not overwrite existing output file. "Yes" overwrite file.
- (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 dpi file using the HITSMAP extensions.The example below
uses the default values for deadpercount and deadapp.
batgse2dpi 'file_list' 'hitsmap.out' histmode=total detmask=mask_t
clobber="Yes" chatter=2
2. Generate a dpi file using the SPECTRUM extensions. The example below
uses the default values for deadpercount and deadapp.
batgse2dpi 'file_list' 'spectrum.out' windows=windows.fits histmode=window detmask=mask_w clobber="Yes" chatter=2
LAST MODIFIED
August 2003