forked from fermi-lat/fermitools-fhelp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
gtltcube.txt
208 lines (168 loc) · 8.93 KB
/
gtltcube.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
NAME
gtltcube - Calculates integrated livetime as a function of sky
position and off-axis angle.
USAGE
gtltcube evfile scfile outfile dcostheta binsz
DESCRIPTION
The LAT instrument response functions depend on the angle
between the direction to a source and the instrument z-axis. (This
angle is commonly referred to as the inclination or "off-axis
angle".) The number of counts that are detected for a source of a
given intensity thus depends on how long that source spends at
various inclination angles over the course of an observation. The
number of counts will also depend on the "livetime", i.e., the
accumulated time during which the LAT is actively taking event
data. To facilitate the calculation of model counts by gtlike and
other analysis tools, the gtltcube tool computes the livetime as a
function of inclination and location on the sky for a specified
observation period.
The livetimes are therefore a function of the three dimensional
space comprising the sky position and inclination angle, and
accordingly the data product produced by gtltcube is called a
"livetime cube". However, as a practical matter, the livetime
cannot be provided as a continuous function of inclination angle
or position on the sky. Thus the livetime cubes are defined on a
HEALPix grid on the sky and in inclination angle bins. HEALPix is
an acronym for Hierarchical Equal Area isoLatitude Pixelization
(http://healpix.jpl.nasa.gov/) of a sphere. As suggested in the name,
this pixelization produces a subdivision of a spherical surface in
which each pixel covers the same surface area as every other pixel.
Another property of the HEALPix grid is that the pixel centers occur
on a discrete number of rings of constant latitude, and the number of
constant-latitude rings depends on the resolution of the HEALPix grid.
gtltcube uses the spacecraft pointing history file along with the
time range and GTI selections in the event file to compute livetime
cubes that cover the entire sky. Therefore any change in data
selection which affects the GTIs (time range, zenith angle, ROI, etc.)
requires the livetime cube to be recomputed.
Since livetime cubes are additive, the livetime cube for a given
epoch can be obtained by co-adding the livetime cubes for the subset
of non-overlapping time ranges that it comprises. The gtltsum tool
can be used to co-add livetime cubes. (See the gtltsum help.)
PARAMETERS
evfile [file]
Input event file. This is the file containing the event data. If
several events files have to be input (event files which cover
different time intervals), an ASCII file with a complete list
should be entered here with an "@" sign before the name. For
example, if the name of that ASCII file is "event_files", then this
parameter should be entered in this way: evfile=@event_files.
(evtable = EVENTS) [string]
Event table extension name. This is a hidden parameter. The default
value is EVENTS.
scfile [file] 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), and for real observations, it can
be obtained from the FSSC.
(sctable = SC_DATA) [string]
Spacecraft data extension. This is a hidden parameter. The default
value is SC_DATA.
outfile [file]
Output FITS file name.
dcostheta = 0.025 [double]
Inclination angle binning represented as the cosine of the off-axis
angle.
binsz = 1 [double]
Size of the desired spatial grid in degrees.
(phibins = 0)
Number of phi bins. When phibins=0, the phi-integrated livetimes
are computed, and in subsequent exposure calculations (e.g., with
gtexpmap or gtexpcube2) the phi-averaged effective area is used.
For normal survey mode observations and for time scales longer
than 12 hours, the variation of the exposure induced by the phi-
dependence of the effective area is <3%. Because of the square
shape of the LAT, the phi-dependence has an 8-fold symmetry and
has an RMS variation of <10% at 100 MeV. A value of phibins=5 is
usually sufficient to capture the phi-dependence on time scales
shorter than 12 hours.
(tmin = 0) [double]
Minimum time (MET s). MET (Mission Elapsed Time) is the number of
seconds since midnight (00:00:00) January 01, 2001 Coordinated
Universal Time (UTC). This will have at least 7 digits. See for
example the Fermi Technical Handbook:
http://fermi.gsfc.nasa.gov/ssc/proposals/manual/
The parameter is ignored if both tmin==0 and tmax==0, while it
applies only if evfile is a null string. This is a
hidden parameter. The default value is 0. If tmin is less than the
TSTART time in the event file the minimum value taken is the
TSTART time of the event file. If the range between tmin and tmax
is outside the time range of the event file, gtltcube will use as
tmin, the TSTART time of the event file, and as tmax the TSTOP
time of the event file. To see the filters applied in the time
range, set the chatter parameter "chatter=4".
(tmax = 0) [double]
Maximum time (MET s). Ignored if both tmin==0 and tmax==0, while it
applies only if evfile is a null string. This is
a hidden parameter. The default value is 0. If tmax is larger than
the STOP time in the event file the maximum value taken is the
STOP time of the event file. If the range between tmin and tmax is
outside the time range of the event file, gtltcube will use as
tmin, the TSTART time of the event file, and as tmax the TSTOP
time of the event file. To see the filters applied in the time
range, set the chatter parameter "chatter=4".
(file_version = 1) [string]
This sets the value of the VERSION keyword in the primary header
of the output file.
(zmax = 180) [double]
The maximum zenith angle over which the livetimes are integrated.
This zenith angle selection pertains to true source locations on the
sky. Therefore this cut is not equivalent to applying a maximum zenith
angle cut in gtselect, since in the latter case the cut is made on
measured photon directions. Non-default zenith angle selections should
not be used for standard analyses. Value must be in the range 0-180.
(zmin = 0) [double]
The minimum zenith angle over which the livetimes are integrated.
Value must be in the range 0-180.
(chatter = 2)
This parameter fixes the output verbosity: no screen output (0),
nominal screen output (2), maximum verbosity (4). The default value is
2.
(clobber = yes)
If true, an existing file of the same name will be overwritten.
(debug = no)
Activate debugging mode. This is a hidden parameter. The default
value 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 = no)
Graphical user Interface (GUI) mode is activated if
gui="yes". This is a hidden parameter with a default value of
"no".
(mode = ql)
Mode of automatic parameters. This is a hidden parameter. The
default value is "ql".
EXAMPLES
Parameters are passed to gtltcube following the FTOOLS model. They can
be passed by responding to a prompt, as a list in a command line, or by
editing the parameter file. This allows gtltcube to be called from a
script.
To be prompted for gtltcube simply type in the command line:
> gtltcube
You will be prompted for parameter values. Beware that not all
parameters are prompted: some of the parameter are "hidden". If you
want to change one of the "hidden" parameter you should specify its
value in the command line. For example if you do not want to overwrite
the existing output file, type on the command line:
> gtltcube clobber=no
An example of how to run the tool is given below:
> gtltcube
Event data file [] : events.fits
Spacecraft data file [] : spacecraft_data_file.fits
Output file [expCube.fits] :
Step size in cos(theta) (0.:1.) [0.025] :
Pixel size (degrees) [1] :
Working on file spacecraft_data_file.fits
That last example could be also run in the command line as follows:
>gtltcube evfile=events.fits scfile=spacecraft_data_file.fits
outfile=expCube.fits dcostheta=0.025 binsz=1
SEE ALSO
gtdiffrsp
gtexpmap
gtltsum
gtsrcmap