NAME

USAGE

DESCRIPTION

batoccultmap computes the fractional exposure in the BAT field of view due to occultation by the earth, moon and/or sun. The BAT field of view is large enough that any of these bodies may occult cosmic sources. Since the bodies move with time, the task computes the exposure map as a function of time and merges the results. This task is used for sky images; if you want to data selection for the visibility of a single source, use batoccultgti.

The task can be run in two modes. If occultation="any", then any portion of the image which is blocked at any time is masked in the output. If occultation="fraction", then the fractional exposure is computed (a value between 0 and 1).

The user must supply the "SAO" file created by prefilter. This file contains the positions of the earth, moon and sun as a function of time. The sizes of the earth, moon and sun are configurable.

PARAMETERS

infile [filename]

The name (and optional extension) of the input image file name.

outfile [filename]

The name of the output map file. For occultation="fraction", the map will range continuously from 0.0 to 1.0, corresponding to the partial exposure. For occultation="any", the map will be either 0.0 (occulted at some time) or 1.0 (never occulted).

saofile [filename]

The name of the "SAO" file produced by prefilter. This file should contain the columns TIME, RA, DEC, ROLL, SAT_ALT, MOON_RA, MOON_DEC, SUN_RA, SUN_DEC, EARTH_RA, EARTH_DEC.

atmdepth = 5.0 [real]

Thickness of the earth "atmosphere" in kilometers. Points within this thickness are assumed to have zero exposure.

rearth = 6378.1 [real]

The effective radius of the earth in kilometers. The default value is the mean equatorial radius (a conservative number).

rmoon = 16.0 [real]

The effective radius of the moon in arcminutes. The default value is conservatively set at 0.5 arcminutes larger than the true value.

rsun = 16.5 [real]

The effective radius of the sun in arcminutes. The default value is conservatively set at 0.5 arcminutes larger than the true value.

method = "time" [string]

Time segmentation method, used for subdividing good time intervals. For method="time", good time intervals are divided into subintervals no larger than timesegtol seconds. For method="position", good time intervals are divided so that the spacecraft and earth/moon/sun move no more than timesegtol arcminutes.

timesegtol = 0.0 [real]

Time segmentation parameter (see "method" above). Generally smaller values will provide higher fidelity, but take longer to compute. A value of zero indicates the defaults of 3 arcmin / 10 seconds should be used.

occultation [string]

Either "any" or "fraction". See "outfile" above.

constraints = "EARTH" [string]

A comma-separated list of the constraints to check (EARTH, MOON and/or SUN). Note that automatic inclusion of the MOON and SUN is not recommended, because both are comparable to the size of a BAT point source and may confuse the source detection software.

gtifile = "INFILE" [string]

Name of file containing the good time interval extension. The file is searched for the first extension matching "*GTI*". A value of "INFILE" indicates to search the input file. A value of "NONE" indicates to use the TSTART/TSTOP image header keywords.

(multfiles = "NONE") [string]

Comma-separated list of image filenames to be corrected using the calculated correction image (or "@filename.lis" to supply a list of files in filename.lis). Images are corrected IN PLACE (i.e. no back-up is made) by MULTIPLYING the original image values by the correction.

(divfiles = "NONE") [string]

Comma-separated list of image filenames to be corrected using the calculated correction image (or "@filename.lis" to supply a list of files in filename.lis). Images are corrected IN PLACE (i.e. no back-up is made) by DIVIDING the original image values by the correction.

(algorithm = "CONTOUR") [string]

Name of algorithm to use, either IMAGE or CONTOUR. The IMAGE method computes visibility for each pixel; the CONTOUR method computes the contours of each object in pixel coordinates. By virtue of the algorithms, the two results are slightly different (CONTOUR produces slightly larger occultation regions).

(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 fractional exposure map for the primary HDU of sky.img. Good time intervals are subdivided so that the spacecraft attitude/earth/moon/sun do not move more than 3 arcmin (the default).

     batoccultmap sky.img occult.img sw00111622000sao.fits.gz \
       method=position occultation=fraction

SEE ALSO

batoccultgti

LAST MODIFIED