Given a count rate in units of counts per second, and a 1-sigma error in the same units, uvotflux will convert the rate into an instrumental magnitude (based on UVOT's own filter system) and flux densities in units of erg/s/cm^2/Angstrom. The count rate error is propagated through each calculation. Magnitudes, m, are determined from:
m = ZPT - 2.5 * log_10(C)
where C is a count rate and ZPT is a zero point appropriate to the specific filter. The zeropoints have been calibrated from standard photometry fields and assume all sources have Vega-like spectra. The zero points are stored as FITS keywords within the UVOT CALDB (see http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/swift/docs/uvot/ index.html). Flux densities, F_lam, are calculated by a applying a straightforward multiplicative factor to the count rate:
F_lam = FCF * C
FCF is also filter specific and stored as CALDB keywords. Its units are erg/cm^2/angstrom/count. The conversion factors assume a mean gamma-ray burst spectrum.
The user is required to provide the filter through which the observations were obtained (through the "filter" parameter) so that the tool knows which zero point and flux conversion factor to extract from the CALDB.
I/O is performed through a FITS table ("infile") which must be prepared by the user. Requirements are to provide a minimum of two columns with arbitrary names containing numeric values. One column contains a count rate, the other contains the associated 1-sigma error. The table may contain any number of rows or other columns, the task will perform the conversion on all data rows. The output is written to the same FITS table. Four new columns are written:
MAG -- instrumental magnitude
MAG_ERR -- 1-sigma error associated with MAG
FLUX -- flux density in units of erg/s/cm^2/Angstrom
FLUX_ERR -- 1-sigma error associated with FLUX in the same units
Each zero point comes with an associated measurement error which is also stored as a CALDB keyword, e.g. ZPEV, ZPEWHITE and ZPEUVW1. To perform construct spectral energy distributions the zero point error should be included in the calculation. However if one is interested in detecting relative structure in time series photometry the zero point error would add an unwanted level of error to each point along the curve. In such cases it is appropriate to ignore the zero point error in the magnitude and flux density calculations. Use the "syserr" argument to toggle between the two cases above.
There are prerequisites before running uvotflux. For a sensible conversion, any background or other contaminants must have been removed from the source count rate. Also the extracted count rates need to have been corrected for coincidence losses (see the ftool uvotcoincidence). Without a coincidence correction, magnitudes and fluxes will be systematically underestimated. The zero points stored in the CALDB are consistent only for a specific extraction aperture size. Count rates should either be obtained from an aperture of the same size, or corrected for aperture size using e.g. a curve-of-growth point spread function correction using e.g. uvotapercorr. The relevant aperture sizes are stored as keywords in the same CALDB product as the zero points, e.g. APTB, APTWHITE and APTUVW1. At the time of writing, all default apertures are circles with radius of 10 unbinned detector pixels (approx. 5 arcsec). Finally, the tool assumes that the deadtime correction (a small fraction due to detector readout) has already been applied to the count rates.
uvotflux may be run as a stand-a-lone ftool, but was designed as a workhorse to be used internally by UVOT's photometry tools, such as uvotsource, uvotmaghist, and uvotproduct. It will also perform on source table created by the source detection tool uvotdetect.
The following examples illustrate running uvotflux.
1. Run uvotflux and wait to be prompted for all arguments.
uvotflux
2. Run uvotflux specifying source list and rate columns on the shell command line. countrates.fits is a FITS file containing a table in HDU number 1. (note that the first extension in the file, often an empty primary extension, is designated HDU number 0, by convention). The tool will look for table columns names RATE (containing the source count rate) and RATE_ERR (the 1-sigma error attached to RATE) to propogate through the magnitude and flux density conversion.
uvotflux infile=countrates.fits+1 ratecol=RATE errcol=RATE_ERR
3. Run uvotflux specifying all arguments on the shell command line. Old or adapted zeropoint CALDB files may be pointed to with the zerofile argument and specific filter zeropoints may be requested using the filter argument.
uvotflux infile=countrates.fits+1 ratecol=RATE errcol=RATE_ERR zerofile=/caldb/data/swift/uvota/bcf/phot/swuphot20041120v105.fits filter=UVW1 syserr=NO history=YES chatter=5
uvotdetect, uvotcoincidence, uvotsource, uvotmaghist, uvotproduct, uvotapercorr
August 21, 2007