NAME

USAGE

DESCRIPTION

This is a specialized task which computes the celestial coordinates (RA and Dec) for each excess measured on-board by BAT and reported in the BAT "image status packet."

The BAT image status packet is telemetered to the ground with BAT instrument coordinates (so-called theta and phi angles). This task computes celestial coordinates using Swift attitude data and the BAT teldef file.

Image status data are normally stored in the archive in the "trend data" area, under "/swift/data/trend/YYYY_MM/bat/btbimgtr", where YYYY and MM are the year and month number.

The image status packets contain information about the analysis of a BAT on-board sky image. Some of the output columns include:

• TIME - start time of image
• DSP_TIME - original DSP telemetry time
• mForeDur/EXPOSURE - exposure of image in seconds
• mSourcesFound - number of excesses analyzed in image
• RA_CENT,DEC_CENT,PA_CENT - the approximate spacecraft pointing direction and roll angle at the image center-time.
• RA_OBJ,DEC_OBJ - celestial position of each excess (up to 20 per image)
• mThetaOrI,mPhiOrJ - detector (theta,phi) position of each excess (up to 20 per image)
• IMX/IMY - image position in tangent plane coordinates
• mCatNum/CATNUM - catalog number if this excess was identified in the on-board catalog (up to 20 per image); a value of 0 indicates an excess with no identification;
• SNR - measured signal to noise ratio (up to 20 per image), computed based on mStrength (measured counts) and mLocalSigma (local noise level);

The BAT is capable of reporting up to 20 excesses per image, although rarely that many are reported. The columns identified above as "up to 20 per image" are 20-vectors. The actual number of excesses analyzed is in the mSourcesFound column. The remaining (20-mSourcesFound) entries will have mCatNum=NULL, RA_OBJ=NULL, and DEC_OBJ=NULL.

In the input file, the TIME column contains the time at which the BAT on-board digital signal processor (DSP) telemetry was reported, which occurs after the image was created. The actual image exposure begins at mStartForeSec+mStartForeSubsec and ends at mEndForeSec+mEndForeSubsec.

Upon output, batimgstatpos recomputes the TIME column to be the start of the image exposure. The original telemetry timestamp is stored in a new column, DSP_TIME. A keyword, IMGTCORR, is set to {{{'T'rue}}} in the output file to indicate that the meaning of the TIME column has been changed.

PLEASE NOTE: not every excess can be considered to be a "real" detection. A typical BAT on-board detection threshold is 6.5 sigma, and excesses weaker than this could be considered questionable without further analysis.

PARAMETERS

infile [filename]

Name of BAT image status data file.

outfile [filename]

Name of revised image status file, with celestial coordinates. Two new columns are added, RA_OBJ and DEC_OBJ, giving the J2000 equatorial position in degrees.

attitude[string]

Swift attitude file name covering the same time as the image status data.

(teldef = "CALDB") [string]

BAT instrument telescope description file, which defines instrument-to-spacecraft alignments. A value of CALDB will cause the tool to consult the calibration database.

(distfile = "NONE") [string]

File name of BAT image distortion map, or NONE to disable distortion correction. A value of NONE is appropriate if one desires to match the on-board calculated RA/Dec values, which is usually the most desireable. A value of CALDB will cause the tool to consult the calibration database, but PLEASE NOTE that this may result in double-correction of the image distortions, so the BAT team recommends to keep distfile=NONE.

(maxtimegap = 10) [real]

The maximum time gap allowed between the image center time and the nearest attitude data. This cut is intended to prevent celestial coordinate calculation when no nearby valid attitude data is present. When the gap is larger than 'maxtimegap', the output RA_OBJ, DEC_OBJ, RA_CENT, DEC_CENT, PA_CENT columns are set to NULL.

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]

Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.

(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 task parameters that were used to produce the output file.

EXAMPLES

1. Convert a BAT image status file, using the spacecraft attitude file from the same observation.

   batimgstatpos sw00020004010bittb.fits sw00020004010bittb_cel.fits \
      sw00020004010sat.fits 

SEE ALSO

batfftimage, batmaskwtimg

LAST MODIFIED