NAME 

      gtdiffrsp - Calculates the integral over solid angle of a diffuse source 
                  model convolved with the instrumental response function

USAGE
 
       gtdiffrsp evfile scfile srcmdl irfs


DESCRIPTION

LAT data are modeled using a maximum likelihood method. The unbinned
likelihood function is defined in terms of the expected photon
distribution for a given source model.  That distribution is the
convolution of the source model with the instrument response. In
particular, the contribution to the log-likelihood associated with an
individual photon is computed as the integral of the source model with
the instrument response evaluated at the observed photon direction,
energy and arrival time.  For point sources, the spatial component is
a delta-function, so this integral is relatively easy to do.  However,
for diffuse sources such as the Galactic interstellar component, this
integral is very computationly intensive since it must be performed 
over the whole sky in principle.  Therefore, if possible, it is useful 
to precompute these quantities in advance.  In the likelihood calculations,
it is assumed that the spatial and spectral parts of a source model factor
in such a way that the integral over spatial distribution of a source
can be performed independently of the spectral part and in this case
the integral over the instrument response can be precomputed for each
diffuse model component.  

The gtdiffrsp tool will perform these integrations and add the results
as an additional column for each diffuse source into the input event file.
Hereafter, we will refer to these quantities as the "diffuse
responses".  If the diffuse responses are not pre-computed using
gtdiffrsp for a given source, gtlike will throw an exception and
report the missing column.  The name of each column is a combination
of the name of the diffuse source and the name of the response
function (see the example below). You may use the FTOOL fdelcol
to delete columns if you want to restore the modified file (see the
fdelcol help more information).

You may overwrite the columns produced by gtdiffrsp using the
clobber=yes parameter; see below.

Please be advised that gtdiffrsp is computationally intensive and depending
on the size of your event file, can take hours to run.


PARAMETERS

evfile [file]
Input event file. This is the file containing the event data. If
several events files have to be input, an ASCII file with the complete
list of them should be entered here with an "@" sign before the
name. For example, if the name of that ASCII file is "events", then is
parameter should be entered as evfile=@events.

(evtable = EVENTS) [string]
Event table extension name. This is a hidden parameter. The default
value is EVENTS.

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 the gtorbsim
help) or it can be obtained from the FSSC.

(sctable = SC_DATA) [string]
Spacecraft data extension. This is a hidden parameter. The default
value is SC_DATA.

srcmdl [file]
XML file containing the source model definitions. This source model
file is the same used by gtlike (see the gtlike help). The source
model could be generated by the model editor utility or by following
source model templates. See ModelEditor help for further explanation.

irfs [string]
Instrument response functions.
  
(edisp = no) 
Use energy dispersion?

(evclsmin = 0)
Minimum event class level

(convert = no)              
convert header to new diffrsp format?
	 
(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 to gtdiffrsp following the FTOOLs model. They
can be passed as answer from a prompt, as a list in a command line, or
by editing the parameter file. This allows calling gtdiffrsp from a
script.
 
To be prompted for gtdiffrsp simply type in the command line: 

> gtdiffrsp 
 
This will prompt for parameter values. Beware that not all parameters
are prompted: some of the parameter are "hidden".  If you want to
change one of the "hidden" parameter you should specify its value in
the command line. For example if you do not want to overwrite the
existing output file you should type in the command line:
 
> gtdiffrsp clobber=no  
  
An example of how to run the tool is given below: 

> gtdiffrsp 
Event data file [] : ps_filtered.fits
Spacecraft data file [] : spacecraft_data_file.fits
Source model file [] : src_model.xml
Response functions to use [] : P6_V3_DIFFUSE


That last example could be also run in the command line as follows: 
 
> gtdiffrsp evfile=ps_filtered.fits scfile=spacecraft_data_file.fits
  srcmdl=src_model.xml irfs=P6_V3_DIFFUSE


LIST OF BUGS


SEE ALSO 

             gtlike
             gtltcube
             gtexpmap
             gtsrcmap