batmaskwtimg HEADAS help file

NAME

batmaskwtimg - compute mask weights for the entire detector BAT plane

USAGE

batmaskwtimg outfile attitude ra dec

DESCRIPTION

batmaskwtimg constructs a mask weighting map, for a particular source position, for the entire BAT detector plane. This is the first step to computing a flux or spectrum for a source from survey type or image type data. The output is an image of the detector plane with one mask weight for each detector.

Users can also compute a "forward" ray tracing map, which gives the expected counts in each detector based on a unit intensity source, accounting for various geometric optics effects. Users should use "corrections=forward,unbalanced,flatfield" and "rebalance=no" in order to simulate such a map.

Users can also request analysis for a batch of sources in a catalog, using the 'incatalog' parameter. The catalog must provide at least the source position (and optionally the name of the source and an identifying number). By default, the output will contain multiple extensions, one for each source. However, individual catalog maps can be combined into one map with the combmeth parameter. NOTE: If the input catalog is empty, then no output catalog will be created. If 'clobber=yes' is set and the input catalog is empty, then any pre-existing output file will be erased.

The actual output map type is controlled by the 'outtype' parameter. By default it is WEIGHTS, indicating to output the ray traced mask weights. If outtype=ZERO or outtype=NONZERO is chosen, then a "footprint" mask is made instead, which shows which parts of the aperture (or non-aperture) illuminates the array, regardless of the aperture pattern. This may be especially useful in combination with combmeth="MIN" or "MAX", to mask out portions of the array illuminated by particular sources.

By default, the coordinates are right ascension and declination. Users must also provide the instrument aperture and teldef files (or use CALDB). Instrument coordinates can also be used, as described in ADVANCED COORDINATE SYSTEMS below.

PLEASE NOTE: the "teldef" definition of Swift and BAT attitude has changed throughout the mission (in particular, August-September 2007). Therefore it is crucially important to specify an "infile" so that the teldef file with the appropriate date can be chosen. As of February 2021, "infile" is a required "ask" parameter.

ADVANCED COORDINATE SYSTEMS

Users may specify a source position using a coordinate system other than sky position. Depending on the value of the coord_type parameter, the user may give the cartesian or angular position of the source in instrument coordinates. When coord_type is changed from "sky" to any of the other coordinate systems, then the meaning of the ra and dec parameters changes according to the following table:

        COORD_TYPE      RA parameter        DEC parameter     Units
        ------------------------------------------------------------
        sky             Right Ascension     Declination        deg
        tanxy           Tan(theta_x)        Tan(theta_y)       none
        cartesian       BAT_X position      BAT_Y position     cm
        unit            BAT_X unit vector   BAT_Y unit vector  none
        fswlonlat       Phi (flt. software) Theta              deg
        grmclonlat      Longitude (GRMC)    Latitude           deg

The coordinate types "fswlonlat" and "grmclonlat" are coordinate systems used in the flight software and instrument simulators. The coordinate type "tanxy" gives the tangent-plane angles of the source. Where necessary the source distance and/or BAT_Z position must also be provided (in centimeters).

DISTORTION CORRECTION

Batmaskwtevt can correct for systematic non-linear centroid shifts in the BAT imaging system. It is assumed that the input position (either celestial or instrumental) is in "true" undistorted coordinates. All distortion corrections occur internally within the task. The distortion correction occurs if the 'distfile' parameter points to a correction map.

PARAMETERS

outfile [filename]

Output image file name. The mask weight map will be written to the primary extension of this file.

attitude [string]

File name of Swift attitude history, or NONE if none is used.

ra [real]

Right ascension of source in decimal degrees, or other source position coordinate, depending on coord_type. This value is ignored if incatalog is specified.

dec [real]

Declination of source in decimal degrees, or other source position coordinate, depending on coord_type. This value is ignored if incatalog is specified.

infile = "NONE" [string]

The name of an input file containing valid Swift/BAT time and instrument keywords. For example, an existing detector plane image. As of February, 2021, this is a required "ask" parameter. The time and instrument keywords are used to select the proper CALDB files, and also to determine the TSTART/TSTOP time for the output file. The keywords in infile are also cloned to the output file. If given, the 'time' parameter overrides TSTART/TSTOP in infile. By default the midpoint time is used to compute the spacecraft attitude.

