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 computationally 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.

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


PARAMETERS

    evfile [filename]
         This is the input 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 in this way: evfile=@events.

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

    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".

    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 by gtlike (see the gtlike help).

    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 background data. The default
   	    is INDEF which will use the default in the PHA file. This can be
   	    overridden by entering the desired event type e.g. 3 for FRONT + BACK
   	    events.

    (evclsmin) [integer]
         This parameter is ignored for data reprocessed after Aug. 1, 2011
         (Pass 7 or higher).
         Mininum event class ID to include. Each set of IRFs will define a set
         of event classes numbered 0 to n, where n+1 is the number of event
         classes. These numbers will be ordered such that the more inclusive
         classes are numbered lowest. Default is "0".

    (evclass) [integer]
         Event class selection for pass 8 data: "128" for Source ,
         "256" for Clean. Default is "INDEF".

    (convert) [boolean]
         Parameter to convert header to a new diffrsp format. Default is "no".

    (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 gtdiffrsp simply type in the command line:

    > gtdiffrsp


    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 overwrite the existing output file, the following
    command line as to be typed:

    > 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[CALDB] CALDB

    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=CALDB


SEE ALSO

     gtlike

     gtobssim