NAME

USAGE

DESCRIPTION

This tool is designed to detect all sources in a UVOT SKY image and do photometry on them. The tools is a wrapper for SExtractor (Bertin & Arnouts 1996, AApS, 117, 393) and accesses a subset of SExtractor's capabilities. SExtractor is used to detect source and extract counts. Uvotdetect optionally corrects these counts for coincidence loss and optionally calibrates them to the standard UVOT flight photometry system (Poole et al., 2008, MNRAS, 383, 627).

Uvotdetect extracts source counts using the SExtractor corrected isophotal magnitudes method (ISOCOR). This magnitude estimate has been found to agree with uvotsource magnitudes to within a tenth of a magnitude on average (when the "calibrate=YES" option is used) for point sources that do not suffer from strong coincidence loss. The accuracy of magnitudes for extended sources is less certain. The problem is not extracting source counts, but applying coincidence corrections and the photometric zero points, both of which are calibrated assuming a point source, to extended sources.

To run uvotdetect the user provides a UVOT SKY image and a detection threshold. The detection threshold is measured in standard deviations above the noise. See the SExtractor documentation for details on the threshold parameter. In general values of 2-4 are reasonable.

The user can provide an optional exposure map. This map contains all of the exposure information needed to process the SKY image. If an exposure map is not provided ("expfile=NONE") the exposure time is read from the EXPOSURE keyword in the FITS header of the SKY image. The "expopt" parameter controls how the exposure map is handled by uvotdetec. In general "expopt=BETA" is preferred for single exposures, but "expopt=ALPHA" should be used for summed images. Setting "expopt=BETA" tells uvotdetect to ignore pixels that was not fully exposed. This method was contributed by Scott Koch.

The "calibrate" parameter controls whether or not the UVOT coincidence loss and photometric calibrations are applied to the count rates returned by SExtractor. If "calibrate=YES" then coincidence loss, detector sensitivity loss, and zero point calibration are performed as indicated by the coinfile, sensfile, zerofile parameters respectively, otherwise no calibration is applied. The "calibrate=NO" option is intended for use when uvotdetect is used for source detection only.

Most of SExtractor's configuration parameters can be specified by the user by specifying a "sexfile". The special value "sexfile=DEFAULT" tells uvotdetect to use a default set of parameters that depend on the details of the input image. If the user supplies a custom "sexfile" the CATALOG_NAME and CATALOG_TYPE parameters must not be specified. These parameters are fixed by uvotdetect and may not be specified in "sexfile". See the SExtractor documentation for details on the structure and contents of this file. SExtractor's command line arguments can be specified using the "sexargs" parameter.

The "zerobkg" parameter specifies the maximum fraction of NULL pixels in the image. If the fraction of NULL pixels exceeds "zerobkg" then uvotdetect will override SExtractor's measurement of the background level. Adjust this parameter if source detection is failing and the background level is near zero.

Uvotdetect has the option of displaying the input image with all of the detected sources marked. To do this specify "plotsrc=YES". Each source is indicated by an ellipse defined by the fitted PROF_MAJOR, PROF_MINOR, and THETA_WORLD parameters. A green ellipse indicates that no SExtractor flags have been set. A yellow ellipse indicates that at least one SExtractor flag has been set. Please see the SExtractor documentation for a discussion of the SExtractor flag values. The "regfile" parameter specifies the name of the region file that these ellipses are written to.

The uvotdetect output FITS catalogue contains the following columns.

RA

The fitted right ascension of the source in decimal degreees.

DEC

The fitted declination of the source in decimal degrees.

RA_ERR

The one-sigma error in RA in arcseconds.

DEC_ERR

The one-sigma error in DEC in arcseconds.

REFID

The reference number of the source.

RATE

The observed count rate from the source. RATE = FLUX_ISOCORR.

RATE_ERR

The one-sigma error in the observed count rate from the source. RATE_ERR = FLUXERR_ISOCORR.

RATE_BKG

The observed background count rate in counts per square arcsecond. RATE_BKG = BACKGROUND / pixel_scale**2.

RAW_TOT_RATE

The total raw count rate from the source and background. RAW_TOT_RATE = RATE + area * RATE_BKG.

