forked from fermi-lat/fermitools-fhelp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
gtltcubesun.txt
253 lines (202 loc) · 10.9 KB
/
gtltcubesun.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
NAME
gtltcubesun - Calculates integrated livetime as a function of sky
position, instrument angle and distance from a solar system body
(Sun or Moon).
USAGE
gtltcubesun evfile scfile outfile body dcostheta thetasunmax 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.
Analysis of LAT data is usually performed in coordinate systems
fixed to distant stars. This causes problems for sources moving
in that system, such as the Sun and the Moon. To first order, the
emission from the Sun and the Moon is spherically symmetric and
their intensity on a point in the sky therefore only depends on
the distance between the point and the source. To facilitate the
inclusion of the emission from the Sun and the Moon, gtltcubesun
computes the livetime as a function of 1) inclination, 2) location
on the sky, and distance from 3) the Sun or 4) the Moon for a
specified observation period.
The livetimes are therefore a function of these four dimensional
spaces and, accordingly, the data product produced by gtltcubesun
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 bins of
inclination angle and angle from the Sun or the Moon. HEALPix is
an acronym for Hierarchical Equal Area isoLatitude Pixelization
(http://healpix.jpl.nasa.gov/) of a sphere. As suggested by 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.
gtltcubesun 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
gtltsumsun tool can be used to co-add livetime cubes. (See the
gtltsumsun help).
NOTES
While it is possible to change the pixel size, we don't recommend
changing it from the default 0.5 degrees. Larger values will
result in inaccurate calculation of the livetime, while smaller
values significantly increase the memory needed to run the tools.
When calculating the binned livetime for minimally extended moving
sources (e.g., the Moon), the tool will be much faster by limiting
the maximum angle of the distance from the solar system body to
cover the extension of the source (e.g., 0.5 degrees for the
Moon).
PARAMETERS
evfile [filename]
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.
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), and for real observations, it can
be obtained from the FSSC.
(sctable = SC_DATA) [string]
Spacecraft data extension. This is a hidden parameter.
outfile [filename]
Output FITS file name.
body [string]
The solar system body to use (for now only SUN and MOON).
dcostheta [double]
Inclination angle binning represented as the cosine of the off-axis
angle.
thetasunmax [double]
The maximum distance from the moving source used in binning. 180
degrees is necessary for the Sun but 0.5 degrees should be enough
for the Moon. This value should be larger than the size of the
extended emission from the solar system body.
binsz [double]
Size of the desired spatial grid in degrees. Note that this is not
a continuous variable and is turned into a HEALPix order. The step
size is therefore binned in roughly factor of 2 values.
(phibins = 0) [double]
Number of phi bins. When phibins=0, 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. Files generated will be phibins times
bigger than the usual without the phi dependence.
(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: 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, gtltcubesun 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, gtltcubesun 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".
(powerbinsun = 2.7) [double]
The binning in distance is done in cos(angle)^1/powerbinsun).
Powerbinsun=1 gives roughly linear binning between 60 and 120
degrees and powerbinsun=2 gives roughly a linear binning between 0
to 90 degrees. A value between 2 and 3 is appropriate for a
normal solar intensity profile. The suggested values are 2.7 for
the Sun and 2 for the Moon.
(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.
(chatter = 2) [integer]
This parameter fixes the output verbosity: no screen output (0),
nominal screen output (2), maximum verbosity (4).
(clobber = yes) [boolean]
If true, an existing file of the same name will be overwritten.
(debug = no) [boolean]
Activate debugging mode. 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) [boolean]
Graphical user Interface (GUI) mode is activated if gui="yes".
(mode = ql) [string]
Mode of automatic parameters: "h" for batch, "ql" for interactive.
EXAMPLES
Parameters are passed to gtltcubesun 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
gtltcubesun to be called from a script.
To be prompted for gtltcubesun simply type in the command line:
> gtltcubesun
You will be prompted for parameter values. Beware that not all
parameters are prompted for: some of the parameter are "hidden".
If you want to change one of the "hidden" parameters you should
specify its value on the command line. For example if you do not
want to overwrite the existing output file, type on the command
line:
> gtltcubesun clobber=no
An example of how to run the tool is given below:
> gtltcubesun
Event data file [] : events.fits
Spacecraft data file [] : spacecraft_data_file.fits
Output file [expCube.fits] :
Name of solar system body [SUN, MOON][SUN] :
Step size in cos(theta) (0.:1.) [0.025] :
Maximum angle in theta_sun (0.:180.) [180]:
Pixel size (degrees)[0.5] :
Working on file spacecraft_data_file.fits
That last example could be also run in the command line as follows:
>gtltcubesun evfile=events.fits scfile=spacecraft_data_file.fits body=SUN \
outfile=expCubeSun.fits dcostheta=0.025 thetasunmax=180 binsz=0.5
Note that the hidden parameters tmin and tmax can be used to split the
calculation into smaller time bins.
SEE ALSO
gtltcube
gtexphpsun
gtltsumsun
gtsuntemp