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