RAW_TOT_RATE_ERR

The one-sigma error in the total raw count rate from the source and background. RAW_TOT_RATE_ERR = sqrt( RATE/exposure_time + area*RATE_BKG/exposure_time ).

RAW_BKG_RATE

The total raw count rate from the background. RAW_BKG_RATE = area * RATE_BKG.

RAW_BKG_RATE_ERR

The one-sigma error in the total raw count rate from the background. RAW_BKG_RATE_ERR = sqrt( area*RATE_BKG/exposure_time ).

X_IMAGE

X coordinate of the source on the image. This is the SExtractor X_IMAGE value.

X_ERR

The one-sigma error in X_IMAGE. X_ERR = sqrt( ERRX2_IMAGE ).

Y_IMAGE

Y coordinate of the source on the image. This is the SExtractor Y_IMAGE value.

Y_ERR

The one-sigma error in Y_IMAGE. Y_ERR = sqrt( ERRY2_IMAGE ).

PROF_MAJOR

The profile RMS along the major axis of the source, in arcseconds.

PROF_MINOR

The profile RMS along the minor axis of the source, in arcseconds.

PROF_THETA

The position angle of the major axis, in degrees, measured counterclockwise from east.

THRESHOLD

The SExtractor detection threshold used to detect the source.

FLAGS

SExtractor flags.

RATE_APER1

The count rate in a circular aperture with a radius of 3.0 arcseconds. No corrections have been applied. RATE_APER1 = FLUX_APER1.

RATE_APER1_ERR

The one sigma error in RATE_APER1.

RATE_APER2

The count rate in a circular aperture with a radius of 5.0 arcseconds. No corrections have been applied. RATE_APER2 = FLUX_APER2.

RATE_APER2_ERR

The one sigma error in RATE_APER2.

TOT_COI_FACTOR

The coincidence-loss correction factor for the source + background. This value is the multiplicative correction that is applied to the total source count rate (after correcting to the standard coincidence-loss area) to get the coincidence-corrected total source + background count rate.

TOT_COI_FACTOR_ERR

The one-sigma error in TOT_COI_FACTOR.

TOT_COI_RATE

The coincidence-loss correction count rate from the source + background.

TOT_COI_RATE_ERR

The one-sigma error in TOT_COI_RATE. TOT_COI_RATE_ERR = TOT_COI_FACTOR * RAW_TOT_RATE_ERR.

TOT_SATURATED

This flag is set to TRUE if the total count rate from the source + backgorund is greater than 1/FRAME_TIME.

BKG_COI_FACTOR

The coincidence-loss correction factor for the background. This value is the multiplicative correction that is applied to the gackground count rate (after correcting to the standard coincidence-loss area) to get the coincidence-corrected total background count rate.

BKG_COI_FACTOR_ERR

The one-sigma error in BKG_COI_FACTOR.

BKG_COI_RATE

The coincidence-loss correction count rate from the background.

BKG_COI_RATE_ERR

The one-sigma error in BKG_COI_RATE. BKG_COI_RATE_ERR = BKG_COI_FACTOR * RAW_BKG_RATE_ERR.

BKG_SATURATED

This flag is set to TRUE if the total count rate from the backgorund is greater than 1/FRAME_TIME.

COI_RATE

The coincidence corrected count rate from the source.

COI_RATE_ERR

The one-sigma error in the coincidence corrected rate from the source.

SENSCORR_RATE

The detector sensitivity corrected count rate from the source.

SENSCORR_RATE_ERR

The one-sigma error in the detector sensitivity corrected rate from the source.

CORR_RATE

The most corrected count rate available.

CORR_RATE_ERR

The one-sigma error in CORR_RATE.

MAG

The magnitude of the source in the UVOT system. This magnitude is computed from COI_RATE, which uses the counts derived by the SExtractor ISOCOR method. Therefore, it is not exactly equivalent to the UVOT flight system, which assumes that counts were extracted in a circular aperture. See above for a discussion of potential systematic errors that this may introduce.

MAG_ERR

The one-sigma error in MAG.

FLUX

The flux density in erg/s/cm^2/Angstrom.

FLUX_ERR

The one-sigma error in FLUX.

PARAMETERS

