NAME

USAGE

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

LAST MODIFIED