NAME

USAGE

DESCRIPTION

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.

PARAMETERS

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

EXAMPLES

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 
         pulserfile=NONE calmode=LINEAR
    -or- bateconvert events.fits cal.fits NONE NONE calmode=LINEAR

         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

          bateconvert events.fits cal.fits NONE NONE \!out.fits calmode=LINEAR
    -or-  bateconvert events.fits cal.fits out.fits NONE NONE 
          calmode=LINEAR clobber=YES

          bateconvert events.fits cal.fits resid.fits pulser.fits

          bateconvert events.fits calfile='none' residfile=NONE 
          pulserfile=NONE zeroit=YES

SEE ALSO

baterebin

LAST MODIFIED