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
