NAME

uvotsource - instrumental source magnitude derived from image

USAGE

uvotsource image=<filename> srcreg=<filename> bkgreg=<filename> sigma=<float> zerofile=<filename> coinfile=<filename> psffile=<filename> lssfile=<filename> syserr=<boolean> frametime=<float> apercorr=<string> output=<string> outfile=<filename> cleanup=<boolean> clobber=<boolean> chatter=<integer>

DESCRIPTION

This tool performs aperture photometry on a single source in a UVOT SKY exposure (sw*.img+extension). It returns information about the count rate from the source, the source's magnitude, and flux density information.

The user specifies the source extraction region and background region using region files that are in the standard ftool or ds9 format. Region files must use the fk5 coordinate system. The RA and Dec coordinates can be specified in either decimal degrees or in sexagisemal format. Examples of a valid source region file and a valid background region file are give below.

Example Source Region File
fk5;circle(12:34:56.78,76:54:32.1,2.5")
Example Background Region File
fk5;circle(123.456,-78.987,12")

If "srcreg" is set to NONE then the tool will return the "sigma"-sigma limiting magnitude for the exposure instead of a source magnitude. The "sigma" parameter tells the tool what level of significance to use to compute the background limit. Photometric and coincidence loss calibration data are read from the files specified by "zerofile" and "coinfile" respectively. If a large-scale sensitivity map is available it can be specified using "lssfile". The special value CALDB tells the tool to obtain calibration data from the Swift/UVOT calibration database. The user must have the $CALDB environment variable correctly set to use this option. If "apercorr" is set to CURVEOFGROWTH the PSF data is read from "psffile". The "psffile" is not used if "apercorr=NONE". If "frametime" is set to DEFAULT the frame time is read from the image header. In some cases this keyword may not be present in the FITS file, so a value can be specified by the user.

There is currently one option for doing photometry. The tool does simple aperture photometry. All of the counts in the "srcreg" region are summed and divided by the exposure time to produce a count rate. The background count rate is subtracted and the magnitude is computed from the coincidence-corrected net count rate. Photometry is done as follows.

  1. Extract the raw counts in three apertures.
    1. The user-supplied source region, "srcreg".

      The source aperture may be any size or shape that can be described in a valid region file. The source region should be selected to maximize the science return. In general faint point sources should use circular apertures with a radius that maximizes the signal-to-noise ratio in the aperture. This is typically about 3 arcsec. For bright sources the standard photometric aperture (defined in "zerofile") is usually preferred. The source aperture should be chosen to minimize contamination from other sources.

    2. The user-supplied background region, "bkgreg".

      The background region may be any size or shape that can be described in a valid region file. It should be chosen to have the same background properties as the source region. It should be free of contaminating sources and large enough so that the mean pixel value is not biased by Poisson statistics. The background value is computed by taking the mean of the pixel values in the background region.

    3. A coincidence-loss correction aperture, defined in "coinfile"

      This region is a circular aperture with an radius defined by the COIAPT column in the COINCIDENCE extension of the "coinfile" file. It is centred on the centre of the "srcreg" region. This is the region that is used to compute the coincidence loss correction factor.

    Counts are extracted from the input exposure by the XImage "counts" command. See the XImage User's Guide for details on how counts are extracted.

  2. Calculate the coincidence loss correction factor from the count rate in the coincidence-loss correction aperture. See the fhelp for uvotcoincidence for details about coincidence-loss corrections.
  3. Apply the coincidence-loss factor to the raw count rate in the source aperture.
  4. Scale the background count rate to the area of the coincidence-loss aperture and then apply the coincidence loss factor.
  5. Scale the coincidence-corrected background rate to the area of the user-supplied source aperture and subtract this from the coincidence-corrected rate in the source aperture to get the coincidence-corrected net count rate from the source.

  6. If "apercorr=NONE" then no aperture corrections are performed. In order to perform aperture corrections to convert the measured magnitude to the standard UVOT system use "apercorr=CURVEOFGROWTH". This option does aperture photometry as described above with one additional step: an estimated aperture correction is applied to the coincidence-corrected net count rate from the source.

    Uvotsource will only return magnitudes and flux densities that are on the standard UVOT photometric system if the source region is the same as the standard photometric aperture defined in "zerofile". If a different aperture ratius is used then one can bring these magnitudes onto the standard system using "apercorr=CURVEOFGROWTH", which computes an aperture correction to the coincidence-loss corrected net count rate from the source. See the fhelp for uvotapercorr for details on aperture corrections and how they are applied. Be aware that "apercorr=CURVEOFGROWTH" assumes that the source is a point source.

    Uvotsource adds a systematic uncertainty to the error in the aperture-corrected net count rate that accounts for the uncertainty in the shape of the UVOT PSF. See the discussion of the "fwhmsig" parameter in the fhelp for uvotapercorr for a discussion of this. The version of uvotsource that was released with HEADAS 6.4 (Swift_Rel2.8(BLD22)_19Nov2007, use the swiftversion command to check which version of uvotsource you are using) does not allow the user to set this number. A value of 5% is used. The value of "fwhmsig" does not affect the value of the aperture correction, only the error in the aperture correction.

    Magnitudes derived from a smaller-than-standard aperture will have smaller statistical errors than magnitudes derived using the standard aperture. This is because the smaller aperture contains less background and is more dominated by light from the source. However, the trade-off is that the smaller-aperture magnitudes, because of the need for aperture correction, will have an extra systematic component to their errors that is not present in the standard aperture magnitudes. Users need to weigh the trade-off between these two sources of error when deciding on whether or not to use "apercorr=CURVEOFGROWTH".

  7. If a large-scale sensitivity map is specified using "lssfile" then a large-scale sensitivity correction is applied to the count rate from the source. If "lssfile=NONE" then no large-scale sensitivity correction is applied. See the fhelp page for uvotlss for more details.
  8. If a detector sensitivity calibration file is specified using "sensfile" then a detector sensitivity correction is applied to the count rate from the source. If "sensfile=NONE" then no detector sensitivity correction is applied.
  9. Apply the photometric calibrations from "zerofile" to the net count rate from the source, after all of the corrections have been applied, to obtain the magnitude and flux density information described below. Note that the photometric calibrations assume that the source region is the same as the standard photometric aperture, so the values returned will not be on the standard UVOT photometric system if some other aperture region is used. See the description of the CURVEOFGROWTH aperture correction for details on how to correct for this.

The aperture correction applied by CURVEOFGROWTH is approximate and is intended for preliminary data analysis. It does not take into account changes in the PSF due to temperature or count rate variations (see the uvotapercorr fhelp). For high-precision photometry "apercorr=NONE"should be used, and aperture corrections that take these factors into account should be performed by the user.

Uvotsource returns the following information:

Source Information
The position is the position specified in the "srcreg" region file. The exposure time is the value of the EXPOSURE keyword.
Magnitude Information
The magnitude of the source, its one-sigma statistical error, and the significance of the detection. Background is the magnitude of the sky. Background-limit is the "sigma"-sigma limiting magnitude of the exposure. Coincidence-limit is the magnitude corresponding to a count rate of one count per frame time.
Flux Information
The flux density information is given in cgs units of flux per Angstrom unit. Flux densities are computed from flux conversion factors in "zerofile" assuming a mean GRB spectrum. They do not reflect the actual spectrum of the source.
Corrected Rate Information
This is the count rate of the source after all corrections have been applied. This includes aperture corrections if the "apercorr=CURVEOFGROWTH" was used; large-scale sensitivity corrections if a large-scale sensitivity map was specified; and detector sensitivity corrections if specified.
Raw Rate Information
This is the raw count rate from the source after subtracting the background count rate, but before applying coincidence, aperture, or large-scale sensitivity corrections.
Flux mJy
The flux density information is given in milliJansky. Flux densities are computed from flux conversion factors in "zerofile" assuming a mean GRB spectrum. They do not reflect the actual spectrum of the source.

The output FITS file contains the following columns.

MET
The mission elapsed time (MET), in seconds since the reference time, of the observation. The point in the exposure that MET refers to is specified by the TIMEPIXR keyword in the header of "outfile"
EXTNAME
The name of the FITS extension that this source is in.
TSTART
The MET start time of the exposure
TSTOP
The MET stop time of the exposure.
EXPOSURE
Please see <http://swift/gsfc.nasa.gov/docs/swift/analysis/uvot_digest.html> for details about how the UVOT exposure time keywords are used.

The EXPOSURE column contains the total exposure time with the following corrections applied.

EXPOSURE represents the actual time that the detector was was detecting photons.

TELAPSE
TSTOP - START
TIME
The offset of this row from 'timezero'. uvotsource initializes TIME to 0. uvotmaghist TIME based on its timezero parameter.
SRC_AREA
The area of the user-supplied source extraction region in square arcseconds.
BKG_AREA
The area of the user-supplied background region in square arcseconds.
PLATE_SCALE
The plate scale, in arcsec per pixel, of the image.
RAW_TOT_CNTS
The total measured counts in the source region.
RAW_TOT_CNTS_ERR
The one-sigma error in RAW_TOT_CNTS. This error is calculated using binomial statistics since the number of counts that can be measured is limited by the number of frames in the exposure. The binomial error approaches the Poisson error in the limit of small count rates. The minimum error is set to 1 count, even if no counts are recorded.
RAW_BKG_CNTS
The total measured counts in the background region.
RAW_BKG_CNTS_ERR
The one-sigma error in RAW_BKG_CNTS. This error is calculated using binomial statistics since the number of counts that can be measured is limited by the number of frames in the exposure. The binomial error approaches the Poisson error in the limit of small count rates. The minimum error is set to 1 count, even if no counts are recorded.
RAW_STD_CNTS
The total measured counts in the coincidence loss region.
RAW_STD_CNTS_ERR
The one-sigma error in RAW_STD_CNTS. This error is calculated using binomial statistics since the number of counts that can be measured is limited by the number of frames in the exposure. The binomial error approaches the Poisson error in the limit of small count rates. The minimum error is set to 1 count, even if no counts are recorded.
RAW_TOT_RATE
The total measured count rate in the source region.
RAW_TOT_RATE_ERR
The one-sigma error in RAW_TOT_RATE. RAW_TOT_RATE_ERR = RAW_TOT_CNTS_ERR / EXPOSURE.
RAW_BKG_RATE
The total measured count rate in the background region.
RAW_BKG_RATE_ERR
The one-sigma error in RAW_BKG_RATE. RAW_BKG_RATE_ERR = RAW_BKG_CNTS_ERR / EXPOSURE.
RAW_STD_RATE
The total measured count rate in the coincidence loss region.
RAW_STD_RATE_ERR
The one-sigma error in RAW_STD_RATE. RAW_STD_RATE_ERR = RAW_STD_CNTS_ERR / EXPOSURE.
COI_STD_FACTOR
The coincidence-loss correction factor for the coincidence-loss region. This value is the multiplicative correction that is applied to raw count rate (after correcting to the STD_AREA) to get the coincidence-corrected count rate.
COI_STD_FACTOR_ERR
The COI_STD_FACTOR_ERR = DELTA / RAW_STD_RATE, where DELTA is the change in the COI_TOT_RATE corresponding to a 1-sigma change in the RAW_STD_RATE.
COI_BKG_FACTOR
The coincidence-loss correction factor for the background region. This value is the multiplicative correction that is applied to the background count rate (after correcting to the STD_AREA) to get the coincidence-corrected background count rate.
COI_BKG_FACTOR_ERR
The COI_BKG_FACTOR_ERR = DELTA / RAW_BKG_RATE, where DELTA is the change in the COI_BKG_RATE corresponding to a 1-sigma change in the RAW_BKG_RATE.
COI_TOT_RATE
The coincidence-loss correction count rate in the source region.
COI_TOT_RATE_ERR
The one-sigma error in COI_TOT_RATE.
COI_BKG_RATE
The coincidence-loss correction count rate in the background region.
COI_BKG_RATE_ERR
The one-sigma error in COI_BKG_RATE.
COI_SRC_RATE
The coincidence-loss correction count rate from just the source.
COI_SRC_RATE_ERR
The one-sigma error in COI_SRC_RATE. COI_TOT_RATE_ERR = sqrt(COI_TOT_RATE_ERR**2 + (COI_BKG_RATE_ERR*SRC_AREA)**2 )
AP_FACTOR
The aperture correction factor to be multiplied by COI_SRC_RATE. AP_FACTOR = 1.0 if "apercorr=NONE" was selected.
AP_FACTOR_ERR
The one-sigma error in AP_FACTOR. AP_FACTOR_ERR = AP_COI_SRC_RATE_ERR / COI_SRC_RATE_ERR.
AP_COI_SRC_RATE
The source count rate with coincidence-loss corrections and aperture corrections applied.
AP_COI_SRC_RATE_ERR
The one-sigma error in AP_COI_SRC_RATE. This error is computed as the quadratic sum of COI_SRC_RATE_ERR and the systematic error in the shape of the point-spread function. The systematic error in the shape of the point-spread function is currently assumed to be 5%.
LSS_FACTOR
The large-scale sensitivity factor to be applied to AP_COI_SRC_RATE. LSS_FACTOR = 1.0 if no large-scale sensitivity map was specified.
LSS_RATE
The source count rate with coincidence-loss corrections, aperture corrections, and large-scale sensitivity corrections applied. LSS_RATE = AP_COI_SRC_RATE / LSS_FACTOR.
LSS_RATE_ERR
The one-sigma error in LSS_RATE. This is computed by dividing AP_COI_SRC_RATE_ERR by LSS_FACTOR.
SSS_FACTOR
The small-scale sensitivity factor to be applied to LSS_RATE. SSS_FACTOR = 1.0 if no small-scale sensitivity is determined.
SSS_RATE
The source count rate with small-scale sensitivity corrections applied. SSS_RATE = LSS_RATE * SSS_FACTOR.
SSS_RATE_ERR
The one-sigma error in SSS_RATE. SSS_RATE_ERR = LSS_RATE_ERR * SSS_FACTOR.
SENSCORR_FACTOR
The long-term detector sensitivity correction factor. SENSCORR_FACTOR = 1.0 if no detector sensitivity correction was specified.
SENSCORR_RATE
The source count rate with coincidence-loss corrections, aperture corrections, large-scale sensitivity corrections, and detector sensivity corrections applied. SENSCORR_RATE = LSS_RATE * SENSCORR_FACTOR.
SENSCORR_RATE_ERR
The one-sigma error in SENSCORR_RATE. SENSCORR_RATE_ERR = LSS_RATE_ERR * SENSCORR_FACTOR.
MAG
The magnitude of the source in the UVOT system.
MAG_ERR
The one-sigma error in MAG.
MAG_BKG
The sky magnitude in the UVOT system.
MAG_BKG_ERR
The one-sigma error in MAG_BKG
MAG_LIM
The "sigma"-sigma limiting magnitude in the UVOT system.
MAG_LIM_SIG
"sigma" for MAG_LIM.
MAG_COI_LIM
The magnitude where the count rate is the inverse of the frame time.
FLUX_AA
The flux density in erg/s/cm^2/Angstrom.
FLUX_AA_ERR
The one-sigma error in FLUX_AA.
FLUX_AA_BKG
The flux density of the sky in erg/s/cm^2/Angstrom.
FLUX_AA_BKG_ERR
The one-sigma error in FLUX_AA_BKG.
FLUX_AA_LIM
The "sigma"-sigma limiting flux density in erg/s/cm^2/Angstrom.
FLUX_AA_COI_LIM
The flux density where the count rate is the inverse of the frame time.
FLUX_HZ
The flux density in milliJansky.
FLUX_HZ_ERR
The one-sigma error in FLUX_HZ.
FLUX_HZ_BKG
The flux density of the sky in milliJansky.
FLUX_HZ_BKG_ERR
The one-sigma error in FLUX_HZ_BKG.
FLUX_HZ_LIM
The "sigma"-sigma limiting flux density in milliJansky.
FLUX_HZ_COI_LIM
The flux density where the count rate is the inverse of the frame time.
FILTER
The name of the filter.
RA
The right ascension of the source. This is the centre of the region file specified by "srcreg".
DEC
The declination of the source. This is the centre of the region file specified by "srcreg".
DETX
The X coordinate of the source in detector coordinates.
DETY
The Y coordinate of the source in detector coordinates.
SATURATED
Is the source saturated?

The errors in the computed quantities are the 1-sigma statistical errors based on binomial statistics in the count rates. The computed quantities are appended to the FITS file specified by "outfile" If "syserr=YES" then the systematic errors in the calibration are added in quadrature to the statistical errors.

PARAMETERS

image [filename]
Name of a FITS-format UVOT SKY image (filename + extension). Uvotsource acts on a single extension of a multi-extension FITS file.
srcreg [filename]
Name of an ASCII source region file. Set to NONE to compute a limiting magnitude.
bkgreg [filename]
Name of an ASCII background region file.
sigma [float]
Level of detection significance over the mean background.
(zerofile = CALDB) [string]
Zero points file. The special value CALDB indicates to read from the calibration data base.
(coinfile = CALDB) [string]
Coincidence loss correction file. The special value CALDB indicates to read from the calibration data base.
(psffile = CALDB) [string]
Radial encircled energy function (PSF) file. This is only used if CURVEOFGROWTH is specified. The special value CALDB indicates to read from the calibration data base.
(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).
(sssfile = CALDB) [string]
Small-scale sensitivity correction file which can take several forms. FITS file syntax for an HDU having UVOT SSS 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 SSS map. See also ssstype.
(ssstype = LOW) [LOW|MID|HIGH]
Small-scale sensitivity correction TYPE constraint for CALDB query.
(sensfile = CALDB) [string]
Detector sensitivity loss correction file. The special value CALDB indicates to read from the calibration data base. The special value NONE indicates to skip this correction.
(expfile = NONE) [string]
Exposure map file or NONE. If an exposure map is provided, the tool will ensure that the source and background regions are within the FOV. Output will only be generated if all pixels in the regions are exposed. It is not required that every pixel have the same exposure or does not have a NULL value.
(qualfile = NONE) [string]
Quality map file or NONE. If a quality map is provided, the tool will determine the quality flags in the source region and store them in the QUALITY column. If no quality map is provided, QUALITY will be set to NULL (-999).
(syserr = no) [boolean]
Are systematic errors in the photometric calibration to be used in the error calculations. If set to YES then systematic errors are added in quadrature to the statistical errors. If set to NO then only statistical errors are returned.
(frametime = DEFAULT) [float]
The frame time, in seconds, for the exposure. If DEFAULT is specified then "frametime" is read from the image header.
(apercorr = CURVEOFGROWTH) [string]
Aperture correction calculation algorithm. NONE or CURVEOFGROWTH. CURVEOFGROWTH assumes a point source.
(fwhmsig = -1) [real]
Percentage uncertainty in FWHM of PSF. See uvotapercorr fwhmsig parameter. This parameter is only used if apercorr=CURVEOFGROWTH.
(output = ALL) [string]
Output sections specified using a comma separated list. The options are instrumental filter magnitude (MAG), flux density in erg/s/cm^2/Angstrom (FLUX), corrected count rate in counts/s (RATE), raw count rate in counts/s (RAW), flux density in milliJanskys (FLUXJ), quality and photometry flags (FLAGS). The special value ALL indicates that all sections are to be output.
outfile [string]
Output FITS file to append results to. Uvotsource will create a new file if the specified file does not exist. The special value NONE indicates to not create an output file.
(centroid = no) [boolean]
Centroid source position? If true, the source position will be centroided based on srcreg. The resulting centroid position will be reported, written to the RA and DEC columns, and used as the center of the circular region used for coincidence loss correction. Only use centroid=yes if srcreg contains a single shape because only the first shape (recentered on the centroid) will be used to arrive at SRC_AREA and RAW_TOT_COUNTS.
(deadtimecorr = yes) [boolean]
Was the exposure time of the input already dead time corrected?
(extprec = 0) [integer]
Extra digits of precision to display in terminal output.
(subpixel = 8) [integer]
Sub-pixelling level. Each input pixel is divided along each axis by this factor. For example, with subpixel=8, each 2-dimensional input pixel is divided into 64=8*8 subpixels).
(skipbad = no) [boolean]
This flag allows outputting no result and exiting without an error for problems uncovered during processing. By default, this tool will exit with an error code if the source or background region is not compatible with the image or other photometry issues. If skipbad=yes, this tool will display a warning, not report photometry, but exit normally for those cases. skipreason is set to the reason for skipping. See also forcephot.
(skipreason = ) [output string]
(Output parameter) The reason photometry was not performed.
(expdeltaf = 0.01) [float]
Allowed variation in exposure times as a fraction of the mean exposure.
(forcephot = no) [boolean]
Proceed in spite of questionable photometry. By default, uvotsource will report issues in the input and stop processing if it detects bad quality in the source region; varying exposure in the source or background region; source or background region not entirely in image/FOV; bad SSS_FACTOR. See also skipbad.
(history = yes) [boolean]
Standard HEAdas history parameter; controls whether history keywords are written to output.
(cleanup = yes) [boolean]
Standard HEAdas cleanup parameter; controls whether temporary files are removed at the end of processing.
(clobber = no) [boolean]
Standard HEAdas clobber parameter; controls whether to overwrite pre-existing output files.
(chatter = 1) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task.

EXAMPLES

The following examples illustrate running uvotsource

1. run uvotsource prompting for all mandatory options: 

      uvotsource

2. run uvotsource specifying many arguments explicitly 

      uvotsource image=sky.img.gz+1 srcreg=src.reg bkgreg=bkg.reg sigma=5 zerofile=CALDB coinfile=CALDB psffile=CALDB lssfile=CALDB syserr=NO frametime=DEFAULT apercorr=NONE output=ALL outfile=sources.fits cleanup=YES clobber=NO chatter=1

3. run uvotsource with the curve of growth aperture corrections and include systematic errors: 

      uvotsource image=sky.img.gz+1 srcreg=src.reg bkgreg=bkg.reg sigma=5 syserr=YES apercorr=CURVEOFGROWTH outfile=sources.fits

SEE ALSO

uvotflux, uvotmaghist, uvotapercorr, uvotcoincidence, uvotlss, uvotdetect, ximage, uvotinteg

LAST MODIFIED

April 2023