Creating Good Time Intervals.

It may turn out that you want to analyze only a part of the time covered by your Observation Group (e.g., if you are analyzing a gamma ray burst). To analyze only part of the data you should define a Good Time Interval (GTI), which you will include into the analysis program as a user-defined GTI. For this purpose there is a very useful tool gti_user.

To create a GTI starting on IJD 1092.5 and lasting 1 minute (do not forget to convert it into days!) input the following command:

gti_user gti=user_gti.fits begin=1322.68 end= \ 
         length=6.944E-4 group=mygroup.fits\[1] unit="day"

This example uses an existing ISDC group mygroup.fits to get the overall TSTART and TSTOP.

This program also allows to generate several sequential GTIs in one go. The next example creates a list of 653 user GTIs of 1.5 seconds each, the start times of which are regularly spaced every 4 seconds. An overall observation start time is given at tstart=1850.0 (in IJD), and the first GTI should begin 3 seconds after this start time. The first GTI will thus cover the range [tstart+3.0 sec, tstart+ 4.5sec], the second [tstart+7.0 sec, tstart+ 8.5sec] and so on (note that tstart is given in IJD). The command is as follows:

gti_user tstart=1850.0 \ 
         unit=sec \ 
         begin=3.0 \ 
         end=4.5 \ 
         step=4.0 \ 
         repeat=653 \ 
         group=scw/027800480010.000/swg_jmx1.fits+1 \ 
         gti=user_gti.fits

The unit parameter specifies that the begin, end, and step parameters are given in seconds (default is IJD). Note that the duration of each GTI (1.5 sec in this example) is recorded in the difference end-begin. Note also that the begin and end parameters refer, in this example, to the start and end times of the first GTI in the series, given relative to the tstart value.

In that last example, you could drop the group option. In this case, no OBT would be computed (since the path to the auxiliary data necessary to compute the OBTs is in the group), and a warning message would be issued to inform you of this. But the created FITS file still contains the computed GTIs in both IJD and UTC formats, which can be used for your analysis. The full range of the possibilities of the program can be seen from the description of the parameters, given in Table 9.

Table 9: gti_user parameters.

Name	Type	Description
begin	string	Start time of a GTI. Can be given in UTC, IJD/MJD or in seconds from a start time (see tstart below). The recognition of the time format is done automatically: UTC times must be in the full UTC format YYYY-MM-DDThh:mm:ss. A purely numerical entry like ``1234.5'' will be interpreted as IJD if its value is below MJDREF=51544 and as MJD if above. It can also be the name of a file name preceded by ``@''. The format of this file is comment lines preceded by ``#'' and otherwise start and end times in IJD on the same line, separated by spaces.
end	string	End time of a GTI. See explanation for begin above for the possible time formats. The ``@file'' format is not recognized here. This parameter can be left empty if length is set instead.
length	real	Duration of a GTI in the defined time units (see unit below). If end is set this is ignored. <0: use end-begin. default: -1.0
repeat	integer	Number of repetions of defined GTI after the first. Useful, e.g., for phase-resolved analysis. The output table will contain the first GTI defined above and repeat replications shifted by step time units. default: 0
step	real	Time interval between the start of one GTI and the next repetition in the defined time unit (see unit below). Only relevant if repeat is greater than zero. = no repetitions default: -1.0
unit	string	Time unit used for begin, end, length and step. Possible values are ``day'' and ``sec''. If the former than begin and end are considered absolute values in IJD. If the latter, they are taken relative to tstart. default: ``day''
type	string	Type of defined time interval: ``good'' or ``bad''. The latter can be useful to exclude certain times. default: ``good''
tstart	real	Overall start time for GTI calculations. Relevant if a bad time interval is defined (then the time from tstart to begin is good time) or if begin is set relative. If left as a negative number, the value will be either read from the data structure addressed in group or set to a predefined fixed value default: -1.0
tstop	real	Overall end time for GTI calculations. Otherwise as tstart. use default default: -1.0
group	string	DOL of a baseline group from which some values, especially tstart and tstop can be taken. In case of ``inverse barycentered'' GTIs (see parameter bary), this must be given and contain ISDC auxiliary data, especially orbital information matching the selected times.
bary	boolean	If set to yes, the user given GTI times are taken to be valid at the Solar System Barycenter. From these, the corresponding times of observation - needed for the GTIs - are then approximately derived. The accuracy of the inversion is 1ms. default: no
ra	real	The Right Ascenscion of the source for which the barycentric corrections are calculated. Must be set to a reasonable value if bary=y. -99=INDEF default: -99.0
dec	real	The Declination of the source for which the barycentric corrections are calculated. Must be set to a reasonable value if bary=y. -99=INDEF default: -99.0
auxtype	integer	Selection flag which kind of auxiliary to use: 0 = any, i.e. use historic if possible, or snapshot or predicted 1 = use snapshot 2 = use predicted 3 = use NRT data (snapshot or predicted) 4 = use historic data default: 0
tcor	integer	Required accuracy in time correlation: 0 = accurate, i.e. return NaN if no accurate correlation possible 1 = inaccurate, i.e. extrapolate time correlation forward if needed 3 = any, i.e. extrapolate time correlation forward & backward default: 3
clobber	boolean	Shall existing output be deleted or not? default: no
chatter	integer	Verbosity level of the outputs (0 to 5 with 2 as ``normal'') default: 2