NAME 

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


USAGE
 
    gtbkg phafile outfile scfile expcube expmap irfs srcmdl target


DESCRIPTION

    To produce a background spectrum file (PHA1), gtbkg uses as input 
    several files that are created with other tools: The input spectrum 
    file (PHA1) by gtbin; The live-time file, by gtltcube; The exposure 
    map by gtexpmap; The source xml file by ModelEditor. 
    The exposure map is the same as the one created for the unbinned 
    likelihood analysis. 
    The background spectrum file contains total counts based on a gtlike 
    source model and covers the same energy bands and region-of-interest as
    the input PHA1 file. The model will typically contain interstellar and
    extragalactic diffuse components as well as nearby point sources.


PARAMETERS

    phafile [filename]
         Name of input spectrum file (PHA1). This file should be produced with
         gtbin (option PHA1). Type "fhelp gtbin" for further explanation.
 	 	 
    outfile [filename]
         Output spectrum file (PHA1).
 	 	 
    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 gtorbsim help for further
         explanation) or more commonly it can be obtained from the FSSC
         website.
 
    (sctable) [string]
         Spacecraft data extension. Default is "SC_DATA".

    expcube [filename]
	 FITS file containing livetime 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.
	 Default is "none".

    expmap [filename]
         Exposure map file used in an unbinned likelihood analysis and created
         by gtexpmap. Do not use an exposure map that is appropriate for binned 
	 analysis (i.e. from gtexpcube2). See gtexpmap help for further 
	 explanation. Default is "none".

    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). The default value is “CALDB”.
	 	 
   evtype [integer]
   	  The evtype to be used in generating the bacground data. The
   	  default is INDEF which will use the default in the PHA
   	  file. This can be overridded by entering the desired event
   	  type e.g. 3 for FRONT + BACK events. 

    srcmdl [filename]
         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. This 
	 model file can be the output of a likelihood fit (either binned or
	 unbinned) as well.
	 	 
    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" (default).
 	 	 
    (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

    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 run gtbkg simply type in the command line: 

>gtbkg

    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 to prevent overwriting an existing output file, the 
    following command line as to be typed::
 
>gtbkg clobber=no  
 
    An example of how to run the tool is given below: 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.

> 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[CALDB] CALDB
Source model file[] src_model.xml
Target source name (excluded from background estimate)[none] 3C279
Excluding source 3C279 from background model.

    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=CALDB srcmdl=src_model.xml target=3C279


KNOWN BUGS


SEE ALSO

     gtbin

     gtltcube

     gtexpmap

     gtlike

     gtorbsim

     gtexposure2

     ModelEditor
