HEADAS help file

NAME

uvotcentroid - Locate the centroid of a source on a UVOT image.

USAGE

uvotcentroid image=<filename> srcreg=<filename> confidence=<float> niter=<integer> threshold=<float> subdimsiz=<integer> plot=<boolean> plotdev=<string> cleanup=<boolean> chatter=<enumerated integer>

DESCRIPTION

One of the primary goals of the UVOT instrument is to provide accurate celestial positions for gamma ray burst afterglows. The problem can be separated into three parts i) the conversion from detector pixels to sky coordinates (see the ftool swiftxform), ii) an astrometric adjustment to correct systematic pointing uncertainties in the spacecraft attitude (see uvotaspcorr), and iii) within the statistical limits of the data, locate the centroid of a particular source on the image. It is this last item which is performed by uvotcentroid. Sky coordinate conversion must have been performed before running uvotcentroid. This tool can be used before an astrometric correction, but only to determine a statistical confidence limit. An astrometric correction is required to determine an accurate position. But note well that both items i) and ii) above can only be achieved to a certain accuracy and this systematic uncertainty - *which can often exceed the statistical position error provided by uvotcentroid* - is not propagated through the centroiding calculation. The statistical and systematic errors must be combined before reporting a formal position ucertainty.

This tool employs uvotdetect to determine the position of sources. uvotdetect is a wrapper for the sextractor tool which does the fundamental work of detecting and providing source positions; see http://terapix.iap.fr/rubrique.php?id_rubrique=91/. Both point- and extended sources can be centroided and relatively crowded fields can be accommodated. 1-sigma uncertainties are reported by uvotdetect but the method by which sextractor obtains these errors is somewhat nebulous. In order to achieve some confidence in the statistical error, uvotcentroid performs a user-defined number of trials. Before each trial a new, small image is created from the original with the source of interest close to the center. The value of each individual pixel is ajusted by a value chosen at random from the normal cummulative distribution function defined to have a sigma width of the square root of the pixel value. This provides multiple images with identical noise distributions but pixel count distributions varying within the limits defined by the noise. A centoid position for the source in each trial image is recorded and the variance used to estimate confidence limits on the result.

The tool reports back the most-likely RA and Dec of the source, a confidence limit on the position and the number of trials in which the source could not be detected (useful for faint soures). Optionally a plot may be generated to inspect the trial distribution.

If more than one source is located within the subimage, the tool will default to the source nearest to the center of a user-provided region file. The user has the ability to change the size of the sub-field over which uvotcentroid regenerates source images. Small fields have the advantage of less field sources and faster runtimes, at the expense of smaller background statistics. A reasonable subimage size is 20x20 arcsec for optical filter observations and 40x40 arcsec for UV observations.

PARAMETERS

image [string]

The name and correct path to a standard UVOT FITS sky image. if either are incorrect, the tool will complain that it has found no such image. The name should normally contain the FITS extension hosting the image, either by number, e.g. example.fits+1, or name, e.g. example.fits[EXTNAME]. If neither are supplied the tool will look for an image in the primary extension and use it. If none is found, it will default to the first extension and look again. If none is then found the tall will complain.

srcreg [string]

The name and correct path to a standard ds9 region file. These regions can often be complex, uvotcentroid will read the first line which begins with 'fk5;' (ignoring any exclusion regions 'fk5:-') and use these coordinates as the center of each subimages it creates. A typical region file looks like this:

# Region file format: DS9 version 4.0 # Filename: /Volumes/data/00035934002/uvot/image/sw00035934002uuu_sk.img[uu198973450I] fk5;circle(76.37975,-4.3054021,5")

The circle radius is ignored by uvotcentroid in this case. The onus is on the user to provide a region file as close to the source of interest as possible. As an absolute minimum, the center of the region must be closer to the interesting source than any other in the image.

confidence [float]

This is the level of confidence (percent) with which you would like the source position reported. A typical value is 90, but the range is 0 < confidence < 100, exclusive.

niter [integer]

The number of trials to be performed. The more trials, the more accurate the result. A minimum of 100 successful trials are required to provide a confidence estimate. If less than 100 trails could detect the source,a position will be reported but no error estimate. In these cases, re-run the tool with a larger number of trials. uvotcentroid can be run with just 1 trial which will provide a position with no confidence. Provided an astrometic correction has been peformed, most likely this position will be good to at least 1 arcsec > 99.9% confidence.

threshold [float]

uvotdetect will only recognise sources if they are detected above this threshold. The units are sigma, assuming a Gaussian noise distribution. This argument must be positive and larger than zero. For weak, marginal source a threshold of 2 is suitable.

subdimsiz [integer]

The dimensions of the subimage are square and this argument provides the length of one side in arcsec units. The subimage must be large enough to incorporate the source and some background in order for the source to be located.

(ra = 0) [float]

This is not an input argument. It is used to store the output right ascension in decimal degrees so that users and scripts can access the results easily, using e.g. from a shell:

'pget uvotcentroid ra'

(dec = 0) [float]

This is not an input argument. It is used to store the output declination in decimal degrees so that users and scripts can access the results easily, using e.g. from a shell:

'pget uvotcentroid dec'

conflimit [float]

This is not an input argument. It is used to store the output location uncertainty in arcseconds so that users and scripts can access the results easily, using e.g. from a shell:

'pget uvotcentroid conflimit'

conflimit is only useful if you get the confidence level associated with it:

'pget uvotcentroid confidence'

plot [boolean]

If yes, the tool will plot a summary of the result and trials. Two windows are plotted. The left one contains a histogram of the distance in arcsec between the most-likely source position' and all of the trials. The confidence range requested by the user is cast as a region colored yellow behind the histogram. The most-likely RA and Dec, the confidence limit and the number of positive source detections are provided in a dialog box in the top right of this window. The right hand plot shows the distribution of trial positions in RA and Dec space, relative to the most-likely position. The confidence limit is represented as a yellow circle in the background. Each source position is marked by a blue cross symbol. The size of each cross is arbitrary and has no relation to a measured error.

plotdev[boolean]

The device through which you want to make the plot. Available options will depend on your PGPLOT installation but common usages are: /XS - xserver on your monitor /GIF - gif file /PS - postscript document

(chatter = 1) [enumerated integer]

Standard HEAdas chatter parameter (0-5) controlling the verbosity of the task. Setting 0 is mute except for the final result reported to STDOUT, while setting 5 is the most wordy.

EXAMPLES

The following examples illustrate running uvotcentroid

1. run uvotcentroid and get prompted for all mandatory arguments:

      uvotcentroid

2. run uvotcentroid specifying all required control arguments on the command line:

      uvotcentroid image=sw00035934002uuu_sk.img+1 srcreg=srcreg confidence=90
      niter=1000 threshold=3 subdimsiz=20 chatter=5

3. run uvotcentroid specifying all control arguments on the command line, plotting output to a gif file and retaining all intermediate files:

      uvotcentroid image=sw00035934002uuu_sk.img+1 srcreg=srcreg confidence=90
      niter=1000 threshold=3 subdimsiz=20 plot=y plotdev=/gif cleanup=n
      chatter=5

LIMITATIONS

The subimage and region file must always be fully contained within the sky region sampled by the input image. Cases where the source lies very close to RA = 0h or the celestial poles have not been tested.

LAST MODIFIED

February 2024