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 107
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 107 cm = 100 km.
batmaskwtevt sw00000001000bnone028.unf NONE 0.348 0.112
coord_type=unit distance=1e7
SEE ALSO
batmaskwtimg,
colfilter
LAST MODIFIED
Sep 2006