NAME

    gttsmap - Calculates test-statistic map for source localization
              and detection.

USAGE

    gttsmap statistic scfile evfile expmap cmap bexpmap expcube srcmdl irfs
    optimizer outfile nxpix nypix binsz coordsys xref yref proj


DESCRIPTION

    This tool computes a significance map based on the maximum
    likelihood test statistic (TS) (see, for example, the gtlike help
    and references therein). The resulting map can be used to localize
    sources within the analysis region. It can also serve as input to
    follow up for the binned and the unbinned likelihood analysis. The
    TS maps are created by
    moving a putative point source through a grid of locations on the
    sky and maximizing -log(likelihood) at each grid point, with the
    other, stronger, and presumably well-identified sources included
    in each fit. New, fainter sources are then identified at local
    maxima of the TS map.

    In each point of the map the TS is obtained using the same procedure
    as in the binned or unbinned likelihood analysis, so many of the
    gttsmap parameters are the same as the ones used in gtlike (see
    the gtlike help).  Note that one should run gtdiffrsp before
    running gttsmap (see the gtdiffrsp help).

    One should keep in mind that this tool takes a lot of time to run
    because a CPU-intensive likelihood analysis is performed at a grid
    of different positions.

PARAMETERS

    statistic [string]
    Statistic that will be used to generate the map. The optional values
    are "BINNED" or "UNBINNED".

    evfile [file]
    Input event file. This is the file containing the LAT event
    data. If multiple events files are desired, 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 = EVENTS) [string]
    Event table extension name. This is a hidden parameter.

    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
    Fermi Science Support Center (FSSC).

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

    expmap [file]
    Exposure map file created by gtexpmap and like those used in an
    unbinned likelihood analysis. See the gtexpmap help for further
    explanation.

    bexpmap [file]
    Exposure map file created by gtexpmap and like those used in an
    binned likelihood analysis. See the gtexpmap help for further
    explanation.

    cmap [file]
    Counts map file to be used in the binned likelihood analysis.

    (psfcorr = yes) [boolean]
         Apply psf corrections for point source maps.

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

    srcmdl [file]
         XML file containing the source model definitions for known sources
	 that are input into your calculation. This source model file is
	 the same as that used by gtlike (see the gtlike help). The source
         model could be generated by the ModelEditor utility or by
         following source model templates. See the ModelEditor 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). 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 input
   	  file. This can be overridden by entering the desired event
   	  type e.g. 3 for FRONT + BACK events.

    outfile [file]
        Output FITS file name.

    optimizer [string]
    Optimizer package to use (see the gtlike documentation), either
    MINUIT, DRMNGB, or LBFGS. Due to
    the fact that gttsmap calls the same routines as gtlike to obtain
    the TS of the detection at each analyzed position, the optimizer
    should be the same than the ones used for that tool. The default
    value is MINUIT.

    (ftol = 1.e-3) [double]
    Relative Fit tolerance. This is the fit tolerance for the
    likelihood analysis. It is the same parameter used for gtlike. See
    the gtlike help for further explanation.

    (toltype = ABS)
    Fit tolerance convergence type (absolute vs relative).

    nxpix [int]
    Number of pixels along x coordinate axis, ranging from 2 to 200.

    nypix [int]
    Number of pixels along y coordinate axis, ranging from 2 to 200.

    binsz [double]
    Image scale (in degrees/pixel).

    coordsys [string]
    Coordinate system to use (CEL=J2000 celestial, GAL=Galactic).

    xref [double]
    X-coordinate of image center in degrees (RA or l).

    yref [double]
    Y-coordinate of image center in degrees (Dec or b).

    proj [string]
    Coordinate projection (AIT|ZEA|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN);
    see Calabretta & Greisen 2002, A&A, 395, 1077 for definitions of the
    projections. Must be AIT, ZEA, or CAR for auto full sky.

    (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 is "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 can be
    passed interactively in response to a prompt, a listed in a
    command line, or by editing the parameter file.

    To run gttsmap interactively simply type in the command line:

    >gttsmap

    You will then be prompted for parameter values. 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 do not want to
    overwrite an existing file, type in the command line:

    >gttsmap clobber=no

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

    > gttsmap
    Statistic to use (BINNED|UNBINNED) [UNBINNED]
    Spacecraft file[none] spacecraft_data_file.fits
    Event file[none] events.fits
    Exposure map file [none] : expMap.fits
    Exposure hypercube file [none] :expCube.fits]
    Source model file [] : src_model.xml
    TS map file name [] : TsMap.fits]
    Response functions to use [] : CALDB
    Optimizer (LBFGS|MINUIT|DRMNGB) [DRMNGB] :
    Fit tolerance [1e-05] :
    Number of X axis pixels[] 20
    Number of Y axis pixels[] 20
    Image scale (in degrees/pixel)[] 0.5
    Coordinate system (CEL|GAL) [CEL]
    X-coordinate of image center in degrees (RA or l[] 193.98
    Y-coordinate of image center in degrees (Dec or b)[] -5.82
    Projection method (AIT|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN) [STG]
    .....................!

    This example is performed in the region around
    (193.98,-5.82). 3C279, 3C273 and the Galactic and
    Extragalactic background were included in the source model. The
    expMap.fits file was produced using gtexpmap (see the gtexpmap
    help), while the expCube.fits file was produced using gtltcube
    (see the gtltcube help). spacecraft_data_file.fits is the spacecraft
    file. 20 points were selected for the x- and y-axis
    respectively. In those points the likelihood analysis is
    performed.

    That last example could be also run in the command line as follows:

    > gttsmap statistic=UNBINNED evfile=events.fits scfile=spacecraft_data_file.fits
    expmap=expMap.fits expcube=expCube.fits srcmdl=src_model.xml
    outfile=TSMap.fits irfs=CALDB optimizer=DRMNGB ftol=1e-05
    nxpix=20 nypix=20 binsz=0.5 xref=193.98 yref=-5.82
    coordsys=CEL proj=STG


SEE ALSO

     gtlike

     gtltcube

     gtexpmap