NAME
uvotdetect - detects sources in an UVOT image and does photometry on them
USAGE
uvotdetect infile=<filename>
outfile=<filename>
expfile=<filename>
threshold=<float>
sexfile=<filename>
sexargs=<string>
plotsrc=<boolean>
zerobkg=<float>
detected=<integer>
expopt=<string>
calibrate=<boolean>
regfile=<filename>
clobber=<boolean>
history=<boolean>
cleanup=<boolean>
chatter=<integer>
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 = 0) [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
February 2024