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