NAME

USAGE

DESCRIPTION

batfftimage constructs a sky image by deconvolving the observed detector plane image with the BAT mask aperture map. This tool is used to estimate the positions and intensities of previously unknown sources on the sky. Typically this tool may be run on a detector image after background cleaning with batbkgclean, but this step is not required.

batfftimage also has a secondary usage, which is to compute the partial coding map of the sky. This map represents the fractional exposure of the sky for a given detector/aperture configuration, and is similar to the vignetting profile for imaging telescopes. To compute the partial coding map, users should the pcodemap parameter. Users must also provide an input map. Although the contents of the map are ignored, the FITS keywords are used to select the proper calibration files from CALDB. A partial coding threshold can also be specified using pcodethresh, which is a fraction between 0.0 and 1.0. Partial coding values below pcodethresh are set to zero.

If an attitude file is specified, then a celestial coordinate system will be attached to the primary WCS descriptors of the image. If no attitude file is specified, then the BAT instrument tangent plane coordinates are assigned instead.

batfftimage will operate on single or multiple images. Multiple input images may be stored as multiple extensions in a single file, or as a FITS table containing one image per row. Individual images may be selected by using the 'rows' parameter. If a table of input images is supplied, then the column specified by 'countscol' is selected. If a column is not specified, then the first 2D column is selected. Output images are always stored as FITS image extensions. Output images have extension names of BAT_IMAGE_n and BAT_PCODE_n for sky and partial coding maps, respectively.

If a background detector map is available, batfftimage can automatically subtract it. It automatically recognizes rate vs. count images, and applies an exposure correction to the background if necessary. If multiple images are operated on, then the background file must either have a single image (which is applied to all inputs); or the same number of images as the input file.

batfftimage can also calculate theoretical Poisson variance and significance maps. Note that the input file must not be cleaned for these maps to be correct.

By default, batfftimage will quantize the image into discrete intensity levels. For sky images, the quantization steps are adaptive, depending on the local noise level. Quantization usually reduces compressed image sizes significantly. The degree of quantization is governed by the 'keepbits' parameter, and quantization can be disabled. The default quantization (7 bits of noise) should be more than enough to preserve all image features.

PARAMETERS

infile [filename]

Input file name containing BAT detector plane image. If pcodemap is 'YES', then the contents of the map are ignored, but the keywords from the map file are used to select the calibration files from CALDB. Thus, using a detector enable map or a quality map is appropriate in that case. Avoid using the CFITSIO syntax to select image extensions; use the 'rows' parameter instead.

outfile [filename]

Output sky image or partial coding map file name.

attitude = "NONE" [string]

Swift attitude file name. If NONE is given, then a celestial coordinate system cannot be assigned to the image.

(aperture = "CALDB:FLUX")[filename]

BAT aperture map file name, which contains the coded mask pattern and alignment parameters. If the CALDB database is set up, then CALDB can also be specified. If several aperture types are available in the CALDB, the user can specify CALDB:apertype. Valid values of apertype are currently: FLUX or DETECTION, for apertures optimized for flux reproducibility or detection sensitivity, respectively.

(detmask = "NONE") [string]

Name of a detector quality map file. This should be an image file with the same dimensions as the focal plane map. A pixel value of 0 indicates the detector is enabled for imaging, and a non-zero value indicates disabled. A default value of NONE implies all detectors are on, except for the BAT detector gap regions.

(bkgfile = "NONE") [string]

Name of a file containing background image data to be subtracted from the input. A value of NONE indicates no subtraction should be performed.

(bkgvarmap="NONE") [string]

Optional output file name for the theoretical Poisson background fluctuation map. This map will be either the standard deviation map or the variance map depending on the value of bkgvartype. NOTE: The input map must not be cleaned for the theoretical map to be computed properly. A value of NONE indicates no fluctuation maps should be created. A value of APPEND indicates that each fluctuation map should be appended to the output file given by 'outfile'.

(bkgvartype="STDDEV") [string]

Type of output fluctuation map. Valid values are: STDDEV, for a standard deviation map; or VARIANCE, for a variance map.

(signifmap="NONE") [string]

Optional output file name for the significance map based on the theoretical Poisson variance map (see 'bkgvarmap' for restrictions). A value of NONE indicates no significance maps should be created. A value of APPEND indicates that each significance map should be appended to the output file given by 'outfile'.

(oversampx = 2) [integer]

Oversampling factor of image in X direction. Finer sampling may allow peaks which straddle pixel boundaries to be detected, but of course will result in increased compute time and disk storage.

(oversampy = 2) [integer]

Oversampling factor of image in Y direction.

(maskoffx = 0.0) [real]

Translational offset to apply to the mask along the BAT_X coordinate from its nominal design position.

(maskoffy = 0.0) [real]

Translational offset to apply to the mask along the BAT_Y coordinate from its nominal design position.

(maskoffz = 0.0) [real]

