NAME

    gtsrcmaps - Convolves source model components with the instrument
    response. 

USAGE
    
    gtsrcmaps scfile expcube cmap srcmdl bexpmap outfile irfs


DESCRIPTION

    gtsrcmaps convolves the components that comprise specified source
    model with the instrument response for a given observation. The
    output is a FITS data structure containing one table extension for
    each source of your xml model. Each such extension contains a
    counts map binned in space and energy for the given source.  This
    tool is used as part of the FERMI binned likelihood analysis, so
    it is recommended to read the gtlike help and threads.

    One of the inputs of this tool is a counts map, which should be
    created using the gtbin tool (see gtbin help).

    The geometry in sky coordinates and energy binning of the output
    maps match that of the input maps.

    Another input is the binned exposure map which should be created
    using the gtexpcube2 tool (see gtexpcube2 help).  The binned
    exposure map must extend 10 degrees beyond the farthest point a
    source might contribute photons to the ROI.  In practical terms,
    this is usually 20 degrees beyond the ROI being analyzed.  For
    example, if the counts map created by gtbin is a 7 degree square,
    then the binned exposure map should be 40 degrees square.  This is
    because the upper corner of the 7 degree square is about 10
    degrees from the center of the square.  This, you need to
    calculate the exposure out to 30 degrees from the center.  A
    square with 40 degree sides fits within this large circle.  This
    exposure map can be reused for subsequent analyses of regions that
    cover the same time range and that use the same energy binning.

    Since the source map generation for point sources is fairly quick,
    and maps for many point sources may use a lot of disk space, it
    may be preferable to disable the generation of the source maps for
    point sources at this stage. If a source in the xml model is
    missing from the input source map file, gtlike will compute the
    maps on the fly.  Relying on this mechanism is recommended only
    for point sources.

    To skip generating source maps for point sources, specify
    "ptsrc=no" on the command line when running gtsrcmaps.


PARAMETERS

    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 for further explanation) or more commonly 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.
   	 
    expcube [file]
        FITS file containing live-time as a function of sky position
        and off-axis angle. This file should be generated by
        gtltcube. See the gtltcube documentation for further
        explanation.
		 
    cmap [file]
        Counts map file created by gtbin (see the gtbin help).
 	 
    srcmdl [file]
        XML file containing the source model definitions. This source
        model file is the same used by gtlike (see gtlike help). The
        source model could be generated by the ModelEditor utility
        (recommended) or manually edited following source model
        templates. See the ModelEditor help for further explanation.
 		 
    bexpmap [file]
        Exposure map for binned analysis. See the discussion above for
        details on generating this file.
 	 
    outfile [file]
        Output FITS file name.
 	 
     evtype [integer]
   	  The evtype to be used in generating the bacground data. The
   	  default is INDEF which will use the default in the input
   	  file. This can be overridded by entering the desired event
   	  type e.g. 3 for FRONT + BACK events. 

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

a
    (convol = yes) [bool]
        This parameter allows the user select whether or not to
        perform a convolution of the model with the PSF. This is a
        hidden parameter. The default value is "yes".
 	 
    (resample = yes) [bool]
        Resample input counts map for convolution.

    (rfactor = 2) [integer]
        Resampling factor.

    (minbinsz = 0.1) [double]
        Rebinning for finely binned model maps. Units are degrees.

    (ptsrc = yes) [bool]
        This parameter allows the user to select whether or not to
        compute source maps for point sources. This is a hidden
        parameter. The default value is "yes".
 
    (psfcorr = yes) [bool]
        Apply psf corrections for point source maps. This is a hidden
        parameter. The default value is "yes".

    (emapbnds = yes) [bool]
        Check or not check that the exposure has been calculated for
        all of the possible points in the counts map (effectively 10
        degrees beyond the ROI plus accounting for the PSF
        convolution).  If the exposure hasn't been calculated, exit.

    (copyall = no)  [bool]
        Copy all source maps from input counts map file to output.

    (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 run gtsrmaps interactively simply type in the command line

> gtsrcmaps

    and respond to the prompts.  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 skip generating source
    maps for point sources, specify "ptsrc=no" on the command line
    when running gtsrcmaps:

> gtsrcmaps ptsrc=no

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

> gtsrcmaps
Spacecraft data file [] : spacecraft_data_file.fits
Exposure hypercube file [] :  expCube.fits
Counts map file [] : ps_counts.fits
Source model file [] : src_model.xml
Binned exposure map [] : bexposure.fits 
Source maps output file [] : srcMaps.fits
Response functions [] : CALDB

    This last example could be also be run from the command line as follows:

> gtsrcmaps scfile=spacecraft_data_file.fits expcube=expCube.fits
  cmap= ps_counts.fits srcmdl=src_model.xml bexpmap=bexposure.fits
  outfile=srcMaps.fits irfs=CALDB


KNOWN BUGS


SEE ALSO


   gtbin
   gtdiffrsp
   gtexpmap
   gtexpcube2
   gtlike
   gtltcube

