NAME

baterebin - read in a survey DPH and rebin the energy spectra using non-linear corrections

USAGE

baterebin infile outfile calfile [residfile pulserfile fltpulserfile outmap lowecare highecare detmask ebins outdatatype wholecount rows

DESCRIPTION

This code reads in a BAT Detector Plane Histogram (DPH), which is organized as a single three-dimensional binary table with spectral information for each BAT detector arranged by geometric location in the focal plane. The tool extracts the individual detector spectra and reanalyzes them using cubic corrections from a ground cal file. A new DPH is output with the new spectra.

PARAMETERS

infile="" [string]
Input file name, which must contain a detector plane histogram (extension names BAT_DPH and EBOUNDS must be in the file).

outfile="" [filename]
Name of the output file. The output file is also a DPH file with a new DPH_COUNTS column that has been corrected.

calfile="gainoffset.fits" [filename]
Name of the file that contains the "gain/offset" maps. These are pseudo-linear calibration constants for conversion of ADU to energy units.

(residfile="CALDB") [string]
Name of the file that contains the quadratic or cubic residuals to the ADU to DAC relation, or CALDB. The keyword GAINMETH in this file will control whether the quadratic or cubic correction is performed.

(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.

(fltpulserfile="CALDB") [string]
Name of the file that contains the pulser DAC to energy calibration coefficients, or CALDB; this should be the as-flown coefficients at the time of the observation.

(detmask="NONE") [string]
Name of the file that contains a detmask image or table containing a detmask image. A detmask is a DPI. Pixels containing values other than the value in the goodval keyword are zeroed out in the output DPH.

(outmap="NONE") [string]
Name of the file to be written that contains a detmask image. The values in the image are:
bit 0
indicates high edge of input integral bin is more than the low edge of the lowest energy non integral output bin that you care about (default 14.0 keV)
bit 1
indicates low edge of input integral bin is less than the high edge of the highest non integral output bin that you care about (default 151.4 keV)
bit 2
(value=4) indicates correction > 50 keV in magnitude
bit 4
(value=8) indicates wacked gain/offset values
bit 5
(value=16) indicates no V -> energy conversion value available
bit 6
(value=32) indicates detector masked by input detmask
(lowecare=14.0) [real]
Lowest energy you care about. This value determines only if bit 1 is set in outmap when the integral bin runs into a bin that you care about.

(highecare=151.4.0) [real]
Highest energy you care about. This value determines only if bit 2 is set in outmap when the integral bin runs into a bin that you care about.

(ebins="FILEBINS") [string]
If FILEBINS, the output has the same energy bins as the input (but the counts will be redistributed into the correct energy bins). Energy bin ranges, expressed as a comma-separated list of floating point number ranges, a file name containing energy bin ranges, or CALDB. Each bin in the comma-separated list is specified as EMIN1-EMAX1,EMIN2-EMAX2,... (in units of keV). Bins may not overlap. If a file name is given, it can either be an ASCII file containing the same comma-separated energy bin list, or a FITS file with an EBOUNDS extension (such as a response matrix), containing columns E_MIN and E_MAX (in keV). If CALDB is specified, then the CALDB database is consulted for energy bins. A standard 80-channel set of binnings is used. By using CALDB:n, a specific n-channel binning can be selected (provided it exists in CALDB). If the first energy bin starts at 0, the first bin will include the all the counts from the first bin from the input (which has all counts less than a nominal linear uncorrected 10 keV). If the highest energy bin stops at 6553.6, the highest bin will include all the counts from the highest input bin (which has all counts greater than a nominal linear uncorrectd 191.4 keV). Otherwise integral bin counts will be discarded.

(wholecount = no) [boolean]
Selects whether the output contains only whole (wholecount=yes) or possibly fractional (wholecount=no) counts. Automatically set to yes if the output data type is an integer type. Either way, the output should contain the same total counts per detector as the input.

(rows="-") [string]
The row numbers in the input DPH which are to be included in the output. Row numbers in a DPH correspond to different time intervals. The rows are expressed as a series of ranges separated by commas, e.g. "1, 3-5, 9-10".

(outdatatype="FLOAT") [string]
Data type of the output histograms. One of "SHORT", "INT", "FLOAT", or "DOUBLE". Choosing an integer type will result in the wholecount parameter to be set to YES.

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

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 4 or higher will produce detailed diagnostic output; chatter = 1 prints out a basic diagnostic message. The default is to produce a brief summary on output.

(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 bateconvert 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.

The following examples illustrate ways in which baterebin can be used.

1. Rebin all rows in a DPH file choosing boundaries to the energy bins different from the nominal boundaries in the input file.

   baterebin {infile} {outfile} {calfile} {residfile} {pulserfile} outefile={outefile} rows=- 

2. Rebin the 2nd to 10th rows in a DPH file assigning fractional counts to bins as appropriate.

   baterebin {infile} {outfile} {calfile} {residfile} {pulserfile} rows=2-10 

3. Rebin the third row in a DPH file moving only whole numbers of events from a bin.

   baterebin {infile} {outfile} {calfile} {residfile} {pulserfile} wholecount=yes rows=3 

SEE ALSO

bateconvert -- energy calculation for event files

LAST MODIFIED

Apr 2007