batsurvey-gti - perform general BAT temporal filtering
batsurvey-gti indir dphfiles outdir
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:
- global - global good/bad times based on 'batglobalgti' task;
- pointing - spacecraft indicates "10 arcminute" settling mode;
- filter_file - filtering based on standard filter file (using the 'filtexpr' parameter);
- ndets - a minimum number of detectors is enabled (using the 'detthresh' parameter);
- startracker - the star tracker indicates that it is 'OK';
- st_lossfcn - the star tracker solution error is within tolerance (defined by the 'stlossfcnthresh' parameter);
- dph_rate - the BAT DPH count rate is within tolerances (defined by the 'rateminthresh' and 'ratemaxthresh' parameters);
- data_flags - the BAT DPH data indicates no lost data;
- earthconstraints - any earth pointing constraints are satisfied (defined by the 'saofiltexpr' parameter);
- remove_midnight - any midnight-crossing DPHs are excluded;
- 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.
- 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
- (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
- (filtexpr = "NONE") [string]
- Additional filtering expression based on filter file. A value of
"NONE" indicates no extra temporal filtering beyond what is done by
- (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
- (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]
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 firstname.lastname@example.org \