NAME

ftmgtime - merge two or more GTI FITS files

USAGE

ftmgtime ingtis outgti {AND,OR}

DESCRIPTION

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.

COMPARISON TO MGTIME TASK

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.

TREATMENT OF EMPTY GTIs

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.

TREATMENT OF GTIs FROM DIFFERENT SOURCES (MJDREF and TIMEZERO)

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.

PARAMETERS

ingtis [filename]
The file names and extensions for input GTI FITS files to be merged. Optionally the list of file names can be placed in an ASCII file, one name per line, and then the name of the file, proceeded by an "@" character may be given to the "ingtis" parameter.
outgti [filename]
The file name for merged output GTI FITS file. The output file has a null primary extension, and a single GTI table extension with EXTNAME=STDGTI.
merge [string]
The type of merge operation to perform, either AND or OR, as described above.
(instarts="START") [string]
The name of the columns for start times in the input files. Either specify one name that applies to all files, or a comma-separated list of names, one for each input.
(instops="STOP") [string]
The name of the columns for stop times in the input files. Either specify one name that applies to all files, or a comma-separated list of names, one for each input.
(outstart="START") [string]
The name of the column for start times in the output file.
(outstop="STOP") [string]
The name of the column for stop times in the output file.
(mjdref=0) [real]
The value of MJDREF to use for the output GTI. Input files will be shifted to this reference time base before processing. The output file will have keywords named MJDREFI and MJDREFF to contain the integer and fractional parts of the MJDREF value. If MJDREF=0 (which is the default), then the MJDREF values are taken from the first input file.
(indates="MJDREF") [string]
Originally used by mgtime, but ignored by ftmgtime. See the mjdref parameter.
(intimes=" ") [string]
Originally used by mgtime, but ignored by ftmgtime. See the mjdref parameter.
(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.
(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 4 or higher will produce detailed diagnostic output; chatter = 1 prints out a basic diagnostic message. The default is to produce a brief summary on output.
(history = YES) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the ftmgtime task parameters that were used to produce the output file.

EXAMPLES

This is a typical invocation:

ftmgtime file1.gti,file2.gti output.gti AND clobber=YES emptygti=APPLY
The two files are combined using "AND" logic (i.e. intersection) and the result is written to output.gti.

SEE ALSO

mgtime, maketime

LAST MODIFIED

Jul 2017