HEADAS help file

NAME

uvotinteg

USAGE

uvotinteg infile=<filename> regfile=<filename>

DESCRIPTION

This tool performs integrations on a FITS image over a region.

If multiple region files and/or operations are provided, iterating over the operations is nested within the iteration over the region files. For example, given regions R1 and R2 and operations O1 and O2, the order of output is O1(R1), O2(R1), O1(R2), O2(R2).

PARAMETERS

infile [filename]

Input image on which to operate. This image provides WCS information and must be a two dimensional image.

regfile [filename]

Input region file. Multiple region files can be specified using a comma-delimited list or the name of a text file containing a list of file names, one per line, preceded by an '@' character.

The operation(s) to perform. AREA yields the area of the region. SUM yields the sum of pixel values in the region. CENTROID yields the centroid of the pixel values in the region. MEAN yields the mean of pixel values in the region. FOV yields the fraction of the region which is exposed (an exposed pixel is defined as having a NULL or non-zero value; note that for FOV, the input image should be an exposure map). CLIP calculates a sigma clipped mean of pixel values in the region (see the nsigma parameter). Multiple operations can be specified using a comma-delimited list.

(subpixels = 1) [integer]

Subdivision per pixel axis (e.g., with subpixels=2, each input pixel is be divided into 4=2^2 subpixels).

(format = DEFAULT) [string]

Result format. The special value DEFAULT tries to choose a reasonable format based on operation and sysname. For AREA, the default format is 'area: %.3f'. For SUM, the default format is 'sum: %.3f'. For CENTROID/world coordinates, the default format is 'centroid: %.6f,%.6f'; otherwise 'centroid: %.3f,%.3f'. For FOV, the default format is 'fov: %.3f'. To specify a user format, use printf-like syntax.

(sysname = DEFAULT) [string]

Output system. This is used to control the coordinate system and units of the output. There are 5 special values. NONE applies no units tag. PIXEL applies the pixel tag and outputs results in image coordinates. WORLD gets the units tag from the WCS CUNITs keywords and outputs results in world coordinates. VALUE applies the value tag. DEFAULT is resolved to PIXEL if operation=AREA, VALUE if operation=SUM, or WORLD if operation=CENTROID. Any other string will be treated as the units tag.

(nullarea = false) [boolean]

Whether null pixels should be included by the AREA operation.

(nsigma = 3) [real]

N sigma for CLIP operation.

result [string]

Output parameter for result.

       OPERATION   FORMAT                  EXAMPLE RESULT
       AREA        $real [pixel]           4.519 [pixel]
       SUM         $real [value]           0.236 [value]
       CENTROID    $real,$real [system]    123.201,-43.388 [deg]
                                           213.273,321.948 [pixel]

outnull [string]

Output parameter for number of null (sub)pixels.

(chatter = 1) [enumerated integer]

Standard HEAdas chatter parameter.

EXAMPLES

The following example illustrates running uvotinteg:

      uvotinteg infile=some.img+3 regfile=src.reg operation=SUM

The following example illustrates running uvotinteg with multiple operations and sub-sampling each pixel 4x4:

      uvotinteg infile=a.img+1 regfile=src.reg operation=SUM,AREA subpixels=4

LAST MODIFIED