NAME

    gtfindsrc - Optimizes a point source location using the likelihood 
                test-statistic.


USAGE
    
    gtfindsrc evfile scfile outfile irfs expcube expmap srcmdl target
    coordsys ra dec l b optimizer ftol atol


DESCRIPTION

     Since our standard likelihood analysis is based on sky models with
     sources at fixed spatial positions, a separate tool is provided to
     optimally localize newly discovered sources.   This tool estimates
     point source locations using an unbinned likelihood analysis.
     This is accomplished by using a multidimensional minimization
     routine  (see, for example, Numerical Recipes Chapter 10:
     http://www.fizyka.umk.pl/nrbook/bookcpdf.html) which finds the
     optimal test-statistic (TS) for a grid of positions positions
     around an initial guess until the convergence tolerance for a
     positional fit is reached. 
  
    
PARAMETERS
    
    evfile [filename]
         Input event file. If several events files have to be input, an
         ASCII file with the complete list of them should be entered here.
  	  	 
    (evtable) [string]
         Event table extension name. 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".
  	  	 
    outfile [filename]
         Output file name, an ASCII file where the initial starting values, 
	 the intermediate, as well as the final values for the best fit 
	 position (RA and DEC), the TS and the circle radius are given.
	 The coordinates and errors are given in decimal degrees.
  	  	 
    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 input
   	  file. This can be overridded by entering the desired event
   	  type e.g. 3 for FRONT + BACK events. 

    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. See gtexpmap help for further explanation. Default is "none".
      	  	 
    srcmdl [filename]
         XML file containing the source model definitions. This is the same
         source model file used by gtlike (see the gtlike help). The source model 
	 can be generated by the "ModelEditor" utility or by following source 
	 model templates (see the "ModelEditor" help for further explanation: 
	 after typing "modeleditor" at the prompt, a gui appears. Select "HELP" 
	 in the main menu).
  	  	 
    target [string]
         Target source name from srcmdl. This is the name of the source for
         which the best position will be optimized with gtfindsrc.

    coordsys [string]
         Coordinate system for input of the putative point source, to be chosen
	 between celestial ("CEL", the default value) and Galactic ("GAL"). 
	 Selecting "CEL", the user will be prompted for right ascension and
	 declination (J2000), otherwise for Galactic latitude and longitude.
  	  	 
    ra [double]
         Initial guess for the source right ascension (decimal degrees). 
         Default is zero.
  	  	 
    dec [double]
         Initial guess for the source declination (decimal degrees). 
         Default is zero.
  	  	 
    l [double]
         Initial guess for the source Galactic longitude (decimal degrees). 
         Default is zero.
  	  	 
    b [double]
         Initial guess for source Galactic latitude (decimal degrees). 
         Default is zero.
  	  	 
    optimizer [string]
         Optimizer package to use. The options are: "DRMNFB", "NEWMINUIT", 
	 "MINUIT", "DRMNGB", 
	 and "LBFGS". See "MODEL FITTING" section of the gtlike documentation 
	 for details. Default is "MINUIT". Due to the fact that gtfindsrc 
	 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 one used for that tool. 
  	  	 
    ftol [double]
         Relative fit tolerance. This parameter is used for the likelihood
         analysis and should be set to the same value adopted when running 
	 gtlike. See the gtlike help more explanation on the subject. 
	 Default is 1e-2.
  	  	 
    (reopt) [boolean]
         Refit all free parameters at each candidate point source
         location. The "free" parameters are the parameters marked as
         "free" in the source model file, and are the ones to be fitted in
         the likelihood analysis. See the gtlike help more explanation on
         the subject. Default is "yes".
  	  	 
    atol [double]
         Convergence tolerance for positional fit. Default is 0.01 (decimal 
	 degrees).

    (toltype) [string]
         Fit tolerance convergence type. The options are: "ABS" (absolute, the
	 default value) and "REL" (relative).
	  	 
    (posacc) [double]
         Accuracy for best-fit position (decimal deg). Default is 0.001.
  	  	 
    (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 gtfindsrc simply type in the command line: 

> gtfindsrc
 
    The parameter values have to be provided. Not all
    parameter are prompted: some of them are "hidden". To
    change one of the "hidden" parameter, the user should specify the value
    in the command line or modify its mode by editing the parameter 
    file. For example, to chance the accuracy for the best fit position, 
    the following command line has to be typed:
 
> gtfindsrc posacc=0.0001

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


> gtfindsrc 
Event file[] events.fits
Spacecraft file[] spacecraft_data_fle.fits
Output file for trial points[] test
Response functions to use[P7SOURCE_V6] P7SOURCE_V6
Livetime cube file[none] expCube.fits
Unbinned exposure map[none] expMap.fits 
Source model file[none] src_model.xml 

Building source model from src_model.xml
-log-likelihood of input source model 4059.27
Target source name[] point_src1
Coordinate system[CEL] CEL
Intial source Right Ascension (deg)[0] 50.45
Initial source Declination (deg)[0] -37.24
Optimizer[MINUIT] MINUIT
Tolerance for -log(Likelihood) at each trial point[1e-2] 1e-2
Covergence tolerance for positional fit[0.01] 0.01
Best fit position: 50.4522,  -37.2381
Error circle radius: 0.116836

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

> gtfinsrc evfile=events.fits scfile=spacecraft_data_file.fits outfile=test 
  irfs=CALDB expcube=expCube.fits expmap=expMap.fits srcmdl=src_model.xml
  target=point_src1 coordsys=CEL ra=50.45 dec=-37.24 optimizer=MINUIT ftol=1e-2 atol=0.01


KNOWN BUGS


SEE ALSO

     gtexpmap

     gtltcube
 
     gtdiffrsp

     gtlike
 
     gtorbsim

     modeleditor
    


