This task performs filtering and normalization of a Good Time Interval (GTI) file. A GTI file contains a list of "good times" used for data analysis. It is a list of entries, giving the start and stop time of each interval. This task performs various screening and filtering options on a GTI.
The situations where ftadjustgti might be used include dealing with occasionally noisy data, or to manipulate a GTI in a known way. Consider some examples:
This task accepts as input a single GTI file and creates a single output GTI file. The basic column structure and keywords of the input are not changed. However, if additional columns are present in the input, they will be filled with default/null values upon output. If requested (copyall=YES), the other extensions of the input file are copied to the output.
This task performs the following operations, in order. All, or some, of these operations are selectable. With the exception of the initial GTI normalization, which is always performed, you can opt to perform, zero or more of these operations.
Performing no operations, which is actually the default, will cause ftadjustgti to read the input GTI file, normalize it, and write it to the output file. Any other operations can be enabled by setting that option to a non-zero value, as described below.
Note that all input times are specified in the same units as the GTI file. For example, if the GTI file start and stop columns are in seconds, than all input values for time parameters are in seconds as well. In all the examples below, a time unit of seconds will be assumed, although the task will work equally well if all units are specified in days, years, etc.
All of the above operations are based on simple enlarge and/or shrink operations on a GTI.
For example, if preenlarge=10, the start value of each GTI entry is enlarged by 10 seconds (subtract 10 seconds from start). If this causes one GTI entry to overlap with its neighbor, then these entries will be merged into a single GTI. This is what gives ftadjustgti its true power: the ability to "heal" small gaps.
It is also possible to specify preenlarge=-10, which will cause the start of each GTI entry to shrink by 10 seconds (add 10 seconds to start).
A similar logic applies to postenlarge. If postenlarge=10, the stop of each GTI entry will be enlarged by 10 seconds (add 10 seconds to stop time); if postenlarge=-10, the stop of each GTI entry will shrink by 10 seconds (subtract 10 seconds from stop time).
The erode/dilate options are slightly more sophisticated, but provide a more powerful way to filter or smooth GTIs in a single pass. If erodedilate is non-zero, then every GTI will shrink (erode) by 10 seconds on both the start and stop ends (total of 20 seconds), and then enlarge (dilate) by 10 seconds on both start and stop. At first, this non-sensical operation seems redundant. Why shrink and then grow GTIs by the same amount? The answer is that a "normalization" operation also occurs in between the erode and dilate operations. Entries that become "empty" are removed. Thus, this is not a completely redundant operation.
The erodedilate option will tend to remove small GTIs even if they are neighboring large GTIs. Use this operation if you expect that smaller GTIs are always noise.
The dilateerode option will tend to combine multiple smaller GTIs into a single, larger GTI. Use this operations if you expect that smaller gaps between GTIs are always noise, or if you want to group multiple smaller GTIs into a larger encompassing GTI.
As the next two steps, ftadjustgti can check for "outlier" GTIs more explicitly. The maxgap option will search for GTI entries that have gaps between of less than maxgap; those gaps will be removed to make a continuous GTI. The mingti option is the last check performed: any GTI entries smaller than mingti will be removed (note that similar results can be achieved by using erodedilate).
In the next and final step, ftadjustgti can invert the sense of a GTI. This effectively changes the sense of a "GTI" (Good Time Interval) into a "BTI" (Bad Time Interval). Since an inverted GTI can be unbounded, the user has the capability to specify an overriding start and stop time using the tstart and tstop parameters. If any of the BTI samples are outside the tstart/tstop boundaries, than the sampled values are used instead.
The treatment of "empty" GTIs can be handled in two different ways. Here, "empty" GTIs are GTI extensions with no rows.
The emptygti parameter governs what happens if no good time intervals are selected by maketime. By default, when no good times are found and emptygti=IGNORE, a GTI extension is created with no rows. Although this appears to be correct behavior, some downstream software tasks may mistakenly misinterpret an "empty" GTI as "all good" rather than "all bad." This is in fact the opposite of desired behavior. To prevent this unreliable behavior, set emptygti=APPLY (in analogy to ftmgtime's emptygti=APPLY parameter). With this setting, a one-row GTI is created with no true good time. This type of output will be understood by most downstream software with least ambiguity. For compatibility with older missions and previous versions of maketime, emptygti=IGNORE. However for more reliable performance, emptygti=APPLY should be used for new development.
Normalize the input GTI and write to output file.
ftadjustgti infile.gti outfile.gti
Remove GTI entries smaller than 10 seconds.
ftadjustgti infile.gti outfile.gti mingti=10
Remove gaps between GTI entries smaller than 50 seconds
ftadjustgti infile.gti outfile.gti maxgap=50
Perform the dilate-then-erode operation with a value of 60 seconds, which will tend to combine GTIs separated by gaps smaller than 60 seconds.
ftadjustgti infile.gti outfile.gti dilateerode=60
Shrink GTIs by 20 seconds at the start
ftadjustgti infile.gti outfile.gti preenlarge=-20