NAME

USAGE

DESCRIPTION

Good Time Intervals (GTI) are defined as pairs of START and STOP times that enclose periods of time on which to base data selection. GTI tables can also contain additional columns with attributes assoicated with each START/STOP pair. In a FITS file, the additional attributes are represented in additional columns in the same GTI extension.

The gticolconv task has two conversion functions:

1. Split a GTI FITS file containing START, STOP, and ELEMENT columns into a file containing several extensions, as many as the unique values in the column ELEMENT.
2. Merge several GTI extensions into a single extension with three columns, START, STOP, and ELEMENT, where ELEMENT is populated with a unique value for each GTI extension that is present.

If the 'direction' parameter is set to SPLIT, gticolconv checks that the GTI extension in the input file contains three columns: START, STOP, and a column whose name is specified in the parameter 'column'. The script first calculates the unique values in 'column' and then creates a new GTI extension for each value found in the original input GTI file. Each unique value is written to a header keyword in the corresponding extension. The name of this keyword is specified in the input parameter 'keyname'. The value of the keyword 'keyname' in each extension is based on the input parameter 'keyform', which is a string that ends in a number of "#" characters. A common root for all values of 'keyname' is obtained by taking the part of the string preceeding the "#" characters, and the remainder of the value of 'keyname' for a given extension. The common root is formed by the script by replacing the "#" characters with the entries in 'column' corresponding to that extension. Similarly, the extension name is set by appending the 'keyname' values thus derived, to the string 'GTI'. For example, suppose 'keyname=DETNAM', 'keyform=PIX##', and that the 3rd column in the input file is called PIXEL. Then, the GTI extension formed from all rows with PIXEL=1, will have a name GTIPIX01, and that extension will have a header keyword DETNAM, whose value is PIX01. In each extension, the TSTART and TSTOP keyword values are taken from the earliest and latest times in the GTI extension respectively.

If 'direction=MERGE', gticolconv merges several GTI extensions in the input file into a single GTI extension in the output file. Each GTI extension in the input file contains two columns (START and STOP), and the merged GTI extension in the output file will contain three columns (START, STOP, and a column named by the value of the 'column' parameter). Each input GTI extension header is searched for a keyword specified by the parameter 'keyname', with a pattern specified in the parameter 'keyform'. The gticolconv task extracts a unique identifier for each input GTI extension from the value of 'keyname' by removing the part of the string of 'keyform' that occurs before any "#" characters. This identifer will, for a given input GTI extension, become an entry in the new column in the merged GTI file for each row that is associated with that GTI extension. The merged extension name in the output file is formed by appending the string value of 'column' to the string 'GTI'. The integer values in the third column are taken from the numerical portion of the input GTI extension to which the START and STOP values in a particular row belong. For example, suppose that the input extensions have 'keyname=DETNAM', 'keyform=PIX##', and 'column=PIXEL'. The input extension names should be PIX01, PIX02, etc. The output extension name will be GTIPIXEL, and the third column, called PIXEL, will have values 1, 2, 3, etc. for GTI intervals that came from the corresponding input extensions PIX01, PIX02, PIX03, etc. The output file is sorted by START, STOP, and then by 'column'. The TSTART and TSTOP keyword values in the header of the merged output file are taken from the earliest and latest times in the output GTI extension respectively.

PARAMETERS

infile [filename]

Input GTI file. If 'direction=SPLIT' and 'infile' does not explicitly specify the extension, then the extensions are searched, and the first GTI extension found is processed. If 'direction=MERGE', then 'infile' should not specify an extension.

outfile [filename]

Output GTI file.

column = PIXEL [string]

Column name. If 'direction=SPLIT', the 'column' parameter is the name of the column in the GTI extension used to split START and STOP into several extensions. If 'direction=MERGE', the parameter 'column' is used to name a new column containing the values of the elements associated with each unique input GTI extension for a each pair of values in the output START and STOP columns. In this case, the 'column' parameter is also used to name the extension, and the value of the keyword specified by the parameter 'keyname'.

direction = SPLIT [string SPLIT|MERGE]

Mode of operation. If 'direction=SPLIT', a single input GTI extension is split into two or more extensions. If 'direction=MERGE', two or more input GTI extensions are merged into a single extension.

keyname = DETNAM [string]

Keyword that is used to either select GTI extensions from an input file, or to set the name of a third column in the output file. If 'direction=MERGE', the input file is searched for all the GTI extensions that include the keyword 'keyname' and only these extensions are used. If 'direction=SPLIT', the keyword 'keyname' is assigned to the value of the parameter 'column' for each output extension.

keyform = PIX## [string]

A string that specifies a root name to use for extensions for splitting, or to interpret input extensions for merging. The format for specifying 'keyform' is a string followed by a number of "#" characters (e.g., PIXEL##, where "##" is replaced by numerical values such as 01, 02, etc...).

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(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 task parameters in HISTORY.

EXAMPLES

1. Split a single GTI extension in an input file into several GTI extensions based on values in a column called PIXEL in the input GTI extension.

   gticolconv infile="ah100041010sxs_el.gti.gz[1]" outfile=px_split.gti column=PIXEL direction=SPLIT keyname=DETNAM \
      keyform="PIX##" clobber=yes

2. Merge a file with multiple GTI extensions into a file with a single GTI extension, based on values of a keyword named DETNAM in the headers of the input GTI extensions.

   gticolconv infile=px_split.gti outfile=px_merge.gti column=PIXEL direction=MERGE keyname=DETNAM keyform="PIX##" \
      clobber=yes

SEE ALSO

LAST MODIFIED