NAME

    gtvcut - This tool prints a summary of the Data Sub-Space keywords. 

USAGE
    
    gtvcut infile table


DESCRIPTION

gtvcut is used to view the Data Sub-Space (DSS) keywords in a given
extension, where the EVENTS extension is assumed by default. The DSS
keywords scheme was introduced for recording data selection criteria
in a systematic manner.

For FERMI data, DSS keywords store information in the FITS headers
about the selection criteria that have been applied to the data using
the gtselect tool (see the gtselect help). The DSS keywords are used
by the exposure-related tools (gtexpmap, gtrspgen) and by gtlike (see
the gtlike help) for calculating various quantities, such as the
predicted number of detected events given the source model. These
keywords must be the same for all of the filtered event files
considered in a given analysis. gtlike will check to ensure that all
of the DSS keywords are the same in all of the relevant files.

A filtering condition is expressed with a set of three or four
keywords, DSTYP1, DSUNI1, DSVAL1, and DSREF1. For example, if we
select events in a given time interval, i.e.,
TIME>start_time&&TIME<end_time, the filtering condition are stored as

DSTYP1 = 'TIME'
DSUNI1 = 's   '
DSVAL1 = 'start_time:end_time'

If you select events in a given energy range
ENERGY>start_energy&&ENERGY<end_energy the filtering conditions are
stored as

DSTYP3: ENERGY
DSUNI3: MeV
DSVAL3: start_energy:end_energy


PARAMETERS

infile [file]
Input event FITS file. This is the file containing the LAT event data.
	
table = EVENTS [string]
Data extension name. The default value is EVENTS.
 	 	 
(suppress_gtis = no) [bool]
Flag to suppress the printing of the individual GTI start and stop
times. This is a hidden parameter. The default value is "no".
 	 	 
(chatter = 2)    
This parameter fixes the output verbosity: no screen output (0),
nominal screen output (2), maximum verbosity (4). The default value is
2.

(clobber = yes) 
Overwrite or do not overwrite existing output files. This is a hidden
parameter. The default value is "yes".

(debug = no)
Activate debugging mode. This is a hidden parameter. The default value
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 = no)
Graphical user Interface (GUI) mode activated if "yes" is
specified. This is a hidden parameter. The default value is "no".

(mode = ql) 
Mode of automatic parameters. This is a hidden parameter. The default
value is "ql".


EXAMPLES

Parameters are passed following the FTOOLs model. They could be passed
answering from a prompt, as a list in a command line, or by editing
the parameter file.
 
To be prompted for gtvcut simply type in the command line: 

> gtvcut

You will be prompted for parameter values. Beware that not all
parameter are prompted. Some of them are "hidden".  If you want to
change one of the "hidden" parameter you should specify the values in
the command line. For example if you want to suppress the printing of
the individual GTI start and stop times on the command line when
running gtvcut you should type:

> gtvcut suppress_gtis=yes

An example of how to run the tool is given below: 

> gtvcut
Input FITS file[] events.fits
Extension name[EVENTS]
DSTYP1: POS(RA,DEC)
DSUNI1: deg
DSVAL1: CIRCLE(193.98,-5.82,20)

DSTYP2: TIME
DSUNI2: s
DSVAL2: TABLE
DSREF2: :GTI

GTIs:
252374400 252460800

DSTYP3: ENERGY
DSUNI3: MeV
DSVAL3: 30:200000

DSTYP4: ZENITH_ANGLE
DSUNI4: deg
DSVAL4: 0:105


In this example the gtselect tool (see the gtselect help) was applied
first selecting a time range of the events in the original event file
between 252374400 (MET sec) and 252460800 (MET sec), an energy
range between 30 MeV and 200000 MeV, and a region of 20 degrees
from a central point at coordinates RA=193.98 DEC=-5.82.

That last example could be also be run in the command line as follows:

> gtvcut infile=events.fits table=EVENTS


KNOWN BUGS

SEE ALSO

* gtselect