NAME

     gtmktime - Create Good Time Intervals (GTIs) based on
     selections made using the spacecraft data file variables.


USAGE

     gtmktime scfile filter roicut evfile outfile


DESCRIPTION

     gtmktime is used to update the Good Time Intervals (GTI) extension and
     make cuts based on spacecraft parameters contained in the Pointing and
     Livetime History (spacecraft) FITS file.

     A Good Time Interval is a time range when the data can be
     considered valid.  The GTI extension contains a list of these
     GTIs for the file.  The sum of the entries in the GTI extension
     of a file corresponds to the time intervals when the data in the
     file is "good". This is based on the spacecraft aspect history
     and a user specified set of selection criteria.  In the case of
     the LAT data, the GTIs are the list of times that the LAT was
     collecting data over the selected time range and is also used to
     'cut out' times when the selected source was close to the earth
     limb. Tools use the GTIs for exposure calculations.

     The gtmktime tool reads the spacecraft data file and, based on
     specified cuts, creates a set of GTIs.  These are then combined
     (logically) with the existing GTIs in the event file, and all
     events outside this new set of GTIs are removed from the
     file. New GTIs are then written to the GTI extension of the new
     file. The gtmktime tool will be most commonly applied to event
     data; and by default the event data will be filtered according to
     the GTIs that are created. This tool may also be used to update
     GTIs in other files such as those created by gtltcube (see the
     gtltcube help).

     The cuts can be made on any field in the spacecraft data
     file. The default is to select times when the spacecraft is not
     in the Southern Atlantic Anomaly (SAA), i.e. "IN_SAA!=T". The
     cuts are made using C-style relational syntax like for example: !
     (not), && (and), || (or), != (different), >, <, >=, <=, abs(),
     cos(), sin(), etc.

     Other kinds of cuts on the data could be made using the gtselect
     tool. See the gtselect documentation for further explanation.


PARAMETERS

     scfile [filename]
          Spacecraft data file containing information such as the
          spacecraft pointing as a function of time. This file could
          be generated by gtorbsim for simulated observations (see the
          gtorbsim help for further explanation) It is normally
          obtained from the Fermi Science Support Center (FSSC)
          website and matches the time range of the requested data.

     (sctable) [string]
          Spacecraft data extension. Default is "SC_DATA".

     filter [string]
          This is the user supplied filter expression. It defines the
          cuts being made using a C-style relational syntax like for
          example: ! (not), && (and), || (or), != (different), >, <,
          >=, <=, abs(), cos(), sin(), etc. Default is "DATA_QUAL>0 &&
          LAT_CONFIG==1".

     roicut [boolean]
          Apply ROI-based zenith angle cut to exclude times where the region of
          interest is outside the field of view. If "yes", then the code will
          construct a filter string expression of the form
          angsep(RA_ZENITH,DEC_ZENITH,RA_ROI,DEC_ROI) <ZENMAX - ROI_RADIUS
          This expression will be "and"-ed it with the filter expression
          provided by the user. The zenith angle cut and acceptance cone
          information used in this expression are read from the DSS keywords in
          the EVENTS header of the input event file. These keywords are written by
          gtselect when the selections are made. If the required DSS keywords
          are missing, then a warning message is printed and no additional
          filter string is applied.

     evfile [filename]
          Input event file. This is the file containing the event data. This
          file is most commonly obtained from the FSSC website.

     (evtable) [string]
          Event table extension name. Default is "EVENTS".

     outfile [filename]
          Output event FITS file name.

     (apply_filter) [boolean]
          Flag to apply GTI filter to event data. Default is "yes".
          Set this to "no" for non-event files.

     (overwrite) [boolean]
          Build the GTIs from scratch, overwriting the existing GTI
          extension. By default (parameter set to "no"), the new GTIs will
          be merged with any existing GTIs in the file. By setting this option
          to "yes", the old GTI extension will be ignored.

     (header_obstimes) [boolean]
          Use the FITS table header values for TSTART and TSTOP.  Default is "yes".
          This option is only relevant if "overwrite=yes", otherwise it is ignored.

     (tstart) [double]
          Observation start time Mission Elapsed Time (MET) seconds. The
          reference time used for MET is midnight (0h:0m:0s) on January 1, 2001,
          in Coordinated Universal Time (UTC). The Fermi convention is that
          MJDREF=51910 (UTC)=51910.0007428703703703703 (TT); the fractional part
          of MJDREF in the TT system compensates for the use of midnight in the
          UTC system as the reference time.  MJDREF is divided into two
          keywords: MJDREFI=51910, the integer part; and
          MJDREFF=7.428703703703703D-4, the fractional part. This option is only
          relevant if "header_obstimes=no". The DATE-OBS and TSTART header
          keywords and earliest GTI start time will be modified to be consistent
          with this value. Default is "0".

     (tstop) [double]
          Observation stop time (MET seconds). This option is only relevant if
          "header_obstimes=no". The DATE-END and TSTOP header keywords and
          latest GTI start time will be modified to be consistent with this
          value. Default is "0".

     (gtifile) [filename]
          Name of temporary file for storing GTIs.

     (chatter) [integer]
          This parameter fixes the output verbosity: no screen output (0),
          nominal screen output (2), maximum verbosity (4). Default is "2".

     (clobber) [boolean]
          If true, an existing file of the same name will be overwritten.
          Default is "yes".

     (debug) [boolean]
          Activate debugging mode. Default is "no". When debug is
          "no", all exceptions that are not caught and handled by individual
          tool-specific code are caught by a top-level exception handler that
          displays information about the exception and then exits. When debug is
          "yes", such exceptions are not caught by the top level code. Instead
          the tool produces a segmentation violation, which is more useful for
          debugging. When debugging mode is enabled, the tool produces more
          verbose output describing any errors or exceptions that are
          encountered.

     (gui) [boolean]
          Graphical User Interface (GUI) mode is activated if set to "yes".
	  Default is "no".

     (mode) [string]
          Mode of automatic parameters: "h" for batch, "ql" for interactive.
          Default is "ql".


EXAMPLES

     The way that the parameters are passed follows the FTOOLs model. They
     could be passed by answering from a prompt, as a list in a command
     line, or by editing the parameter file.

     To be prompted for gtmktime simply type in the command line:

     > gtmktime

     This will prompt for parameter values. Not all parameter are prompted; some
     of them are "hidden". To
     change one of the "hidden" parameter, the user should specify the values in
     the command line or modify its mode by editing the parameter
     file. For example, if the user does not want to overwrite the
     existing output file, the user should set the parameter "clobber=no", e.g.:

     > gtmktime clobber=no

     In the following example the "_3C279_3C273_back_events_0000.fits" data
     file is used, along with the spacecraft data file called
     "spacecraft_data_file.fits". All events that fall in time ranges outside
     of the SAA are selected out:

    > gtmktime
    Spacecraft data file[] spacecraft_data_file.fits
    Filter expression[DATA_QUAL>0 && LAT_CONFIG==1]
    Apply ROI-based zenith angle cut[yes]
    Event data file[] _3C279_3C273_back_events_0000.fits
    Output event file name[] _3C279_3C273_back_filtered.fits

     The output event FITS file is called "_3C279_3C273_back_filtered.fits".

     The same example can be run in the command line in this way:

    > gtmktime scfile=spacecraft_data_file.fits \
    	   filter="DATA_QUAL>0 && LAT_CONFIG==1" \
    	   roicut=yes evfile=_3C279_3C273_back_events_0000.fits \
    	   outfile=_3C279_3C273_back_filtered.fits


SEE ALSO

     gtltcube

     gtorbsim

     gtselect