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