bateconvert - read in an event file and apply energy conversions.
bateconvert infile calfile residfile pulserfile [outfile] [calmode] [zeroit]
This task reads in an event file and one to three calibration files
containing gains and offsets in a BAT Detector Plane array. For each
event it calculates the energy in keV from the ADU value (PHA), gain
and offset. The tool fills the PI and ENERGY columns in the event FITS
file. PI is the same as energy, but expressed in units of 0.1 keV.
If the event file does not have a PI column, then such a column is
added to the file.
The default is to fill in or create
the PI column in the input file, but if the optional
"outfile" argument is given, a new file with the PI column filled is created.
- infile [filename]
- Input file name. There is no need to include the extension name of the
HDU since bateconvert only operates on an HDU with name "EVENTS."
Unless an outfile name is specified, bateconvert will automatically
fill in the PI column in the infile and/or create a PI column if none exists.
- calfile [filename]
- Name of the calibration file. This is a required parameter. This file
is expected to contain the gain and offset derived in flight. This file
is used for both LINEAR and QUADRATIC 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. If zeroit==YES then the calfile need not exist and calfile
can be set to NONE (or left off the command line).
- residfile [filename]
- Name of the file containing the residuals between a quadratic pulser
gain fitting and a linear fitting. This is a required parameter. This file
is typically derived from ground processing. This file
is used for all but the LINEAR energy conversion. The file
must exist and must include a "BAT_MAP" extension with "GAIN2",
"GAIN," "OFFSET" columns containing calibration parameters in the
proper format and had the appropriate value of the GAINMETH keyword. If
calmodes CUBIC, DIRECTCUBIC, or FIXEDDAC are used, the
file must also have a GAIN3 column. If DIRECTCUBIC or FIXEDDAC are used, the
file must have LIN_GAIN and LIN_OFFSET columns, contain the cubic fit
itself rather than the residuals of the cubic from the linear fit, and the
GAINMETH keyword is FULLCUBIC. If zeroit==YES or CALMODE==LINEAR
then the residfile need not exist and residfile can be set to NONE (or left off
the command line).
- (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. Only
used for QUADRATIC correction; pulsercal=NONE is allowed for the
LINEAR correction case.
- (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. Only used for QUADRATIC
correction; pulsercal=NONE is allowed for the LINEAR correction case.
- (outfile) [filename]
- Output file name. If an output file name is given,
bateconvert will create a new file which is a copy of the input
file with the PI and ENERGY columns filled in. The input file will
remain unchanged. Precede the output file name 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).
- (calmode=INDEF) [string]
- The calibration mode. The currently supported options are LINEAR, QUADRATIC,
CUBIC, DIRECTCUBIC, and FIXEDDAC. If LINEAR is chosen, no residfile is needed,
otherwise, the keyword GAINMETH in residfile must correspond to the calmode.
If calmode == INDEF, the mode will be chosen based on the keyword in the
residfile. FIXEDDAC is the preferred mode for accurate energy correction.
LINEAR is provided to do the same correction as is done by the flight
software before the events are binned in a DPH.
A linear fit applies two parameters, gain and offset using the formula:
ENERGY=GAIN*(OFFSET-PHA). The other fits perform the linear fit and then
adds in a residual to correct for the deviation of the true fit from
linearity, except for DIRECTCUBIC. DIRECTCUBIC computes the energy from
the cubic pre-flight DAC to ADU fit and the values in pulserfile alone, ignoring
the changes indicated by changes in the peaks of the pulser as a function
of DAC value in flight.
- (zeroit=NO) [boolean]
- An optional parameter requesting bateconvert to set all values in
the PI and ENERGY columns to zero instead of calculating the energy
conversion. If zeroit==YES, then calfile can equal NONE.
- (scaled_energy=YES) [boolean]
- If YES (default), then the ENERGY column is written as 16-bit
integers with a TSCAL scale factor which converts to keV. If NO,
32-bit floating point values are written directly. The default is YES
to conserve disk space.
- (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
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 bateconvert can be used.
1. Apply a linear conversion to convert from PHA (ADUs) to ENERGY (keV). The
input file is updated with the PI and ENERGY columns filled in.
bateconvert infile='events.fits' calfile='cal.fits' residfile=NONE
-or- bateconvert events.fits cal.fits NONE NONE calmode=LINEAR
2. Apply the same linear conversion from PHA(ADUs) to ENERGY (keV). Copy the
input file to a new file with the PI and ENERGY columns filled in. The input file is
bateconvert infile='events.fits' calfile='cal.fits' outfile='out.fits'
residfile=NONE pulserfile=NONE calmode=LINEAR
-or- bateconvert events.fits cal.fits NONE NONE out.fits calmode=LINEAR
Overwrite an existing version of 'out.fits'
bateconvert events.fits cal.fits NONE NONE \!out.fits calmode=LINEAR
-or- bateconvert events.fits cal.fits out.fits NONE NONE
3. Apply a quadratic conversion instead of a linear conversion. This
requires valid residfile and pulserfile.
bateconvert events.fits cal.fits resid.fits pulser.fits
4. Set all values in the PI and ENERGY columns of the existing file to zeros.
bateconvert events.fits calfile='none' residfile=NONE