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. LIST OF BUGS SEE ALSO gtltcube gtexphpsun gtltsumsun gtsuntemp