batfftimage - make sky image from detector plane image by FFT deconvolution
batfftimage infile outfile
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
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.
- 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
- (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:
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.
- No partial coding maps are output (although they may be
computed internally, depending on the required corrections).
- Only the partial coding map is output.
- Append each partial coding map to the output.
- Append only the last partial coding map to the output.
- (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
- Default corrections, which is shorthand for: "autocollim,flatfield,maskwt,ndets,pcode"
- Correct plate scale for autocollimation effect
- Apply corrections for cosine and edge projection effects
- Apply corrections for FFT technique
- Normalize by number of exposed detectors
- 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
1. Reconstructs the sky image from the detector plane image
focalplane.img. The aperture map, aperture.img, is in the current
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
Fast Fourier Transform routines by T. Ooura, used with