NAME

ahgtigen - create and/or merge GTI files

USAGE

ahgtigen infile outfile gtifile gtiexpr mergegti

DESCRIPTION

'ahgtigen' 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 (HK) (or similarly structured time-ordered fits file of quantities to use for filtering) file, 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 file. 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 mulitple extension in the input file(s) the output gtifile 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 may also be specified.

The second function of ahgtigen is to merge a list of GTI files (preceded by "@" if input is a list) specified by the parameter 'gtifile' using the mgtime ftool, 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 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 of the gti start times column), 'instops' (name of of the gti stop times column) may also be specified.

PARAMETERS

infile [filename]
Input file with parameters for creating the GTI, or name of text file with 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 [filename]
Input gti file, or name of text file with list of files, preceded by "@" if merging muliple input gti files. Set to NONE if creating gti file(s) from input files only.

gtiexpr [string]
User-input expression applied to input file used to create GTI. Set to NONE if merging gti only or using label file for selection only.

mergegti [string]
Merge GTI mode (OR or AND) used in combining GTI files. Required only if gtifile is not set to "NONE".

(cpkeyword = NONE) [string]
List of keywords to be copied from the first input file into the output gti file. May be set to NONE or ALL.

(upkeyword = yes) [boolean]
Update timing keywords in output file using the first input file ([yes]/no).

(leapsecfile = REFDATA) [filename]
Name of the file giving the table of leap seconds. If the parameter is set to CALDB, the file is read from the calibration database.

(instrume = NONE) [string]
Instrument used to search label file.

(selectfile = NONE) [string]
CALDB or user input label file with labels and expresssions. May be set to NONE if merging gti, or using gtiexpr parameter.

(label = NONE) [string]
Labels to read from 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 containing HK parameter times.

(outstart = START) [string]
Name of output column containing GTI start times.

(outstop = STOP) [string]
Name of output column containing GTI stop times.

(prefr = 0.) [real]
Pre-time interval factor. Must be within [0,1].

(postfr = 1.) [real]
Post-time interval factor. Must be within [0,1].

(cleanup = yes) [boolean]
Delete temporary files ([yes]/no).

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
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]
Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember), 'h' (hidden).

EXAMPLES

1. Run ahgtigen with with the mkf file CALDB 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 2, 2016