forked from fermi-lat/fermitools-fhelp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgtselect.txt
285 lines (221 loc) · 11.9 KB
/
gtselect.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
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
NAME
gtselect - Performs selection cuts on event data files.
USAGE
gtselect infile outfile ra dec rad tmin tmax emin emax zmin zmax
evclass evtype
DESCRIPTION
gtselect creates a filtered FITS file by selecting rows from an input
event data file based on user-specified cuts that are applied to
each row of the input file. This application enables detailed
selections to be made on Fermi photon and event data obtained from the
FSSC data server or simulated data generated using gtobssim
(see gtobssim help). The most common selections are these
involving time range (minimum and maximum time) and energy range
(minimum and maximum energy), and event class. For each cut that is applied Data
Subspace (DSS) keywords are written to the EVENTS header of the
output FITS file that describe the selection. This information is
used by the likelihood tools and gtrspgen for computing
exposure-related information.
NOTES
- The selection cone center (right ascension and declination)
must match exactly that which was used in the original selection
from the data server.
- both evclass and evtype are "hidden" parameters, i.e. they are
not propmted for but must be supplied on the command line
- evclass, recommended selection for standard analysis = 128 (source)
The event classification system in Pass 8 is similar to that employed
in Pass 7 (i.e. a bitmask classification system for various event classes),
Additionally, through the use of the new data filter EVENT_TYPE (see below),
further subselection of events are allowed in data preparation. Each bit
in the EVENT_CLASS variable corresponds to a
particular set of the Instrument Response Functions (IRFs). The more
used event classes (Transient, Source, Clean and UltraCleanVeto ) are
still hierarchical, i.e., Transient > Source > Clean > UltraCleanVeto.
Most analyses will use either the Source or Clean event samples.
**NOTE** once you perform selection on event class or event type, you
cannot revert to a more general selection at a later stage of your analysis.
Table of standard (non-transient) event classes (for a complete
list see the FSSC Website or Cicerone)
-----------------------------------------
|Class (Pass 8)| evclass
|----------------------------------------
|Source | 128 |
|Clean | 256 |
|UltraCleanVeto| 1024 |
-----------------------------------------
- evtype, recommended selection for standard analysis = 3 (front +
back events)
The Pass 8 processing implements a new scheme for partitioning
the data within an event class with "event type" selections.
The event type selections partition the data within a class
into independent subsets. Currently, evtype has the ability to
select on 2 different types of event conversions (front/back),
4 different PSF classes, and 4 different energy reconstruction
classes. You may select a sub-sample within a given event type
(e.g. PSF2), but those events can only be used with other
events of the same type. If you select one of the "all events"
values (3 = front+back, 60 = PSF0+PSF1+PSF2+PSF3, 960 =
EDISP0+EDISP1+EDISP2+EDISP3). be aware that different IRFs
will be applied. If you do not select an "all events" value,
then the tool may apply results only to a subset of the
events.
PARAMETERS
infile [filename]
Input event FITS file. This is the file containing the event data.
outfile [filename]
Output event FITS file with events that satisfy the selections
performed with gtselect.
ra [double]
Right ascension of acceptance cone (J2000) in decimal degrees.
If the parameter is set to INDEF the right ascension will be read from the
header of the input file.
dec [double]
Declination of acceptance cone (J2000) in decimal degrees.
If the parameter is set to INDEF the declination will be read from the
header of the input file.
rad [double]
Radius of acceptance cone (decimal degrees). A value of 180 (default)
indicates that no acceptance cone cut will be applied. If the
parameter is set to INDEF the radius will be read from the header
of the input file.
tmin [double]
Event arrival time lower limit in mission elapsed time (MET)
seconds. All the events in the output FITS file will have "event
arrival time" larger than this value. The reference time used for MET
is midnight (0h:0m:0s) on January 1, 2001, in Coordinated Universal
Time (UTC). The Fermi convention is that MJDREF=51910
(UTC)=51910.0007428703703703703 (TT); the fractional part of MJDREF in
the TT system compensates for the use of midnight in the UTC system as
the reference time. MJDREF is divided into two keywords:
MJDREFI=51910, the integer part; and MJDREFF=7.428703703703703D-4, the
fractional part. If the parameter is set to INDEF (default) tmin will be
read from the header of the input file. For conversions
between MET and other commonly used time conventions we refer
the user to the HEASARC online tool
http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/xTime/xTime.pl.
tmax [double]
Event arrival time upper limit in mission elapsed time (MET)
seconds. All the events in the output FITS file will have
"event arrival time" smaller than this value. A value of zero
in this context means that no upper limit will be applied. If
the parameter is set to INDEF (default) the tmax will be read
from the header of the input file.
emin [double]
Minimum event energy in MeV. All the events in the output FITS file
will have "event energy" larger than this value. Default is "100" MeV.
emax [double]
Maximum event energy in MeV. All the events in the output
FITS file will have "event energy" smaller than this
value. Default is "300000" MeV.
zmax [double]
Maximum apparent zenith angle (degrees). It ranges from 0 to 180 (default).
(evclsmin) [integer]
This parameter is ignored for data reprocessed after Aug. 1, 2011
(Pass 7 series).
Mininum event class ID to include. Each set of IRFs will define a set
of event classes numbered 0 to n, where n+1 is the number of event
classes. These numbers will be ordered such that the more inclusive
classes are numbered lowest. Default is "INDEF".
(evclsmax) [integer]
This parameter is ignored for data reprocessed after Aug. 1, 2011
(Pass 7 series).
Maximum event class ID to include. Default is "INDEF".
(evclass) [integer]
Event class selection for pass 8. The default is 128 (source
class).
(evtype) [integer]
The event type selection for Pass 8 data. The event type is a
subselection of the event class. Users can select on range of
events based on conversion type (front/back), angular
reconstruction quality (PSF values), and energy
reconstruction quality (EDISP values). The default value is
INDEF, which will not apply a subselection.
(convtype) [integer]
Conversion type. This parameter screens events based on which
portion of the instrument the incident gamma-ray pair conversion
event occurred. 0=Front, 1=Back, -1=both (defalt value). Refer
to the Cicerone manual for details
(http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone).
(phasemin) [double]
Minimum pulsar phase to include. This cut is only applied if
the PULSE_PHASE column has been added to the FT1 file by the
gtpphase tool. Default is "0".
(phasemax) [double]
Maximum pulsar phase to include. Default is "1".
(evtable) [string]
Event data extension. Default is "EVENTS".
(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
The way that the parameters are passed follows the FTOOLs model. They
could be passed by answering from a prompt, as a list in a command
line, or by modifying the parameter file. The command line option
facilitates calling gtselect from a script.
To prompt for gtselect type in the command line:
> gtselect
This will prompt for parameter values. Not all parameter are prompted:
some of them are "hidden". To change one of the "hidden" parameter,
the user should specify the values in the command line or modify its
mode by editing the parameter file.
For example, to prevent overwrite the existing output file, the following
command line as to be typed:
> gtselect clobber=no
This is an example of how to run the tool:
In this case the quasar 3C279 (centered on Ra=193.98, Dec=-5.82) was
simulated using gtobssim (type "fhelp gtobssim" for further explanation),
although the indentical procedure could be followed for actual data.
Note that a radius of 40 degrees was specified in the input simulation.
The energy for the simulated events ranges between 20 MeV and 200000 MeV.
Using gtselect it possible to select the events with energy larger than
100 MeV and within a radius of 20 degrees centered on Ra=193.98,
Dec=-5.82 and a time range between 220838400 and 225590400 MET seconds:
> gtselect evclass=2
Input FT1 file[] 3C279_events_0000.fits
Output FT1 file[] 3c279_filtered.fits
RA for new search center (degrees) (0:360) [INDEF] 193.98
Dec for new search center (degrees) (-90:90) [INDEF] -5.82
radius of new search region (degrees) (0:180) [INDEF] 20
start time (MET in s) (0:) [INDEF] 220838400
end time (MET in s) (0:) [INDEF] 225590400
lower energy limit (MeV) (0:) [100] 100
upper energy limit (MeV) (0:) [300000] 100000
maximum zenith angle value (degrees) (0:180) [180] 105
Done.
The last example could be also run from the command line as:
> gtselect infile=3C279_events_0000.fits outfile=3c279_filtered.fits \
ra=193.98 dec=-5.82 rad=20 evclass=128 evtype=3 \
tmin=220838400 tmax=225590400 emin=100 emax=100000 zmax=100
You can also use the defaults in the input file header by using
the INDEF syntax
> gtselect infile=3C279_events_0000.fits outfile=3c279_filtered.fits \
ra=INDEF dec=INDEF rad=INDEF evclass=128 evtype=INDEF tmin=INDEF \
tmax=INDEF emin=100 emax=100000 zmax=100
KNOWN BUGS
Use the INDEF values for right ascension, declination, and radius
are handled peculiarly. If any one of the parameters are set to
INDEF it is treated if all are set to INDEF.
SEE ALSO
fselect
gtobssim
gtpphase
gtrspgen