NAME

USAGE

DESCRIPTION

batsurvey-gti performs temporal filtering of Swift data, for the purpose of BAT survey analysis. While batsurvey-aspect performs specific attitude-related filtering, this task performs much more generic filtering, such as on count rates, etc.

This task accepts as input an observation directory. The directory should contain the complete "auxil" and "bat" subdirectories (the "xrt" and "uvot" subdirectories are ignored). It examines several housekeeping files and filter files for specific quantities that have been found useful for filtering BAT survey data.

The main filters are:

1. global - global good/bad times based on 'batglobalgti' task;
2. pointing - spacecraft indicates "10 arcminute" settling mode;
3. filter_file - filtering based on standard filter file (using the 'filtexpr' parameter);
4. ndets - a minimum number of detectors is enabled (using the 'detthresh' parameter);
5. startracker - the star tracker indicates that it is 'OK';
6. st_lossfcn - the star tracker solution error is within tolerance (defined by the 'stlossfcnthresh' parameter);
7. dph_rate - the BAT DPH count rate is within tolerances (defined by the 'rateminthresh' and 'ratemaxthresh' parameters);
8. data_flags - the BAT DPH data indicates no lost data;
9. earthconstraints - any earth pointing constraints are satisfied (defined by the 'saofiltexpr' parameter);
10. remove_midnight - any midnight-crossing DPHs are excluded;
11. occultation - the source is not occulted by the earth (the occultation parameters are defined by the source position parameters, 'ra' and 'dec', and any options to the batoccultgti);

By default all of these tests are performed. However, the 'filters' parameter can select a specific subset to be used instead.

The output of the task is a directory which contains the intermediate and final results. The final result is stored with the file name 'master.gti' in the output directory, and is the intersection ("AND") of all requested temporal filters.

PARAMETERS

indir [string]

Name of observation directory, as described above.

dphfiles [string]

Names of DPH files, either as a comma-separated list, or as an @-filename style batch file. These DPH files are used for quality filtering based on min/max rates, and quality flags.

outdir [string]

Output directory name. If the directory does not exist, then it will be created if possible. Upon success, output directory will contain the file master.gti, which is the final result. Other intermediate files may also be stored.

(totexpo = -1.0) [real] OUTPUT

Upon output, the total exposure of the listed dphfiles. If an error occurs, then -1.0 is stored.

(goodexpo = -1.0) [real] OUTPUT

Upon output, the total "good" time after applying all temporal filters. If an error occurs, then -1.0 is stored.

(ngti = -1) [int] OUTPUT

Upon output, the number of good time intervals, after applying all temporal filters. If an error occurs, then -1 is stored.

(filters = "all") [string]

A comma separated list of filters to apply, as described above, or "all" to indicate all filters should be applied.

(elimits = "14-195") [string]

Energy limits for DPI quality checking, in keV.

(ratemaxthresh = 12000) [real]

Maximum allowed count rate in a DPH, in units of counts/sec. The purpose of this filter is to exclude periods of high background.

(rateminthresh = 3000) [real]

Minimum allowed count rate in a DPH, in units of counts/sec. The purpose of this filter is to exclude anomalously low count rates.

(detthresh = 22000) [integer]

The minimum allowed number of enabled detectors, out of 32768 total detectors. The purpose of this filter is to exclude periods of time where much of the BAT array was disabled.

(ra = "NONE") [string]

For the occultation filter, the right ascension of the source in decimal degrees. A value of "NONE" disables the occulatation filter.

(dec = "NONE") [string]

For the occultation filter, the declination of the source in decimal degrees. A value of "NONE" disables the occultation filter.

(pcodethresh = 0.10) [real]

Minimum partial coding for the source, where partial coding is measured as a fraction. Ignored if the occultation filter is disabled.

(batoccultgti_opts = "") [string]

Additional options to batoccultgti. Ignored if the occultation filter is disabled.

(stlossfcnthresh = 1.0E-9) [real]

Maximum allowed star tracker "loss function." The loss function provides an indicator of the quality of the star tracker attitude solution.

(filtexpr = "NONE") [string]

Additional filtering expression based on filter file. A value of "NONE" indicates no extra temporal filtering beyond what is done by batsurvey-gti.

(saofiltexpr = "ELV > 30.0") [string]

Filter expression based on "prefilter" file.

(dphfiltexpr = "DATA_FLAGS == 0") [string]

Filter expression based on DPH files. The default specifies that only rows with all good data are to be kept.

(surveyslop = 5) [real]

Duration to add to the beginning and ending of each DPH. It is not recommended to change this setting.

(sepdph = "YES") [boolean]

If set to yes, then each DPH is assigned its own individual good time interval. If set to no, then adjoining DPHs are merged into one interval.

(maxgtigap = 5.0) [real]

If two intervals are separated by a gap less than 'maxgtigap', then they are joined into a single interval.

(mingti = 30.0) [real]

Minimum allowed good time interval size.

(mjdrefi = 51910) [int]

Swift MJDREF value (integer portion).

(mjdreff = 0.00074287037) [real]

Swift MJDREF value (fractional portion).

(clobber = YES) [boolean]

This task will always clobber files, so clobber=NO has no effect.

(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 the task results; chatter = 5 prints debugging information.

(history = YES) [boolean]

Ignored.

EXAMPLES

1. Assume we are working with observation directory called 00035025015, and wish to find good times associated with all survey DPH files in that observation. The first command creates an "@"-batch file containing the names of the DPH files, and the second command creates the good time intervals. All temporal filters are applied.

     ls 00035025015/bat/survey/*.dph > mydphfiles.txt
     batsurvey-gti indir=00035025015 dphfiles=@mydphfiles.txt \
          outdir=gti_directory filters=all

SEE ALSO

batsurvey, batglobalgti

LAST MODIFIED