forked from fermi-lat/fermitools-fhelp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
gtmktime.txt
205 lines (157 loc) · 8.68 KB
/
gtmktime.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
NAME
gtmktime - Create Good Time Intervals (GTIs) based on
selections made using the spacecraft data file variables.
USAGE
gtmktime scfile filter roicut evfile outfile
DESCRIPTION
gtmktime is used to update the Good Time Intervals (GTI) extension and
make cuts based on spacecraft parameters contained in the Pointing and
Livetime History (spacecraft) FITS file.
A Good Time Interval is a time range when the data can be
considered valid. The GTI extension contains a list of these
GTIs for the file. The sum of the entries in the GTI extension
of a file corresponds to the time intervals when the data in the
file is "good". This is based on the spacecraft aspect history
and a user specified set of selection criteria. In the case of
the LAT data, the GTIs are the list of times that the LAT was
collecting data over the selected time range and is also used to
'cut out' times when the selected source was close to the earth
limb. Tools use the GTIs for exposure calculations.
The gtmktime tool reads the spacecraft data file and, based on
specified cuts, creates a set of GTIs. These are then combined
(logically) with the existing GTIs in the event file, and all
events outside this new set of GTIs are removed from the
file. New GTIs are then written to the GTI extension of the new
file. The gtmktime tool will be most commonly applied to event
data; and by default the event data will be filtered according to
the GTIs that are created. This tool may also be used to update
GTIs in other files such as those created by gtltcube (see the
gtltcube help).
The cuts can be made on any field in the spacecraft data
file. The default is to select times when the spacecraft is not
in the Southern Atlantic Anomaly (SAA), i.e. "IN_SAA!=T". The
cuts are made using C-style relational syntax like for example: !
(not), && (and), || (or), != (different), >, <, >=, <=, abs(),
cos(), sin(), etc.
Other kinds of cuts on the data could be made using the gtselect
tool. See the gtselect documentation for further explanation.
PARAMETERS
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 the
gtorbsim help for further explanation) It is normally
obtained from the Fermi Science Support Center (FSSC)
website and matches the time range of the requested data.
(sctable) [string]
Spacecraft data extension. Default is "SC_DATA".
filter [string]
This is the user supplied filter expression. It defines the
cuts being made using a C-style relational syntax like for
example: ! (not), && (and), || (or), != (different), >, <,
>=, <=, abs(), cos(), sin(), etc. Default is "DATA_QUAL>0 &&
LAT_CONFIG==1".
roicut [boolean]
Apply ROI-based zenith angle cut to exclude times where the region of
interest is outside the field of view. If "yes", then the code will
construct a filter string expression of the form
angsep(RA_ZENITH,DEC_ZENITH,RA_ROI,DEC_ROI) <ZENMAX - ROI_RADIUS
This expression will be "and"-ed it with the filter expression
provided by the user. The zenith angle cut and acceptance cone
information used in this expression are read from the DSS keywords in
the EVENTS header of the input event file. These keywords are written by
gtselect when the selections are made. If the required DSS keywords
are missing, then a warning message is printed and no additional
filter string is applied.
evfile [filename]
Input event file. This is the file containing the event data. This
file is most commonly obtained from the FSSC website.
(evtable) [string]
Event table extension name. Default is "EVENTS".
outfile [filename]
Output event FITS file name.
(apply_filter) [boolean]
Flag to apply GTI filter to event data. Default is "yes".
Set this to "no" for non-event files.
(overwrite) [boolean]
Build the GTIs from scratch, overwriting the existing GTI
extension. By default (parameter set to "no"), the new GTIs will
be merged with any existing GTIs in the file. By setting this option
to "yes", the old GTI extension will be ignored.
(header_obstimes) [boolean]
Use the FITS table header values for TSTART and TSTOP. Default is "yes".
This option is only relevant if "overwrite=yes", otherwise it is ignored.
(tstart) [double]
Observation start time Mission Elapsed Time (MET) seconds. 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. This option is only
relevant if "header_obstimes=no". The DATE-OBS and TSTART header
keywords and earliest GTI start time will be modified to be consistent
with this value. Default is "0".
(tstop) [double]
Observation stop time (MET seconds). This option is only relevant if
"header_obstimes=no". The DATE-END and TSTOP header keywords and
latest GTI start time will be modified to be consistent with this
value. Default is "0".
(gtifile) [filename]
Name of temporary file for storing GTIs.
(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 editing the parameter file.
To be prompted for gtmktime simply type in the command line:
> gtmktime
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, if the user does not want to overwrite the
existing output file, the user should set the parameter "clobber=no", e.g.:
> gtmktime clobber=no
In the following example the "_3C279_3C273_back_events_0000.fits" data
file is used, along with the spacecraft data file called
"spacecraft_data_file.fits". All events that fall in time ranges outside
of the SAA are selected out:
> gtmktime
Spacecraft data file[] spacecraft_data_file.fits
Filter expression[DATA_QUAL>0 && LAT_CONFIG==1]
Apply ROI-based zenith angle cut[yes]
Event data file[] _3C279_3C273_back_events_0000.fits
Output event file name[] _3C279_3C273_back_filtered.fits
The output event FITS file is called "_3C279_3C273_back_filtered.fits".
The same example can be run in the command line in this way:
> gtmktime scfile=spacecraft_data_file.fits \
filter="DATA_QUAL>0 && LAT_CONFIG==1" \
roicut=yes evfile=_3C279_3C273_back_events_0000.fits \
outfile=_3C279_3C273_back_filtered.fits
SEE ALSO
gtltcube
gtorbsim
gtselect