gtltcube Help File

Usage: gtltcube evfile scfile outfile dcostheta binsz

Calculates integrated livetime as a function of sky position and off-axis angle.

The LAT instrument response functions are a function of 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, gtltcube computes the livetime as a function of inclination and location on the sky for a specified observation period.

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 Science Analysis Environment (SAE) 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 of a sphere. This pixelization produces a subdivision of a spherical surface in which each pixel covers the same surface area as every other pixel. 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.

Users can generate their own livetime cubes using gtltcube tool, or – whenever possible in order to save calculation time – obtain precomputed livetime cubes from the SLAC Data Portal.

Since livetime cubes are additive, the livetime cube for a given epoch days can be calculated by adding the livetime cubes for non-overlapping time ranges that it comprises. The gtltsum tool can be used to add two or more livetime cubes together. (See gtltsum.)

Example: gtltcube

Parameters are passed following the FTOOLs model (i.e., they can be passed interactively by: answering a prompt; as a list in a command line; or by editing the parameter file).

To be prompted for gtltcube parameter values, enter (at the command line): gtltcube

Note: "Hidden" parameters are not prompted. If you want to change one of the "hidden" parameters, specify the values in the command line. For example, if you do not want to overwrite the output file, enter (at the command line): gtltcube clobber=no

An example of how to run gtltcube 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

The above example can also be run from the command line as follows:

>gtltcube evfile=events.fits scfile=spacecraft_data_file.fits
outfile=expCube.fits dcostheta=0.025 binsz=1

Owned by: J. Chiang


Last updated by: Chuck Patterson 01/18/2011