forked from fermi-lat/fermitools-fhelp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
gtfindsrc.txt
237 lines (178 loc) · 8.67 KB
/
gtfindsrc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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