xrtcentroid help file

NAME

xrtcentroid -- Calculate source centroid position and its error

USAGE

xrtcentroid infile outfile outdir [parameter = < value >]

DESCRIPTION

'xrtcentroid' calculates the source centroid an its associated error for the Swift XRT instrument. 'xrtcentroid' accepts as input file data taken with the Swift XRT Photon Counting mode (event lists or sky images),sky images taken with the Image mode and TDRSS postage stamp images. The centroid is estimated using the 'centroid' command of the XIMAGE package and it is calculated in a box region whose center and half-width can be specified with the parameters 'boxra', 'boxdec' and 'boxradius'. Alternatively, if the parameter 'interactive' set to 'yes', the box region can be defined interactively with the cursor.

The XIMAGE 'centroid' command calculates in the selected region the first guess for the centroid using two possible methods and then uses this best guess for the final calculation. The first guess for the centroid is obtained via a subsequent rebinning of the selected area until the location of maximum is the same as the last rebin (parameter 'hist'=no, default). The alternative method, selected by setting the parameter 'hist' to yes, determines the X and Y maximum from the distributions obtained by summing the counts in the pixels along the X and Y directions. The first best guess for the centroid is used as new center for the final centroid calculation. This is also achieved via two possible methods. The default method ('deriv'=no) re-evaluates the barycenter in boxes reduced by 80% each time from the original selected area. The alternative, selected by specifying the parameter 'deriv' to 'yes', uses the derivative of partial sums method.

The error circle on the position is derived by adding in quadrature the contributions of fours different components: i) statistical uncertainty on the centroid determination, which depends on the source total (time-integrated) intensity; ii) instrument residual misalignment; iii) spacecraft attitude reconstruction accuracy; iv) systematic error. The first was derived from ground calibration, the others are set to pre-launch nominal values. The four error components are recorded in a calibration file included in CALDB.

'xrtcentroid' allows also to calculate only the centroid error. In this case the user must provide in input the source total (time-integrated) intensity and its units ('COUNTS' for Photon Counting mode and 'DN' for Imaging mode) through the parameters 'totalint' and 'unit'.
Centroid and error are written in an output file.

PARAMETERS

infile [file name]: Name of the input Event/Image FITS file. For files containing several images specify the extension with +N where N is the extension number. If 'calcpos' is set to 'no' the 'infile' parameter can be set to 'NONE' and the parameters 'dateobs' and 'timeobs' must be provided.
outfile [file name]: Name of the output ASCII file. If DEFAULT the stem of the input file is used (option available only if parameter 'calcpos' is set to 'yes').
outdir [directory name]: Name of the output directory.
(posfile = CALDB) [file name]: Name of the calibration file containing information on the centroid error components. If CALDB is input (default), the file included in CALDB is used.
calcpos [boolean]: If set to 'yes' calculates the centroid position and its error. If set to 'no' only the position error is calculated and the value of the parameters 'totalint' and 'unit' must be provided.
totalint [real]: Total (time-integrated) COUNTS (Photon Counting mode) or DN (Imaging mode) of the source. It is used to calculate the centroid position error if parameter 'calcpos' is set to 'no'.
unit [string]: String indicating the units for the 'totalint' parameter. Allowed units are 'COUNTS' for Photon Counting mode and 'DN' for Imaging mode.
dateobs [string]: String indicating the start date of observations (yyyy-mm-dd) (used if infile='NONE')
timeobs [string]: String indicating the start time of observations (hh:mm:ss) (used if infile='NONE')
interactive [boolean]: If set to 'yes', use the cursor to define center (boxra boxdec) and size of box (boxradius).
boxra [real]: RA of the box center (degrees or hh mm ss.s). To be used if parameter 'interactive' is set to 'no'.
boxdec [real]: DEC of the box center (degrees or hh mm ss.s). To be used if parameter 'interactive' is set to 'no'.
boxradius [real]: Half-width of the box in arcmin.To be used if parameter 'interactive' is set to 'no'.
(hist=no) [boolean]: If set to 'yes' uses histogram method for the first preliminary centroid estimation.
(deriv=no) [boolean]: If set to 'yes' uses partial derivate method for the final centroid determination.
(clobber = no): If set to 'yes' overwrites the output files with the same name if they exist.
(chatter = 3) [integer]: Verbosity Level from 0 to 5.
(cleanup = yes) [boolean]: If set to 'yes' deletes temporary files.

EXAMPLES

From a Photon Counting mode event file calculates source centroid position and its error and writes them in an output file named 'sw00073125003xpcwnpocl.txt'. The box area used for the centroid calculation is defined interactively with the cursor.
```
> xrtcentroid infile=sw00073125003xpcwnpocl.evt outfile=DEFAULT outdir=./ 
calcpos=yes interactive=yes
```

BUGS

LAST MODIFIED

May 2008