NAME
ahgtigen - Create and/or merge GTI files
USAGE
ahgtigen infile outfile gtifile gtiexpr mergegti
DESCRIPTION
The ahgtigen task has two primary functions. It can either create a
GTI file using an expression operating on columns stored in a FITS
file, or it can merge two or more GTI files.
The first function requires an input housekeeping file (HK, or similarly
structured time-ordered FITS file of quantities to use for filtering),
or a text file containing a list of FITS files with identical
structure and extensions, specified by the 'infile' parameter
(preceded by "@" if input is a list). In this case, the 'gtifile'
parameter should be set to NONE, and the 'mergegti' parameter is ignored.
The name of the TIME column in the input file(s) may be specified
using the 'time' parameter.
Users may specify an additional expression via the 'gtiexpr' parameter,
or use a pre-existing CALDB filtering expression stored in the label
file, specified by the 'selectfile' parameter. The label file is a FITS
file containing several expressions, each with a label that identifies
the filtering details (the screening expression, and the type of file
the expression is applied to) used to screen events and create the
GTI. A user-input label file may also be used via the 'selectfile'
parameter. A single label, or any combination of labels in the form of
a comma-separated list, may then be specified using the 'label'
parameter. In the latter case, the resulting GTI is created by
conjoining the individual expressions using AND. The user may include
an expression using the 'gtiexpr' parameter, in combination with an
expression (or expressions) from the label file. In this case the
expressions are combined using AND. If multiple files are input using
a list for 'infile', and/or there are multiple extensions in the input
file(s), the output 'gtifile' will have multiple extensions, each
corresponding to a single extension of a single file. The names of the
start and stop times in the output GTI files may be set using the
'outstart' and 'outstop' parameters.
The second function of ahgtigen is to merge a list of GTI files
(preceded by "@" if the input file contains a list), specified by the parameter
'gtifile', using the ftool mgtime according to the value of the
'mergegti' parameter (either AND or OR). In this case, the 'infile'
and 'gtiexpr' parameters may be set to NONE; otherwise the output of
the operation of the first function is merged with that of the
second function. Users may update the timing keywords (EXPOSURE,
TSTART, TSTOP, etc.) using the 'upkeyword' parameter, and other
keywords may be copied from the first input file onto the final file
using the 'cpkeyword' parameter. The mgtime parameters 'instarts'
(name of the GTI start times column) and 'instops' (name of the GTI
stop times column) may also be specified.
PARAMETERS
- infile [filename NONE|file name]
- Input file with parameters for creating the GTI, or name of text
file with a list of files preceded by "@" if creating a GTI with
multiple extensions from a list of files. Set to NONE if merging
existing GTI files only.
- outfile [filename]
- Name of output GTI file.
- gtifile = NONE [filename NONE|file name]
- Input GTI file, or name of text file with list of files preceded
by "@" if merging multiple input GTI files. Set to NONE if creating GTI
file(s) from input files only.
- gtiexpr = TIME>=0 [string]
- User-input expression applied to the input file or files used to create
GTI. Set to NONE if merging GTI only, or if using the label file for selection
only.
- mergegti = AND [string OR|AND]
- Merge GTI mode used in combining GTI files. Required
only if 'gtifile' is not set to NONE.
- (cpkeyword = NONE) [string NONE|ALL|keywords]
- List of keywords to be copied from the first input file into the
output GTI file.
- (upkeyword = yes) [boolean yes|no]
- Update timing keywords in the output file using the first input file.
- (leapsecfile = REFDATA) [string CALDB|REFDATA|file name]
- Name of the file giving the table of leap seconds.
If the parameter is set to CALDB or REFDATA, the file is read from the calibration database (CalDB) or REFDATA area, respectively.
- (telescop = NONE) [string]
- Mission name.
- (instrume = NONE) [string]
- Instrument name used to search label file.
- (selectfile = NONE) [string NONE|CALDB|file name]
- CALDB or user input label file with labels and expressions. May
be set to NONE if merging GTI, or using the 'gtiexpr' parameter.
- (label = NONE) [string]
- Labels to read from the label file specified by 'selectfile'. To input
multiple labels, use a comma-separated list.
- (outexpr) [string]
- Final expression used to create GTI. Output parameter only.
- (instarts = START) [string]
- Name of input column containing GTI start times.
- (instops = STOP) [string]
- Name of input column containing GTI stop times.
- (time = TIME) [string]
- Name of column in HK files containing time values associated with HK parameters.
- (outstart = START) [string]
- Name of output column containing GTI start times.
- (outstop = STOP) [string]
- Name of output column containing GTI stop times.
- (prefr = 0.) [double]
- Pre-time interval factor, between 0.0 and 1.0. For a group of time tags (associated with the input file
parameters) that are included in a given GTI, this
factor moves the earliest GTI start time to an earlier value. The shift in time is the product of 'prefr' and the
time interval between the earliest time tag included in the GTI and the first preceding time tag (outside the GTI).
- (postfr = 1.) [double]
- Post-time interval factor, between 0.0 and 1.0. For a group of time tags (associated with the input file
parameters) that are included in a given GTI, this
factor moves the latest GTI stop time to a later value. The shift in time is the product of 'posfr' and the
time interval between the latest time tag included in the GTI and the first following time tag (outside the GTI).
- (cleanup = yes) [boolean yes|no]
- Delete temporary files.
- (clobber = no) [boolean yes|no]
- Overwrites the existing output file if set to yes.
- (chatter = 2) [integer 0|1|2|3]
- Chatter level for output. Set to 0 to suppress output,
or to 1, 2, or 3 for increasing the chatter of the output.
- (logfile = !DEFAULT) [string DEFAULT|NONE|file name]
- Log file name. If set to DEFAULT, uses the name of the task and, if
preceded by "!", overwrites the file if it exists. If set to NONE, no
log file is created.
- (debug = no) [boolean yes|no]
- Diagnostic output is printed to the screen if set to yes.
- (history = yes) [boolean yes|no]
- Records tool parameters in HISTORY.
EXAMPLES
1. Run ahgtigen with an MKF file and a CALDB selection expression labeled by PIXELALL, creating an output GTI file.
ahgtigen infile=infile.mkf outfile=outfile_mkf.gti gtifile=NONE gtiexpr=NONE mergegti=AND selectfile=CALDB label=PIXELALL
SEE ALSO
ahscreen, mgtime
LAST MODIFIED
February 16, 2024