HEADAS help file

NAME

uvotmaghist - make magnitude history for UVOT image file

USAGE

uvotmaghist infile=<filename>

DESCRIPTION

This tool makes a history of a source magnitude versus time. Given a multiple extension FITS file, ximage is run on each extension to determine the source and background counts (rate) for a particular source.

The rates [1] are converted to magnitudes (using uvotmag) and written to a FITS table and a plot.

The user can specify source and background regions with the srcreg and bkgreg parameters, or a circular source region surrounded by an annulus can be created based on the ra, dec, srcas and bkgas parameters.

[1] The rates which are passed to uvotmag are derived as follows. For each image, determine

          SRC_AREA = source area
      TOTAL_COUNTS = source plus background counts in source region
          BKG_CNTS = background counts
          BKG_AREA = background area

           BINNING = value of BINX keyword

Using these with the tool parameters frametime and nsigma, uvotmaghist calculates

        REGION_RATIO = SRC_AREA / BKG_AREA

          TOTAL_RATE = TOTAL_COUNTS / EXPOSURE
      TOTAL_RATE_ERR = sqrt(TOTAL_COUNTS) / EXPOSURE
   BKG_RATE(arcsec2) = 4 * (BKG_COUNTS / BKG_AREA) / BINNING^2 / EXPOSURE
    BKG_RATE(source) = BKG_COUNTS * REGION_RATIO / EXPOSURE

            NET_RATE = TOTAL_RATE - BKG_RATE(source)

        NET_RATE_ERR = sqrt((TOTAL_RATE_ERR * EXPOSURE)^2
                           + REGION_RATIO^2 * BKG_COUNTS) / EXPOSURE

And the faintest detectable source is found by finding the positive root of 0 = x^2 + bx + c with b = - (NSIGMA^2) c = - (BKG_COUNTS * REGION_RATIO * NSIGMA^2) which is r = (-b + sqrt(b^2 - 4c)) / 2 RATE_LIMIT = r / EXPOSURE

PARAMETERS

infile [filename]: Input image file. All extensions (not the primary HDU) are analyzed.
outfile [filename]: Output magnitude history file name. See clobber parameter.
plotfile [filename]: Output GIF plot of magnitude history or NONE.
zerofile [filename]: Name of zero points file or CALDB.
coinfile [filename]: Name of coincidence loss correction file or CALDB.
(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.
(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.
(exclude = NONE) [string]: A comma-delimited list of HDUs to exclude from processing. Elements of the list can be HDU names or (0-based) numbers.
(frametime = 0.0110329) [real]: Frame time [s]. Used for calculating LOW_LIM_RATE and passed to uvotmag.
(nsigma = 3.0) [real]: Required significance of faintest source.
(logtime = yes) [boolean]: Whether to plot the time axis using log or linear scale.
(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

LAST MODIFIED