Translational offset to apply to the mask along the BAT_Z coordinate from its nominal design position.

(rebalance = YES) [boolean]

If YES, then the detector and aperture maps will be adjusted so that their additive means are zero. If NO, then, the maps will be used unadjusted. (NOTE: pcodemap implies rebalance=NO)

(pcodemap = "NO") [string]

Partial coding map output setting. The possible values are:

"NO"

No partial coding maps are output (although they may be computed internally, depending on the required corrections).

"YES"

Only the partial coding map is output.

"APPEND_ALL"

Append each partial coding map to the output.

"APPEND_LAST"

Append only the last partial coding map to the output.

Note that if the spacecraft attitude changes between sequential input images, then the coordinate system attached to the partial coding map will also change. Use APPEND_ALL in this case. If the spacecraft attitude is known to be fixed (for example, if each image is taken at the same time, but in different energy bands), then APPEND_LAST will append only one partial coding map, and thus save space.

(pcodethresh = 0.01) [real]

Minimum allowable partial coding value in the partial coding map. This is a fraction between 0.0 (no partial coding) and 1.0 (fully coded). The default of 0.01 implies that at least 1% of the detectors must be illuminated. Values below the threshold will be set to zero in the partial coding map.

(bat_z = 0) [real]

For testing with a near-field source. The position of the source in centimeters along the BAT_Z axis. A value of 0 indicates infinity.

(origin_z = 0) [real]

For ground testing with a near-field source. The position of the origin of coordinates (in cm), used for the angular measures attached to the output image.

(corrections = "default") [string]

Comma-separated list of corrections to apply to the image, or "none" if no corrections are to be applied. The possible corrections are:

default

Default corrections, which is shorthand for: "autocollim,flatfield,maskwt,ndets,pcode"

autocollim

Correct plate scale for autocollimation effect

flatfield

Apply corrections for cosine and edge projection effects

maskwt

Apply corrections for FFT technique

ndets

Normalize by number of exposed detectors

pcode

Apply partial coding corrections

(keepbits = "7") [string]

Integer number of bits of precision to keep in the output images. A value of ALL means keep all bits. A positive value indicates that 'keepbits' bits of precision should be preserved, and the other bits should be set to zero. Fewer kept bits means the output images are more compressible, at the expense of lost precision. For partial coding maps and variance maps, a straight number of bits are kept (thus preserving the same relative precision across the map). For sky maps and significance maps, 'keepbits' prescribes the number of noise bits to keep; more bits may be kept if a pixel is significantly above the noise (thus preserving the same noise quantization error across the map). NOTE: it must be possible to compute a variance map in order for most 'keepbits' operations to work. (see 'bkgvarmap' for restrictions).

(handedness = "left") [string]

The handedness of the image. For an image where north is up, a left-handed image has East=left, and a right-handed image has East=right. "left" is conventional for astronomical images.

(rows = "-") [string]

An index list of images to operate on. This is a standard comma-separated list of row ranges, starting with image number 1. A range of "-" indicates all images should be processed.

(countscol = "INDEF") [string]

If the input image is a FITS table, the column to analyze. If countscol is INDEF, then the first 2 dimensional column to be found in the table is used.

(teldef = "CALDB") [string]

BAT instrument telescope description file, which defines instrument-to-spacecraft alignments. Must be specified in order to assign celestial coordinates to the output image. A value of "NONE" disables celestial coordinates. By default the teldef file located in the HEADAS reference data area is used. If the CALDB database is set up, then CALDB can also be specified.

(time = 0) [real]

Command line override for the image time. This MET time is used to interpolate the attitude file. By default the image midpoint time is used (= (TSTART+TSTOP)/2).

(maskwtswgain = 0.03) [real]

Mask weight technique software gain correction factor. When corrections=maskwt, the image is divided by (1+maskwtswgain). This is correction is software algorithm dependent and not intended to be changed by the user.

(copyall = YES) [boolean]

If set, then batfftimage will copy any extra HDUs to the output file. If not set, then only the sky images are written. Extra extensions are any HDUs that come after the image extension(s).

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]

Controls the amount of informative text written to standard output. Setting chatter = 1 produces a basic summary of the task actions; chatter = 2 (default) additionally prints a summary of input parameters; chatter = 5 prints debugging information.

(history = YES) [boolean]

If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Reconstructs the sky image from the detector plane image focalplane.img. The aperture map, aperture.img, is in the current directory.

        batfftimage focalplane.img skyimage.img

2. Make a partial coding map for the given detector configuration given in detmask.img. The output file is the image pcodemap.img. If the detmask parameter were not given, then a default one would be used, which assumed that all detectors were enabled.

        batfftimage NONE pcodemap.img detmask=detmask.img pcodemap=YES

REFERENCES

Fast Fourier Transform routines by T. Ooura, used with permission. http://momonga.t.u-tokyo.ac.jp/~ooura/

SEE ALSO

batclean, batcelldetect

LAST MODIFIED