batmaskwtevt HEADAS help file

NAME

batmaskwtevt - compute mask weights for an event file

USAGE

batmaskwtevt infile attitude ra dec

DESCRIPTION

batmaskwtevt applies mask weighting, for a particular source position, to an event file. This is the first step to creating a light curve or spectrum for a source from event data.

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.

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

infile [filename]

Input event file name. This file must contain BAT events, and have at least the columns TIME, MASK_WEIGHT, DETX and DETY. The MASK_WEIGHT column is overwritten by this tool, so the file must be writeable.

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.

dec [real]

Declination of source in decimal degrees, or other source position coordinate, depending on coord_type.

(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 or DETECTION, for apertures optimized for flux reproducibility or detection sensitivity, 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.

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

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

(pcodethresh = 0.00) [real]

Minimum allowable partial coding value allowed for the source position. This is a fraction between 0.0 (no partial coding) and 1.0 (fully coded). For example, a value of 0.01 implies that at least 1% of the detectors must be illuminated. Mask weights for events whose partial coding is below the threshold will be set to zero.

(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 for all detectors in the array, regardless of detmask.

(auxfile = "NONE") [string]

Specifies an auxiliary output file which describes the position of the source in the BAT field of view as a function of time, including various ray tracing diagnostics. The columns are TIME (MET in seconds); BAT_X/Y/ZOBJ (source position in instrument coordinates in cm); IMX/Y (source tangent plane coordinates); PCODEFR (partial coding fraction); NGOODPIX (number of enabled detectors); MSKWTSQF (normalization parameter). One row is created for each ray tracing operation performed. This file is required for response matrix generation during slews.

(filtexpr = "(EVENT_FLAGS == 0) || (EVENT_FLAGS == 16)") [string]

Event filtering expression to be applied to the data. Any column filtering expression using the columns or keywords in the event file is valid (see the help for the "colfilter" task for more information). Events that fail the expression will have their mask weight set to zero. The default expression rejects calibration and multi-hit events, which are never due to cosmic sources. NOTE: users should not use spatial filters which exclude certain detectors, since batmaskwtevt will be unable to properly normalize the weights. For spatial filtering, use a detmask.

(bat_z = 0) [real]

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

(maskwtcol = "MASK_WEIGHT") [string]

Name of mask weight column.

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

(buffersize = 32768) [integer]

Size of internal event buffer for processing.

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

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

(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 event file sw00000001000bnone028.unf has its MASK_WEIGHT column overwritten.

        batmaskwtevt sw00000001000bnone028.unf 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.

 
        batmaskwtevt sw00000001000bnone028.unf 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 batmaskwtevt, 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.

        batmaskwtevt sw00000001000bnone028.unf NONE 0.348 0.112 
            coord_type=unit distance=1e7

LAST MODIFIED

Sep 2006