HEADAS help file

NAME

uvotmaghist - make a light curve from the exposures in a UVOT image file

USAGE

uvotmaghist infile=<filename> outfile=<filename> plotfile=<filename> zerofile=<filename> coinfile=<filename> psffile=<filename> syserr=<boolean> timezero=<float>: ra=<float> dec=<float> srcas=<float> bkgas=<float> srcreg=<filename> bkgreg=<filename> exclude=<string> frametime=<float> nsigma=<float> apercorr=<string> logtime=<boolean> plotcol=<string> clobber=<boolean> cleanup=<boolean> history=<boolean> chatter=<integer>

DESCRIPTION

This tool makes a history of one of the quantities computed by uvotmaghist (usually magnitude) for a source versus time. It does this by doing photometry on a source in every exposure in the input UVOT SKY image file (sw*.img). This software calls uvotsource to do photometry. The output quantites are the same as for uvotsource. An optional plot is produced that shows the light curve of the source. The "plotcol" parameter controls which output column to plot as a function of time. See the fhelp for uvotsource for details on how the photometry is done, on how to use the photometry control keywords, and on the output information.

The "timezero" parameter is used to specify the start time for output time column. If it is set to "0" then the TRIGTIME keyword, if present in the input FITS file header, is used as the start time. This option is intended to produce light curves relative to the BAT trigger time of a gamma-ray burst. "Timezero" is given in mission elapsed time (MET). Use swifttime to convert times into MET. The "logtime" keyword controls whether or not the time axis of the plot is in log or linear units.

The source and background regions can be specified as standard ftools or ds9 region files (via the "srcreg" and "bkgreg" parameters), or as coordinates (in decimal degrees). Please see the fhelp for uvotsource for details on the required format for the regions files.

Exposures can be excluded using the "exclude" keyword. See uvotimsum for details. The errors in the magnitudes and the flux densities are the statistical errors based on Poisson errors in the count rates. Systematic errors due to uncertainties in the photometric zero points and flux conversion factors can be included by setting "syserr" to "yes".

PARAMETERS

infile [filename]: Input SKY image file. All extensions (not the primary HDU) are analyzed, except those specifed by the <exclude> keyword.
outfile [filename]: Output magnitude history file name. See clobber parameter.
plotfile [filename]: Output GIF plot of magnitude history or NONE.
(zerofile = CALDB) [filename]: Name of zero points file or CALDB.
(coinfile = CALDB) [filename]: Name of coincidence loss correction file or CALDB.
(psffile = CALDB) [filename]: Name of point-spread function file or CALDB.
(lssfile = CALDB) [filename]: Name of large scale sensitivity file or CALDB or NONE.
(sensfile = CALDB) [filename]: Name of detector sensitivity loss file or CALDB or NONE.
(syserr = NO) [boolean]: Set to YES to include systematic errors in the output error calculations.
(timezero = 0) [real]: The time at the left edge of the horizontal (time) axis in the magnitude history plot. The special value 0 results in the time being determined based on the input. If the input contains the TRIGTIME keyword, its value is used, otherwise, the earliest start time of the processed images is used.
(ra [real]): Source RA [deg]. See the examples for specifying regions.
(dec [real]): Source DEC [deg]. See the examples for specifying regions.
(srcas = 3) [real]: Source region radius [arcsec]. See the examples for specifying regions.
(bkgas = 3) [real]: Background region radius [arcsec]. See the examples for specifying regions.
(srcreg = NONE) [string]: Source region file or NONE. See the examples for specifying regions.
(bkgreg = NONE) [string]: Background region file or NONE. See the examples for specifying regions.
(exclude = DEFAULT) [string]: A comma-delimited list of HDUs to exclude from processing. Elements of the list can be HDU names, (0-based) numbers, or special values. The special value ASPCORR:NONE indicates to exclude HDUs without aspect corrections. The special value DUPEXPID indicates to include only one of duplicate exposures (which are due to IMAGE and EVENT mode). The special value OBS_MODE:<value> indicates to exclude exposures where the value of the OBS_MODE keyword is <value>. The default value DEFAULT is equivalent to ASPCORR:NONE,DUPEXPID,OBS_MODE:SETTLING.
(frametime = DEFAULT) [real]: Frame time [s] or DEFAULT. This parameter is passed to uvotsource. The special value DEFAULT results in the frametime being taken from the FRAMTIME keyword.
(nsigma = 3.0) [real]: Required significance of faintest source.
(apercorr = CURVEOFGROWTH) [NONE|CURVEOFGROWTH]: This is the aperture correction method that is applied to the count rates. The options are NONE, which causes no aperture corrections to be applied, or CURVEOFGROWTH, which uses the curve of growth method described in the fhelp for uvotapercorr to be used. The CURVEOFGROWTH method assumes a point source.
(logtime = yes) [boolean]: Whether to plot the time axis using log or linear scale.
(plotcol = MAG) [string]: Output column to plot as a function of time.
(centroid = no) [boolean]: Perform centroiding? See uvotsource centroid parameter.
(fwhmsig = -1) [real]: Percentage uncertainty in FWHM of PSF. See uvotapercorr fwhmsig parameter. This parameter is only used if apercorr=CURVEOFGROWTH.
(subpixel = 8) [integer]: Sub-pixelling level. See uvotsource.
(cleanup = yes) [boolean]: Standard HEAdas cleanup parameter; controls whether temporary files are removed at the end of processing.
(clobber = no) [boolean]: Overwrite output file if it exists?
(cleanup = yes) [boolean]: Remove temporary files?
(history = yes) [boolean]: Write parameter history?
(chatter = 1) [enumerated integer]: Standard HEAdas chatter parameter.

EXAMPLES

1. This example illustrates running uvotmaghist specifying the input and output file names and source position on the command line.

      uvotmaghist infile=images.fits outfile=maghist.fits ra=286.4 dec=-8.16

2. This example specifies source and background region files:

      uvotmaghist infile=images.fits srcreg=source.reg bkgreg=back.reg

3. This example specifies how to include systematic errors and exclude extension 3.

      uvotmaghist infile=images.fits srcreg=source.reg bkgreg=back.reg syserr=YES exclude=3

4. This example specifies how to produce a plot with a linear time axis starting at 2007-06-14T12:34:56. Use swifttime to determine the MET.

      uvotmaghist infile=images.fits plotfile=lightcurve.gif srcreg=source.reg bkgreg=back.reg timezero=203517297 logtime=NO

LAST MODIFIED