NAME

mkgti - MaKe GTI file from boolean HK parameter expression

SYNOPSIS

mkgti [hkgfile=] <hkg_filename> [parameter=value ...]

DESCRIPTION

mkgti creates a Good Time Interval (GTI) table from the time tag columns (TIME) in a SAX/LECS or SAX/MECS HK file of type hkg. The time intervals are selected on the basis of three boolean expressions formed from a list of "standard" interval definitions for various HK parameters. Those are represented as the respective Bintable column names in the second (HKP+GAIN), third (EPHEMERIS), and fourth (ASPECT) extension of hkg HK files (see sections 4.3, 4.4, 4.5, and 6.2, or A.8-10 in [1] for a complete list of allowed column names).

In order to actually construct the GTI file, mkgti uses the standard FTOOLS maketime and mgtime in the following manner: For each of the three HK file extensions 2, 3, and 4, maketime is invoked on the respective Bintable extension in the input HK file with a suitably constructed boolean expression. This whole process shall create to up to three different individual GTI files which will subsequently be merged with mgtime. The resulting GTI file can then be used for event selection purposes, either with the FTOOL fltime or by reading it into Xselect after an event list file has been defined.

The standard HK parameter interval definitions are obtained from one of the following sources:



1. A calibration file of type CCNM001=HKPARMINT in the SAX/LECS or SAX/MECS calibration database
2. An alternative calibration file of type CCNM001=HKPARMINT specified on the command line
3. A set of hard-coded default settings.

Which of these methods is actually being used can be controlled via the command line parameter hkparmfile - default is to use method 1., i.e., the needed HK parameter interval definitions are attempted to obtain from a calibration file in the calibration database.

The required boolean expressions for the different invocations of maketime are automatically constructed from the corresponding HK parameter interval definitions. In addition, each resulting expression can be supplemented or completely replaced by boolean expressions provided via the command line. This is controlled through the parameters stdhkints and expr{1,2,3}.

PARAMETERS

The following command line parameters are recognized by the program:

hkgfile = "" [string: name of existing HK file of type hkg]

This must be the name of an existing HK file of type hkg whose contents shall be used to derive the GTIs. Apart from some basic checks the file itself is not used by mkgti but just passed to maketime which actually create the GTI file on the basis of a supplied boolean expression. If the specified file does not exist or is found not to be of type SAX/{LECS|MECS}/HKG a warning message will be issued and execution shall be aborted.



expr{1,2,3} = "" [string: valid boolean HK parameter expression]

Each of these strings, i.e., expr1, expr2, and expr3 is optional and can be omitted, otherwise it must contain a valid boolean expression (see description of syntax for boolean expressions for maketime) involving HK parameter names from the second, third, and fourth Bintable extension in the file hkgfile, respectively. In other words, expr1 refers to the second (EXTNAME=HKP+GAIN), expr2 to the third (EXTNAME=EPHEMERIS), and expr3 to the fourth (EXTNAME=ASPECT) Bintable extension in the HK file. Any specified expression will not be checked for syntactical correctness, but is just passed as the value of the expr parameter of maketime as is. If the usage of standard HK parameter intervals is in effect (see command line parameter stdhkints) any specified expression expr{1,2,3} will supplement the expression resulting from the standard HK parameter intervals and this combined expression is then passed to maketime. For example, the expr argument for the maketime invocation for creating the GTI file for extension 2 (HKP+GAIN) will have the form:

    <expr_from_standard_HK_intervals> && ( <expr1> )

In case of conflicting parameter intervals in the two sub-expressions, the interval specifications in expr{1,2,3} takes precedence over the standard ones. This means that the parameter intervals in questions will simply be removed from the standard expression before the combined total boolean expression is formed. As an example, if the standard HK intervals yield an expression

    PARM1 >= 1 && PARM1 <= 2 && PARM2 >= 10

and the conflicting expression

    PARM1 == 3

was given on the command line, the resulting boolean expression for maketime will be:

    PARM2 >= 10 && ( PARM1 == 3)

Each specified expression must comply the syntax rules for boolean expressions of the FTOOLS task maketime. In case these rules are breached, the expression parser of maketime will fail to interpret the expression and execution will be aborted.

NOTE: Due to a limitation of maketime's expression parser the decimal point in floating point numbers MUST always be followed by at least one digit, e.g., the number "one" must be specified as "1.0". The "popular" form "1." is not accepted by maketime.



stdhkints = yes [boolean: yes|no]

This boolean switch determines whether or not a standard boolean HK parameter expression for each Bintable extension should be generated based on corresponding interval specifications from either a calibration file or hard-coded d/f values (see command line parameter hkparmfile). In case stdhkints is set to "no", the entire boolean expressions for constructing the GTIs must be provided through the command line parameters expr{1,2,3}.



hkparmfile = "CALDB" [string: name of existing cal.-file of type HKPARMINT]

If standard HK parameter intervals shall be considered (stdhkints = "yes") mkgti will need to extract the necessary information from a calibration file of type HKPARMINT. The name of this file can either be obtained through interrogation of an installed SAX/LECS or SAX/MECS calibration database, or, if such a database is not installed or accessible, by specifying it explicitly. The former method is used by mkgti if hkparmfile is assigned the special value "CALDB". Otherwise, this parameter is supposed to contain the full pathname of the required calibration file. If hkparmfile is empty, or the interrogation of the calibration database failed, or a specified file does not exist or is not found to be of type SAX/{LECS,MECS}/HKPARMINT, and the parameter stdhkints is set to "yes", hard-coded default values for the standard HK parameter intervals will be used.
For information on the struture and contents of the HKPARMINT calibration file, please consult Sec. 33 in [2].



verbosity = 2 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Verbosity level 3 results into detailed diagnostic messages. Default is level 2.



help = no [boolean: yes|no]

A boolean flag which, when set to yes triggers that the program prints out a brief on-screen description of all available command line parameters together with the current program version number and exits successfully.

EXAMPLES

1. Create a GTI file from the contents of the HK file kv171_hkg.fits using standard HK parameter interval specifications. Those come from a calibration file of type HKPARMINT in the calibration database. The interval specification for the HK parameter CELL_TEMPERATURE is given explicitly and shall override any corresponding definition contained in the calibration file:

   	mkgti kv171_hkg.fits expr1="CELL_TEMPERATURE>=19.0 &&
                                   CELL_TEMPERATURE <=21.0"
   

2. Create a GTI file from the contents of the HK file kv171_hkg.fits using standard HK parameter interval specifications. The calibration database shall not be interrogated for a file of type HKPARMINT but hard-coded default values shall be used for the standard HK parameter intervals:

   	mkgti kv171_hkg.fits caldb=no
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010
2. The SAX LECS Ground Calibration,
   G. Vacanti, Doc. SAX/LEDA/0015

BUGS

• The standard FTOOL maketime is utilized to actually construct the GTI file from boolean expressions - this is slow and should be replaced by something faster in the (not so distant) future.

SEE ALSO

maketime, mgtime, fltime, Xselect, lecspipe