NAME gtbkg - Creates a background spectrum file (PHA1).

USAGE
 
         gtbkg phafile outfile scfile expcube expmap irfs srcmdl target

DESCRIPTION

The gtbkg tool produces a background spectrum file (PHA1).

The tool uses as input several files that are created with other
tools: The input spectrum file (PHA1) should be created by gtbin; the
live-time file, by gtltcube; the exposure map is the same as the one
created for the unbinned likelihood analysis and should be created by
gtexpmap; the source xml file is the same as the one used for the
gtlike tool and can be created with ModelEditor (see the modeleditor
help).

The spectrum file (PHA1 format) that is created contains total counts
based on a gtlike source model and covers the same energy bands
and region-of-interest (see the gtlike documentation for details) as
the input PHA1 file. The model will typically contain interstellar and
extragalactic diffuse components as well as nearby point sources.


PARAMETERS

phafile [file]
Name of input spectrum file (PHA1). This file should be produced with
gtbin (option PHA1). See the gtbin help for further information.
 	 	 
outfile [file]
Output spectrum file (PHA1 format).
 	 	 
scfile [file]
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 gtorbsim help for further
explanation) or more commonly it can be obtained from the FSSC
website.
 
(sctable = SC_DATA) [string]
Spacecraft data extension. This is a hidden parameter. The default
value is: SC_DATA.

expcube [file]
FITS file containing live-time as a function of sky position and
off-axis angle. This file can be generated by gtltcube or obtained
from the FSSC website. See the gtltcube help for further explanation.

expmap [file]
Exposure map file created using gtexpmap. This is an exposure map of
the form that is used with unbinned likelihood analysis and is used in
this context but Xspec analyses of LAT data presently only support
acceptance cone based extraction regions. Do not use an exposure map
that is appropriate for binned analysis. See the gtexpmap help for
further explanation.
 	 	 
irfs [string]
Instrument response functions. The instrument response (PSF, effective
area, energy resolution) is currently a function of energy,
inclination angle (the angle between the source and the LAT normal)
and photon category. Since the LAT will usually survey the sky, a
source will be observed at different inclination angles. Each count
will therefore be characterized by a different instrument response
function (IRF).

srcmdl [file]
XML file containing the source model definitions. The source model can
be generated by the "ModelEditor" utility or by following source model
templates. See the "ModelEditor" help for further explanation.
	 	 
target [string]
The name of the target source as it appears in the source model
file. Its contribution will be excluded from the background
calculation. If there are no sources to exclude, this field may be
left blank or set to "none".
 	 	 
(chatter = 2)  [integer]
This parameter fixes the output verbosity: no screen output (0),
nominal screen output (2), maximum verbosity (4). The default value is
2.

(clobber = yes) 
If true, an existing file of the same name will be overwritten. This
is a hidden parameter. The default value is: "yes".

(debug = no)   
Activate debugging mode. 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. The default value is "no".

(mode = ql)
Mode of automatic parameters. The default value is "ql". 

        
EXAMPLES

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

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

>gtbkg

This will prompt for parameter values. Beware that not all parameters
are prompted: some of the parameters are "hidden".  in order to change
one of the "hidden" parameter, specify its value in the command
line. For example to prevent overwriting an existing output file, type
in the command line:
 
>gtbgk clobber=no  
 
An example of how to run the tool is given below:


> gtbkg 
pha file [] : 3C279_3C273_back_filtered_pha1.fits
output file [] : pha1.fits
Spacecraft file [] : spacecraft_data_file.fits
Exposure hypercube file [] : expCube.fits
Exposure file [none] : expMap.fits
Response functions to use [] : P6_V3_DIFFUSE
Source model file [] : src_model.xml
Target source name (excluded from background estimate) [none] :3C279
Excluding source 3C279 from background model.

The file 3C279_3C273_back_filtered_pha1.fits was created using gtbin
(option PHA1) from an original event file. The expMap.fits and the
expCube.fits file were created with gtexpmap and gtltcube
respectively. 3C279 is the source excluded from the background
model. The name "3C279" is the same as the one in the source model
file.
 
To run the same example in the command line type:

>gtbkg phafile=3C279_3C273_back_filtered_pha1.fits outfile=pha1.fits
 scfile=spacecraft_data_file.fits expcube=expCube.fits expmap=expMap.fits
 irfs=P6_V3_DIFFUSE srcmdl=src_model.xml target=3C279
Excluding source 3C279 from background model.

KNOWN BUGS


SEE ALSO


* gtbin

* gtrspgen

* gtltcube

* gtexpmap

* gtlike

* ModelEditor