This task merges any number of input Good Time Interval (GTI) files, using either of two modes:
The input files are combined as specified, and the resulting GTI is written to a standard output FITS file. This task is used for combining GTIs useful for screening by time. As described below, ftmgtime is similar to, but different than, the original task mgtime. ftmgtime is designed to have improved behavior for special cases that might appear in automated batch processing.
This task is similar to the 'mgtime' task, which also merges GTI files, but is "better" in a number of ways. Better also means different, which means that some care must be taken before simply substituting ftmgtime in place of mgtime. However, some effort has been made to make the calling syntax compatible with mgtime to ease the transition. ftmgtime handles special cases in a more systematic way which allows it to be used in automated batch processing with less special case wrapper code. The original task 'mgtime' is not obsolete; it can still be used as it always has been used.
Here are the main differences and similarities between mgtime and ftmgtime.
Most importantly perhaps, the treatment of "empty" GTIs is different between mgtime, and ftmgtime. See below for more information.
The command line parameters of mgtime can be used with ftmgtime as well (although some are ignored).
The underlying engines for both tasks are different code-bases that have a common history.
There is no limit to the number of input GTIs allowed by ftmgtime, while mgtime has an upper limit of 400 inputs. You should use the @filename.lis notation to list large numbers of files reliably.
It is also possible to specify only one single input file, and ftmgtime will process it. A single input file is equivalent to the "identity" operation, and the single input is copied to the output. This allows the user to enter any number of GTI files (one or more) and reliably merge them without needing special case code (versus mgtime which requires at least two inputs).
The 'indates' and 'intimes' keyword parameters are allowed for command line compatibility with mgtime, but are ignored. ftmgtime uses the first input file as the source of most timing related keywords. The mjdref keyword parameter can be used to select a desired value of the MJDREF FITS keyword.
The output file will have the MJDREFI and MJDREFF keywords for maximum time precision. Any existing MJDREF keywords (without the "I" or "F") will be removed so that MJDREFI/F are the only keywords present in the output.
As mentioned above, the treatment of "empty" GTIs is different between the two tasks. Here, "empty" GTIs are GTI extensions with no rows. In the past, the treatment of these files is ambiguous as some tasks interpret this as meaning all times are good, and others interpreting as all times are bad. This ambiguous treatment has lead to numerous bugs, errors and special cases in HEASoft software.
ftmgtime has two ways to treat empty GTIs.
If the keyword parameter emptygti=APPLY, which is the default, then empty input GTIs are considered as all times are bad. This setting will produce the most reliable results for batch processing. WARNING: this default behavior is different than the default behavior of mgtime, so users should take care for what they intend before using this setting.
If the keyword parameter emptygti=IGNORE, the behavior is similar to mgtime. Any input files which are empty are simply ignored (passed over) and do not enter into the GTI computation. This is mostly equivalent to treating an empty GTI as all times are "good." WARNING: this can lead to unexpected results.
There is also the question of what happens if a resulting GTI is empty. This would occur if the inputs are empty and emptygti=APPLY, or if an AND operation results in no intersecting good times. In those cases, the output GTI will have a single tabular row, which has no good time. (i.e. the row as START=STOP.) This will indicate to downstream software the true intention of an empty GTI and avoid the ambiguity of a truly empty GTI table. This output occurs regardless of the emptygti parameter setting.
GTIs may come from different sources with different reference times. The reference times are captured in the standard MJDREF and TIMEZERO keywords. Sources wih different references should have different values of the keywords.
ftmgtime will automatically apply a shift to put input times on a common time scale using each of the MJDREF and TIMEZERO keywords. The output reference time is specified using the mjdref keyword parameter. If the mjdref parameter is set to 0, then the MJDREF keywords of the first input file are used to set the reference time for calculations.
WARNING: the behavior of the task is undefined if some files have MJDREF keywords and others do not.
This is a typical invocation:
ftmgtime file1.gti,file2.gti output.gti AND clobber=YES emptygti=APPLYThe two files are combined using "AND" logic (i.e. intersection) and the result is written to output.gti.