NAME

USAGE

DESCRIPTION

batoccultgti computes the occultation good time intervals for a particular source during a BAT observation. Occultation of the earth, moon and/or sun can be considered. The BAT field of view is large enough that any of these bodies may occult cosmic sources. Note that this task is used for a single source, usually for data selection. If operating on a sky image, the batoccultmap task should be used.

Users can also check whether a source is within the X% partially coded field of view of the BAT using the "FOV" constraint. Users need to simply specify a partial coding threshold. However, users should be warned that the coordinate transformations and partial coding levels are not exact (to within a few degrees).

In addition to the partial coding check, users can also constrain the target to be in a certain position in the field of view, either in tangent plane coordinates (using the im{x,y}{min,max} parameters), or in polar coordinates (theta,phi).

Normally, 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 in this task. If the user is only performing a field of view check (i.e. not the earth, moon or sun), then it is possible to use a Swift attitude file ("sw*sat*.fits"), along with the att_type="ATT" parameter.

This task calls the FTOOLS 'maketime' and 'ftcopy', which must be present.

PARAMETERS

infile [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. The file may also be a Swift attitude file if only field of view constraints are being checked, and if att_type="ATT".

outfile [filename]

The name of the output good time interval file. This is a standard OGIP-compatible GTI file.

ra [real]

The right ascension of the target in degrees.

dec [real]

The declination of the target in degrees.

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

(constraints = "EARTH,MOON,SUN") [string]

A comma-separated list of the constraints to check (any of EARTH, MOON, SUN and FOV). "FOV" refers to a BAT field of view check (i.e. whether the source has a partial coding fraction of at least 'pcodethresh' percent).

(imxmin = "INDEF") [string]

Minimum value for the image (tangent plane) IMX coordinate for the target. INDEF indicates no selection.

(imxmax = "INDEF") [string]

Maximum value for the image (tangent plane) IMX coordinate for the target. INDEF indicates no selection.

(imymin = "INDEF") [string]

Minimum value for the image (tangent plane) IMY coordinate for the target. INDEF indicates no selection.

(imymax = "INDEF") [string]

Maximum value for the image (tangent plane) IMY coordinate for the target. INDEF indicates no selection.

(thetamin = "INDEF") [string]

Minimum value for the image THETA angle (angle of the target from the boresite). INDEF indicates no selection.

(thetamax = "INDEF") [string]

Maximum value for the image THETA angle (angle of the target from the boresite). INDEF indicates no selection.

(unocculted = "YES") [boolean]

Enter "YES" to find the unocculted intervals. In the unlikely event that you are interested in the occulted intervals, enter "NO".

(tempregionfile = "INDEF") [string]

Name of a temporary file used when performing the field of view (FOV) check. A region file is written out containing the shape of the BAT field of view in tangent plane coordinates at the desired partial coding threshold. A value of NONE indicates that no file is required. A value of INDEF indicates that a scratch file should automatically be created and deleted as needed for this purpose. If an explicit file name is given, the user is responsible for deleting the file.

(tempexprfile = "NONE") [string]

Name of a temporary file used for making intermediate coordinate transformation calculations for the field of view (FOV) check. A value of NONE indicates that no file is required. A value of INDEF indicates that a scratch file should automatically be created and deleted as needed for this purpose. If an explicit file name is given, the user is responsible for deleting the file.

(pcodethresh = 0.50) [real]

Partial coding threshold, as a fraction of unity. If the FOV check is enabled, then times are considered good only if the target is partially coded at the level of pcodethresh or higher.

(calcfile = "NONE") [string]

Name of file to be used for intermediate calculations in the FOV check. Various columns, containing coordinate transformation and BAT tangent plane coordinates, are appended to the SAO file. A value of "NONE" indicates that an intermediate file should not be created.

(att_type = "SAO") [string]

Set to "SAO" if the input file is a prefilter (SAO) file, or "ATT" if the input file is a Swift attitude file.

(prefr = 0.5) [real]

Pre-Time Interval factor passed to the 'maketime' task.

(postfr = 0.5) [real]

Post-Time Interval factor passed to the 'maketime' task.

(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 a good time interval for the Crab.

     batoccultgti sw00111622000sao.fits.gz crab.gti 83.6332 22.0145 

SEE ALSO

batoccultmap, maketime

LAST MODIFIED