xrtimage help file

NAME

xrtimage -- Evaluate bias and clean bad pixels in XRT Imaging Mode data.

USAGE

xrtimage infile outfile [parameter=]

DESCRIPTION

'xrtimage' calculates the bias, cleans the bad and the saturated pixels (parameter 'cleanbp' = yes), and eliminates the calibration sources ('cleansrc' = yes) for the data taken in the Swift XRT Image mode. In this mode, pixel values are proportional to the charge collected in the pixel, not to the number of events.
The Swift XRT Image data are stored using the FITS Image extension. If multiple exposures (frames) are taken within an observation, these are included in a single file where each extension correspond to a single frame. 'xrtimage' processes all the extensions. It is possible to exclude frames by screening ('gtiscreen'=yes) the file for an input GTI file specified in the parameter 'gtifile'.

With the old version of the on-board software (before v. 8.9), in the Swift XRT image mode the bias is not subtracted on board. For the files produced in that epoch, the bias can be subtracted on ground using a single value valid for all pixels of the CCD. The bias value has been evaluated from ground calibration data and it is stored in a CALDB file. This file is periodically updated by the result analysis of flight calibration data. The bias value can be input in two ways: as a single value specified through the parameter 'bias' or, if the parameter 'bias' is set to a negative value, the task will read the bias value information stored in the file specified through the parameter 'biasfile'. If the 'biasfile' parameter is set to CALDB (default) the latest version of the bias file stored in Calibration Database will be used. As an alternative, the user can input their own bias file (with the same format of the CALDB file). The bias file can contain more than one row, each corresponding to bias measurements at different epochs. The value applied to the data is the result of bias values measured at epochs closest to the time of observation.

With the new version of the on-board software (v. 8.9) the bias can be subtracted on-board and the bias value subtracted to each frame is telemetred together with the last twenty pixels of the frame and stored in the housekeeping header file. If the parameter 'subbias' is set to yes, the ground software estimates the bias and if necessary adjusts the bias subtraction. In fact, for each frame the bias is estimated by calculating the median value of the twenty pixels telemetred and, if the bias value obtained differs from the one subtracted on-board more than a quantity set by the user through the parameter 'biasdiff', the bias correction is adjusted. The parameters 'bias' and 'biasfile' are not considered by the task in this latter case.

To clean bad and saturated pixels (if parameter 'cleanbp' = yes) 'xrtimage' allows three different input bad pixels list file that identify bad pixels similarly to 'xrtflagpix'. These are:

the Bad pixels calibration file which includes the most up to date information about known bad pixels,
the on-board Bad pixels that includes the list of bad pixels used on-board for that observation and
a user-supplied list of bad pixels (this file has to be of the same format as the bad pixels file in CALDB)

The CCD has four calibration sources located at the corners of the detector. Pixels overlapping with calibration sources location are flagged. The location of the calibration sources are read from a CALDB file specified in the parameter 'srcfile'.
It is possible to flag, depending on the CCD temperature, pixels located on the burned spots region (42 columns and 54 rows whose lower left corner is RAWX=307, RAWY=256).

The output file always maintains the structure of the input file and three keywords are added or updated in the file headers. The first,'XRTPHACO', is set to 'T' to indicate that the bias correction was done, the second, 'BIAS_VAL',contains the bias value which has been subtracted, and the last,'XRTBPCNT', stores the total number of bad and saturated pixels removed. 'xrtimage' can be run more than once on an input file. If the input file has been already processed (XRTPHACO is set to 'T'), the task adds to all pixels the bias value previously subtracted (stored in the keyword 'BIAS_VAL') before applying the new bias correction.

The bad and saturated pixels are set to NULL in the image array. The bad and saturated pixels cleaned by 'xrtimage' can be output in a file by specifying the filename in the parameter 'outbpfile'. This file contains as many extensions as the input file and each extension lists the raw coordinates of each pixel removed from the relative image and a flag recording why that pixel has been removed. The flag is a 16 bit binary number and the values are defined in the 'xrtflagpix' helpfile.

PARAMETERS

infile [file name]: Name of the input image FITS file.
outfile [file name]: Name of the output Image FITS file.
hdfile [file name]: Name of the input Header Packet Housekeeping FITS file
(srcfile = CALDB) [file name]: Name of the file containing the locations of the calibration sources. If set to 'CALDB' (default value), use the file in the Calibration Database.
(biasfile = CALDB) [file name]: Name of bias FITS file. If set to 'CALDB' (default value), use the file in the Calibration Database.
(bias = -40) [integer]: Bias value. If the value is negative value, the bias is calculated using the file provided in the 'biasfile' parameter.
(biasdiff = 20) [integer]: Threshold value for bias adjustment.
(maxtemp = 0.0) [real]: Temperature threshold above which burned spots region will be flagged.
(bpfile = CALDB) [file name]: Name of the input bad pixels file. The bad pixels file is read from Calibration Database if 'CALDB' is input. If NONE is input, this parameter is ignored.
(userbpfile = NONE) [file name]: Name of the bad pixels file provided by the user. The default is 'NONE',i.e., no user-provided file is considered
(outbpfile = DEFAULT) [file name]: Name of the output bad pixels file. If outbpfile=DEFAULT, the standard naming convention is used for the output file. If outbpfile=NONE no output file is created.
(bptable = CALDB) [file name]: Name of the on board used bad pixels file. If CALDB is input, the on board bad pixels file stored in the CALDB is read. If NONE is input, this parameter is ignored.
(cleanbp = yes) [boolean]: If set to yes, remove bad and saturated pixels.
(cleansrc = yes) [boolean]: If set to yes, clean images from calibration sources.
(subbias = yes) [boolean]: If set to yes, subtract the bias.
(clobber=no) [boolean]: If 'clobber'=yes ,the file with the same name will be overwritten if it exists.
(gtiscreen = yes) [boolean]: If set to yes, screen for the GTIs.
gtifile [file name]: Name of the input GTI file. If more than one GTI file is necessary, their list must be included in an ASCII file and input by preceeding the file name with a '@'.
(history=yes) [boolean]: If set to yes, write parameter values and other information in HISTORY blocks.
(chatter = 2) [integer]: Chatter Level (min=0, max=5).

EXAMPLES

Perform the bias correction on the file sw00073149002ximrw.img.gz using the bias value stored in CALDB. The bad and saturated pixels, read from the bad pixels calibration file, are set to NULL in the image array. The output is written in the file named outfile.fits.
```
> xrtimage infile=sw00073149002ximrw.img.gz outfile=outfile.fits 
     outbpfile=NONE 
```

BUGS

LAST MODIFIED

June 2005