infile [filename]

Name of a FITS-format UVOT SKY image (filename+extension). If the input file has multiple extensions the user must specify on which extension to operate. See the HEASOFT help on filenames for specifying the extension (in section B.2).

outfile [filename]

Output FITS file to write results to. This file contains a table of sources found in the input image.

expfile [filename]

Exposure map file name that corresponds to the input SKY image, or NONE. If the file has multiple extensions the user must specify the specific extension on which to operate. This value is passed to SExtractor if the sexfile parameter is DEFAULT.

(sexfile = DEFAULT) [filename]

SExtractor configuration file or DEFAULT. The user can control nearly every aspect of SExtractor by providing this file. There are certain parameters which uvotdetect overrides for its own purposes: CATALOG_NAME, CATALOG_TYPE.

(sexargs = NONE) [string]

SExtractor command line arguments or NONE. Note that arguments specified on the SExtractor command line override those specified in the configuration file.

threshold [float]

The detection threshold in units of background standard deviation (sigma). See the SExtractor documentation for details on this parameter. This value is passed to SExtractor if the "sexfile" parameter is DEFAULT.

(zerobkg = 0.03) [float]

Maximum fraction of nulls in image to allow SExtractor to calculate background. If the fraction of nulls in the 'middle' third of the image exceeds this limit, the background mean and sigma will be calculated externally using ftstat and passed as constants to SExtractor.

detected [integer]

This output parameter gives the number of sources detected or -1 in the event of an error.

(plotsrc = NO) [boolean]

Display detected source positions in the ds9 viewer.

(expopt = BETA) [string]

Controls processing when an exposure map is provided. "Expopt=ALPHA" is intended for summed images, and is the same as the default behaviour in older versions of uvotdetect that did not have the "expopt" parameter. "Expopt=BETA" is intended for individual exposures. "Expopt=EVENTS" can be used for exposures with very few counts.

(calibrate = YES) [boolean]

Controls whether or not to calibrate the photometry. The calibrate parameter takes precedence over the individual calibration file parameters (zerofile, coinfile, sensfile).

(zerofile = CALDB) [filename]

Zero points calibration file or CALDB or NONE.

(coinfile = CALDB) [filename]

Coincidence loss calibration file or CALDB or NONE.

(sensfile = CALDB) [filename]

Detector sensitivity calibration file or CALDB or NONE.

(lssfile = CALDB) [string]

Large-scale sensitivity correction file which can take several forms. FITS file syntax for an HDU having UVOT LSS calibration format. The special value CALDB indicates to read from the calibration data base. The special value NONE indicates to skip this correction. A value SKY:<fitsname> indicates a sky LSS map (as produced by uvotskylss).

(regfile = NONE) [filename]

Name of the region file that is created for storing the region data used to generate the plot that is created when "plotsrc=YES".

(errfilt = 2) [float]

Minimum significance detection (RATE/RATE_ERR) to include in results. This filtering is only applied if greater than 0.

(clobber = NO) [boolean]

Standard HEAdas clobber parameter; controls whether to overwrite pre-existing files.

(history = YES)

Standard HEAdas history parameter; controls whether to write HISTORY keywords to the FITS headers.

(cleanup = YES) [boolean]

Standard HEAdas cleanup parameter; controls whether temporary files are removed at the end of processing.

(chatter = 1) [integer]

Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task.

EXAMPLES

The following examples illustrate running uvotdetect

1. run uvotdetect prompting for mandatory options:

      uvotdetect
  

2. run uvotdetect specifying all arguments

      uvotdetect infile=image.fits+1 outfile=source.fits expfile=NONE threshold=3 sexfile=DEFAULT plotsrc=YES zerobkg=0.03 expopt=BETA calibrate=YES
  

3. run uvotdetect on an unsummed image with a customized SExtractor parameter file, an exposure map,

      uvotdetect infile=swu00306757000ubb_sk.img+3 outfile=bb_3.fits expfile=swu0036757000ubb_ex.img+3 threshold=3 sexfile=custom.sex expopt=BETA calibrate=YES
  

SEE ALSO

SExtractor, uvotflux, uvotcoincidence, uvotsource

LAST MODIFIED

November 2020