NAME

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

USAGE

uvotmaghist infile=<filename> outfile=<filename> plotfile=<filename> srcreg=<filename> bkgreg=<filename> expfile=<filename>

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 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). Use of coordinates (ra, dec, srcas, bkgas) is discouraged because it leads to no gap between the source and background regions. Please see the fhelp for uvotsource for details on the required format for the regions files.

The "timezero" parameter is used to specify the start time for the 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. uvotmaghist populates the TIME column with the elapsed seconds from timezero to the mid-point of the exposure:

	TIME = (TSTART+TSTOP)/2 - timezero

Exposures can be excluded using the "exclude" parameter. 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(s). All extensions (not the primary HDU) are analyzed, except those specifed by the <exclude> parameter. Note that multiple image files can be provided via a comma-delimited list or '@' syntax.

outfile [filename]

Output magnitude history file name. See clobber parameter.

plotfile [filename]

Output GIF plot of magnitude history or NONE.

srcreg [string]

Source region file or NONE. Use of NONE is discouraged.

bkgreg [string]

Background region file or NONE. Use of NONE is discouraged.

(expfile = NONE) [filename]

Exposure map file(s) for provided images 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.

(sssfile = CALDB) [filename]

Name of small scale sensitivity file or CALDB or NONE.

(ssstype = LOW) [LOW|MID|HIGH]

Small scale sensitivity CALDB query TYPE constraint.

(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]. Deprecated- please use srcreg/bkgreg.

(dec [real])

Source DEC [deg]. Deprecated- please use srcreg/bkgreg.

(srcas = 3) [real]

Source region radius [arcsec]. Deprecated- please use srcreg/bkgreg.

(bkgas = 10) [real]

Background region radius [arcsec]. Uses a background region which is an annulus around ra/dec from srcas to bkgas. Deprecated- please use srcreg/bkgreg.

(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.

(skipbad = no) [boolean]

Skip images for which photometry fails. See uvotsource.

(skipped = 0) [output integer]

Returns the number of HDUs not included in output.

(expdeltaf = 0.01) [float]

Allowed variation in exposure times as a fraction of the mean exposure.

(forcephot = no) [boolean]

Perform photometry even if src/bkg region exposure validation fails.

(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 specifies source and background region files:

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

2. 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

3. 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

SEE ALSO

uvotsource, uvotflux, uvotapercorr, uvotcoincidence, uvotimsum, uvotdetect

LAST MODIFIED

April 2023