(aperture = "CALDB")[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, DETECTION, or MASK_EDGES; for apertures optimized for flux reproducibility, detection sensitivity, or for the shadow of the edge of the mask, respectively.

(coord_type = "sky") [string]

Method of specifying the source coordinates. It should be one of: "sky"; "tanxy" (coordinates expressed in tangent-plane coordinates); "cartesian" (source at cartesian position in BAT coordinates); "unit" (unit vector direction in BAT coordinates); "fswlonlat" (flight software phi and theta); "grmclonlat" (source at simulator longitude and latitude). All coordinate types but the first are specified in the instrument coordinate system.

(time = 0) [real]

Time associated with the mask weighted image. When coordinates are used, it is also possible for the attitude to change as a function of time. Specify the mission elapsed time of interest with this parameter. A value of 0 (the default) indicates to use the first row of the attitude file, or the time in 'infile' if it is present. Ignored for non-sky coordinate systems.

(rebalance = YES) [boolean]

If YES, then the mask weight map will be adjusted so that its additive mean is zero. If NO, then, the map will be written unadjusted.

(bat_z = 0) [real]

Position of the source in BAT_Z coordinates, if coord_type is "cartesian" (in units of cm).

(incatalog = "NONE") [string]

Input source catalog containing source positions. The catalog should contain one row per source. A value of NONE indicates that the source coordinates should be taken from the command line.

(racol = "RA_OBJ") [string]

Column name of the first coordinate value in the input catalog, typically right ascension.

(deccol = "DEC_OBJ") [string]

Column name of the second coordinate value in the input catalog, typically declination.

(namecol = "NAME") [string]

Column name of the source name in the input catalog. This value is written to the output keyword named 'OBJECT'. If NONE is specified, then this column is ignored.

(catnumcol = "CATNUM") [string]

Column name of the source catalog number in the input catalog. This value is written to the output keyword named 'CATNUM'. If NONE is specified, then this column is ignored.

(outtype = "WEIGHTS") [string]

Type of output map (one of WEIGHTS, ZERO or NONZERO). For ZERO, the test (weight == 0) is performed on each pixel; for NONZERO, the test (weight != 0) is performed. (1=true; 0=false).

(combmeth = "NONE") [string]

Method of combining multiple maps (one of NONE, MIN, MAX or SUM). If NONE, then multiple maps are output individually. If MIN/MAX/SUM, the minimum/maximum/total value is output for each pixel.

(distance = 1.0e7) [real]

Default bat_z position if bat_z is zero (centimeters).

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

(maskthickness = INDEF) [string]

Thickness of the lead mask tiles in centimeters. Normally this will be set to INDEF, which reads the mask thickness from the aperture file. A thickness of 0 cm is permitted.

(distfile=CALDB) [string]

The 'distfile' parameter should point to a FITS file containing an MxNx2 image (or CALDB to use the default instrument correction in the calibration database). The two planes of the image are the non-linear distortion of the BAT "plate scale" as a function of position in the sky image. The values are offsets in tangent plane coordinates (IMX,IMY), and therefore unitless. The first plane of the image cube is the IMX offset, and the second plane is the IMY offset. The sense of the offset is (TRUE-APPARENT), i.e. for a measured position in tangent plane coordinates, the offset values should be *added* to arrive at the true position in tangent plane coordinates. The images are low-resolution versions of the BAT field of view in instrumental sky coordinates, and are meant to be interpolated to the desired sampling. The WCS keywords must specify the image coordinate systems.

(corrections = "default") [string]

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

default: Default corrections, which is shorthand for: "flatfield,ndets,pcode,maskwt"
flatfield: Apply corrections for cosine and edge projection effects
maskwt: Apply corrections for mask weighting technique
pcode: Apply partial coding corrections
ndets: Normalize by number of exposed detectors
subpixelate: Use slower but potentially higher fidelity algorithm
forward: Reserved for clean procedure
unbalanced: Reserved for clean procedure
nearfield: Near field corrections for ground calibration analysis only

The "pcode" and "ndets" corrections require the user to supply the detmask keyword.

(detmask = "NONE") [string]

Name of a detector quality map file. This should be an image file with the same dimensions as the detector plane map. A pixel value of 0 indicates the detector is enabled, and a non-zero value indicates disabled. A default value of NONE implies all detectors are on, except for the BAT detector gap regions. This map is only used for computing the fraction of illuminated pixels. The output mask weight map contains a value of zero for all bad quality pixels. detmask.

(subpixsize = 0.02) [real]

Size of detector subpixels used in computing mask weighting, in centimeters. Can be no larger than 0.02 cm.

(teldef = "CALDB") [string]

BAT instrument telescope description file, which defines instrument-to-spacecraft alignments. Must be specified when celestial coordinates are provided. If the CALDB database is set up, then CALDB can also be specified.

(gapval = 0.0) [real]

Value to place in image cells where detector gaps are located.

(origin_z = 0) [real]

For ground testing with a near-field source. The position of the origin of coordinates (in cm), to which the source position is referred.

(maskwtswgain = 0.04) [real]

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

(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. Computes the mask weights for a source at (RA,DEC) = (257.5500,-28.118) degrees. The output is sent to the image maskwt.img.

        batmaskwtimg maskwt.img attitude.dat 257.5500 -28.118

2. Computes mask weights for a source which is fixed in detector coordinates. The the tangent-plane coordinates are provided (tan(theta_x) and tan(theta_y)), with the source at a distance of 10⁷ cm = 100 km. Because no attitude file is needed, NONE is specified.

        batmaskwtimg maskwt.img NONE 0.348 0.112 coord_type=tanxy distance=1e7

3. Computes mask weights for a source which is fixed in detector coordinates. The X and Y components of the unit vector are given; the Z unit vector is computed implicitly by batmaskwtimg, so that the full unit vector is (0.348, 0.112, 0.931). The source is placed at a distance of 10⁷ cm = 100 km.

        batmaskwtimg maskwt.img NONE 0.348 0.112 coord_type=unit distance=1e7

LAST MODIFIED

Feb 2021