NAME
    gtbin - Bins GBM or LAT event lists in time, energy,
    and/or space to produce light-curves, spectra, count cubes or
    count maps, respectively.

USAGE

    gtbin evfile scfile outfile algorithm ebinalg emin emax enumbins
    denergy ebinfile tbinalg tstart tstop dtime tbinfile snratio lcemin
    lcemax nxpix nypix binsz coordsys xref yref axisrot proj


DESCRIPTION

    gtbin is a general purpose tool that performs one of three related
    event-binning tasks:

    Spectra:
    Events can be binned into a single spectrum, resulting in a type-I PHA
    file, or into a time-sequenced series of spectra in a single FITS
    file, resulting in a type-II PHA file. For a description of OGIP
    standards PHA files refer to:
    http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/node5.html).
    The type-II pha files are intended primarily for GBM data analysis.

    The energy binning can be:
    Provided by a user-specified file created by a previous gtbin run or
    by the gtbindef tool (see the gtbindef help). You are also able to
    select linear or logarithmic energy binning by selecting the binning
    algorithm type using the "ebinalg" parameter (see the "PARAMETERS"
    section below).  When a single spectrum is created (type-I pha file),
    all events in the event file are used--a user-specified TSTART and
    TSTOP WILL BE IGNORED.

    The time binning (when a type II PHA file is created) can be:
    Provided by a user-specified file created by a previous gtbin run
    (or by gtbindef), or the user can select linear time bins as well as
    constant signal-to-noise ratio per time interval (see the "tbinalg"
    parameter description below). Note the TSTART and TSTOP parameters
    will be ignored when spectral binning made is selected.
    PHA1 bins all the event data and does not provide for time cuts.

    Light Curves:
    The gtbin tool provides the option to generate light curves from event
    data. The time binning can be:
    (i) Determined by the user by specifying the time binning algorithm
    (tbinalg). The choices of binning are Linear binning (LIN), binning
    using a constant S/N ratio (SNR), or from an ascii file,
    (ii) Provided by a user-specified file created by a previous gtbin run,
    or
    (ii) Produced by gtbindef (tbinalg=FILE), in which case the user can
    select linear time bins definitions (tbinalg=LIN), or constant
    signal-to-noise ratio per time bin (tbinalg=SNR. See the "tbinalg"
    parameter description below).
    All the events between user specified TSTART and TSTOP are used.

    Count Map/Count Cube:
    Count maps (2-D images) or Count Cubes, a 3-D data cube (spatial +
    energy), can also be created by gtbin. The events are binned into
    user-specified rectangular pixels (see the description of the
    parameters "nxpix", "nypix", "binsz" in the PARAMETERS section
    below). For sky X-Y projected coordinates use algorithm=CMAP. This
    will produce a single two-dimensional spatial count map. A counts cube
    is created by stacking maps generated in projected sky coordinates
    using various energy slices using the algorithm=CCUBE.  This data cube
    is used in binned likelihood analysis. Many different projection
    methods are available (anything provided by the wcslib using the three
    letter identifiers): Aitoff [AIT], Zenithal equal- area [ZEA],
    Zenithal equidistant [ARC], Plate Carree [CAR], Sanson-Flamsteed
    [GLS], Mercator [MER], North-Celestial-Pole [NCP], Slant orthographic
    [SIN], Stereographic [STG], Gnomonic [TAN].  See Calabretta & Greisen
    2002, A&A, 395, 1077 for definitions of the projections. The resulting
    count map can then be viewed graphically, e.g., by fv or ds9
    (http://hea-www.harvard.edu/RD/ds9/).



PARAMETERS

General Parameters

    algorithm [string: CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX]
    Indicates which specific type of binning to perform by indicating the
    type of output file produced. Legal values are CCUBE (a data cube
    with one or more count maps binned in sky X-Y projected coordinates
    with the z-axis corresponding to different energy bins), CMAP (count
    map binned in sky X-Y projected coordinates), LC (light curve binned
    in time only), PHA1 (spectrum binned in energy), PHA2 (spectra
    binned in energy for a series of time ranges/bins), and HEALPIX
    (event binning algorithm. For small pixels sizes and large areas of
    the sky, HEALPix is a superior binning scheme for convolutions with PSFs.
    See http://healpix.jpl.nasa.gov/html/intronode4.htm for more info).
    CCUBE and CMAP are not applicable to GBM TTE data since they do not
    have a spatial dependence.  PHA1 does not provide time cuts and thus
    bins all the event data.

    evfile [file]
    Name of input event FITS file. This is the file containing the event
    data.

    outfile [file]
    Name of output FITS file, whose contents are determined by the
    algorithm parameter: count cube, count map, light curve or spectra.

    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) or more commonly it can be obtained from the FSSC
    website. Default is NONE.

    The spacecraft file is used to compute the exposure when binning the
    LAT data and is needed when creating spectra but is used in creating
    maps as well.
    The exposure for the GBM data are computed using a different method
    and does not use a spacecraft data file, thus this parameter should be
    set to 'none'.

    Time binning parameters:

    tbinalg [string: FILE|LIN|SNR]
    Indicates how the time bins will be specified. Legal values are FILE
    (bins will be read from a bin definition file), LIN (linearly uniform
    bins), and SNR (signal-to-noise ratio) per time bin. This parameter is
    only used if the output type requires binning in the time domain, that
    is, if the "algorithm" parameter is LC or PHA2.
    SNR binning has not yet been implemented.

    tstart [double]
    The start time of the first interval for linearly uniform bins in
    mission elapsed time (MET) seconds. Only used if tbinalg is LIN and if
    the output type requires time binning (LC and PHA2, see tbinalg).
    Note that tstart is not applicable to PHA1 binning.

    tstop [double]
    The stop time of the last interval for linearly uniform bins in MET
    seconds. Only used if tbinalg is LIN and if the output type requires
    time binning (LC and PHA2, see tbinalg).
    Note that tstop is not applicable to PHA1 binning.

    dtime [double]
    The width of linearly uniform bins in units of seconds. This option is
    used only if tbinalg is LIN and if the output type requires time
    binning (see tbinalg).

    tbinfile [file]
    The name of the optional time bin definition file. This file is
    created by the gtbindef tool (see the gtbindef documentation).
    This option is used only if tbinalg is FILE and if the output
    type requires time binning (see tbinalg).
    Note that tbinfile is applicable to PHA2 binning but not to
    PHA1 binning.

    snratio [double]
    Signal-to-noise ratio per time bin. This parameter is only used if
    tbinalg is SNR and if the output type requires time binning (see
    tbinalg). This option is not fully implemented yet.

    lcemin [double]
    Lower bound of energy range (in MeV) used to determine the bins in
    signal-to-noise binning. Note that all events in the input file will
    be binned, but only events that are in the range [lcemin, lcemax]
    contribute to the signal statistics for purposes of determining when
    to start a new time bin. This option is used only if SNR was selected
    in tbinalg and if the output type requires time binning (see tbinalg).
    Note that SNR binning has not yet been implemented.

    lcemax [double]
    Upper bound of energy range (in MeV) used to determine the bins in
    signal-to-noise binning. Note that all events in the input file will
    be binned, but only events that are in the range [lcemin, lcemax]
    contribute to the signal statistics for purposes of determining when
    to start a new bin. This option is used only if SNR was selected in
    tbinalg and if the output type requires time binning (see tbinalg).
    Note that SNR binning has not yet been implemented.

    Spatial binning Parameters:

    nxpix [integer]
    The number of pixels in the horizontal dimension in output image. This
    parameter is used only if the parameter "algorithm" is CMAP or CCUBE.

    nypix [integer]
    The number of pixels in the vertical dimension in output image. This
    parameter is used only if the parameter "algorithm" is CMAP or CCUBE.

    binsz [double]
    The number of degrees per pixel at the center of the image. This
    parameter is used only if the parameter "algorithm" is CMAP or CCUBE.

    xref [double]
    The horizontal position of the center of the image, either RA in
    celestial coordinates or l in galactic coordinates. This parameter is
    used only if the parameter "algorithm" is CMAP or CCUBE.

    yref [double]
    The vertical position of the center of the image, either DEC in
    celestial coordinates or b in galactic coordinates. This parameter is
    used only if the parameter "algorithm" is CMAP or CCUBE.

    axisrot [double]
    The rotation angle desired for the image. This parameter is used only
    if the parameter "algorithm" is CMAP or CCUBE.

    proj [string: AIT|ZEA|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN or any
    other three letter identifier recognized by wcslib]
    Coordinate projection (AIT|ZEA|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN); see
    Calabretta & Greisen 2002, A&A, 395, 1077 for definitions of the
    projections.  Must be AIT, ZEA, or CAR for auto full sky. This
    parameter is only used if the parameter "algorithm" is CMAP or CCUBE.

    coordsys [bool: CEL|GAL]
    Coordinate system. If you choose CEL you will be prompted for ra and
    dec (J2000), if you choose GAL you will be prompted for l and b
    coordinates. This parameter is used only if the parameter "algorithm"
    is CMAP or CCUBE.

    hpx_ordering_scheme [string: RING|NESTED]
    Ordering Scheme for the binning (see
    http://healpix.jpl.nasa.gov/html/intronode4.htm for more info)
    
    hpx_order [integer]
    Order of the map (integer between 0 and 12, included), corresponding to
    the level of pixelization or resolution.

    hpx_ebin [boolean]
    Apply energy binning to the count maps/cubes.

    hpx_region [string]
    Region, leave empty for all-sky

    Energy Binning Parameters

    ebinalg [string: FILE|LIN|LOG]
    Indicates how the energy bins will be specified. Legal values are FILE
    (bin boundaries will be read from a bin definition file), LIN
    (linearly uniform bins are used), or LOG (logarithmically uniform bins).
    This parameter is applicable only if the output type requires energy
    binning, that is, if the "algorithm" parameter is PHA1, PHA2, or CCUBE.

    emin [double]
    The lowest energy of the first interval for linearly or
    logarithmically uniform bins. Only used if ebinalg is LIN or LOG and
    if the output type requires energy binning (see ebinalg).
    Default is 30 MeV.

    emax [double]
    The highest energy of the last interval for linearly or
    logarithmically uniform bins. Only used if ebinalg is LIN or LOG and
    if the output type requires energy binning (see ebinalg).
    Default is 200 GeV.

    enumbins [integer]
    The number of bins for logarithmically uniform bins. Only used if
    ebinalg is LOG and if the output type requires energy binning (see
    ebinalg).

    denergy [double]
    The width of linearly uniform bins. Only used if ebinalg is LIN and if
    the output type requires energy binning (see ebinalg).

    ebinfile [file]
    The name of the energy bin definition file. Only used if ebinalg is
    FILE and if the output type requires energy binning (see ebinalg).


    Hidden parameters:

    (efield = ENERGY) [string]
    This is the name of the field containing the energy values for energy
    binning. The default value is consistent with the Fermi/LAT event file
    format.

    (tfield = TIME) [string]
    This is the name of the field containing the time values for time
    binning. The default value is consistent with the Fermi/LAT event file
    format.

    (rafield = RA) [string]
    The field in the input file which contains the RA (count maps
    only). The default value is the one used in Fermi/LAT event files.

    (decfield = DEC) [string]
    The field in the input file which contains the DEC (count maps
    only). The default value is the one used in Fermi/LAT event files.

    (evtable = EVENTS) [string]
    Event table extension name. The default value is consistent with the
    Fermi/LAT event file format.

    (sctable = SC_DATA) [string]
    Spacecraft data extension. The default value is consistent with the
    Fermi/LAT event file format.

    (chatter = 2)   [integer]
    This parameter fixes the output verbosity: no screen output (0),
    nominal screen output (2), maximum verbosity (4).

    (clobber = yes)  [string]
    Overwrite or do not overwrite existing output files.

    (debug = no)  [string]
    Activate debugging mode. 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 activated if "yes" is
    specified.

    (mode = ql)
    Mode of automatic parameters.


EXAMPLES

    The way that the parameters are passed follows the FTOOLs model: They
    could be passed by answering from a prompt, as a list in a command
    line, or by editing the parameter file. The command line option
    facilitates calling gtbin from a script.

    To be prompted for gtbin simply type in the command line:

    >gtbin

    This will prompt for parameter values. Beware that not all parameters
    are prompted: some of the parameters 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 you should type in the command line:

    >gtbin clobber=no

    Keep in mind that gtbin has several options to create different
    outputs, so some parameters are specific for each option. Some
    examples are given below to create count maps, light curves and
    spectra.


    Example 1: How to create a count map (CMAP):

    An example of how to run gtbin to create a count map is given below:


    > gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2] CMAP
    Event data file name[] events_filtered.fits
    Output file name[] counts_map.fits
    Spacecraft data file name[NONE]
    Size of the X axis in pixels[] 120
    Size of the Y axis in pixels[] 120
    Image scale (in degrees/pixel)[] 0.25
    Coordinate system (CEL - celestial, GAL -galactic) (CEL|GAL) [CEL]
    First coordinate of image center in degrees (RA or galactic l)[] 193.98
    Second coordinate of image center in degrees (DEC or galactic b)[] -5.82
    Rotation angle of image axis, in degrees[0.]
    Projection method e.g. AIT|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN:[AIT]


    In this example the algorithm used is CMAP (algorithm = CMAP), which
    create a counts map. The input event FITS file name is:
    events_filtered.fits while the output FITS file name is:
    counts_map.fits). The coordinate system is celestial (coordsys
    = CEL) and the center of the map is at coordinates: RA=193.98,
    DEC=-5.82. The projection method is AIT (proj = AIT) and the data is
    not rotated about the image center (axisrot = 0). The dimensions of
    the map are 120x120 pixels (nxpix = 120, nypix = 120) with a scale of
    0.25 degrees/pixel (binsz = 0.25). The spacecraft data file is not needed
    to create a counts map.

    That last example can also be run in the command line:

    > gtbin evfile=events_filtered.fits \
      scfile=NONE outfile=counts_map.fits \
      algorithm=CMAP nxpix=120 nypix=120 binsz=0.25 coordsys=CEL \
      xref=193.98 yref=-5.82 axisrot=0 proj=AIT

    Note: This has to be run on a single line and the \ is the Unix
    continuation character.


    Example 2: How to create a counts map with different energy bins (CCUBE MAP):

    An example of how to run gtbin to create a count map for different
    energy bins is given below:

    > gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2] CCUBE
    Event data file name[] _3C279_3C273_back_filtered.fits
    Output file name[] counts_map_3D.fits
    Spacecraft data file name[NONE]
    Size of the X axis in pixels[] 120
    Size of the Y axis in pixels[] 120
    Image scale (in degrees/pixel)[] 0.25
    Coordinate system (CEL - celestial, GAL -galactic) (CEL|GAL) [CEL]
    First coordinate of image center in degrees (RA or galactic l)[] 193.98
    Second coordinate of image center in degrees (DEC or galactic b)[] -5.82
    Rotation angle of image axis, in degrees[0.]
    Projection method e.g. AIT|ARC|CAR|GLS|MER|NCP|SIN|STG|TAN:[AIT]
    Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
    Start value for first energy bin in MeV[30]
    Stop value for last energy bin in MeV[200000]
    Number of logarithmically uniform energy bins[] 21

    In this example the algorithm used is CCUBE (algorithm = CCUBE), which
    creates a counts map for different energy bins. The input event FITS
    file name is: events_filtered.fits while the output FITS file name is:
    counts_map_3D.fits. In this case the energy bins are
    logarithmic (ebinalg = LOG) and 21 bins were selected (enumbins =
    21). The initial energy for the first bin is 30 MeV (emin = 30) while
    the last energy for the last bin is 200000 MeV (emax = 200000). The
    coordinate system is celestial (coordsys = CEL) and the center of the
    map is at coordinates: RA=193.98, DEC=-5.82. The projection method is
    AIT (proj = AIT) and the image is not rotated (axisrot = 0). The
    dimensions of the map are 120x120 pixels (nxpix = 120, nypix = 120) with a
    scale of 0.25 degrees/pixel (binsz = 0.25).


    That last example could be also run in the command line:

    > gtbin evfile=events_filtered.fits \
      scfile=NONE outfile=counts_map_3D.fits \
      algorithm=CCUBE ebinalg=LOG emin=30 emax=200000 enumbins=21 \
      nxpix=120 nypix=120 binsz=0.25 coordsys=CEL xref=193.98 yref=-5.82 \
      axisrot=0 proj=AIT

    Note: This has to be run on a single line and the \ is the unix
    continuation character.

    Example 3: How to create a light curve

    An example of how to run gtbin to create light curves is given below:

    > gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2] LC
    Event data file name[]  events_filtered.fits
    Output file name[] lc.fits
    Spacecraft data file name[NONE]
    Algorithm for defining time bins (FILE|LIN|SNR) [LIN]
    Start value for first time bin in MET[] 252390000
    Stop value for last time bin in MET[] 254966400
    Width of linearly uniform time bins in MET[] 20000

    In this case the event FITS input file is called
    events_filtered.fits, the output file with the
    light curve is called lc.fits . The algorithm used is LC,
    which creates the light curve (algorithm = LC). The time bins are
    linear (tbinalg = LIN) with steps of 20000 MET seconds (dtime =
    20000). The start time is 252390000 MET seconds (tstart = 252390000)
    and the stop time is 254966400 MET seconds (tstop = 254966400).
    Note that the valid range of MET values can be obtained from the
    event file FITS header, e.g. fkey prints events FITS TSTARTS or
    similar for TSTOP. The equivalent UT dates are contained in
     the "DATE-OBS" keyword, which can be similarly obtained.
    Since the output is not an image, but rather a table of values, you
    may look at it with fv
    (http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/) instead of ds9.

    That last example could be also run in the command line in this way:

    > gtbin evfile=events_filtered.fits \
      scfile=NONE outfile=lc.fits \
      algorithm=LC tbinalg=LIN tstart=252390000 tstop=254966400 \
      dtime=20000

    Note: This has to be run on a single line and the \ is the unix
    continuation character.

    Example 4: How to create a light curve with GBM data:

    An example of how to run gtbin to create a light curve with the GBM
    data is given below:

    prompt> gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2] LC
    Event data file name [ ] : GLG_TTE_N0_BN080104514_V01.FIT
    Output file name [ ] : GRB_080104A_N0_lc.fit
    Spacecraft data file name [NONE] :
    Algorithm for defining time bins  [LIN] :
    Start value for first time bin [ ] : 221142009
    Stop value for last time bin [ ] : 221142055
    Width of linearly uniform time bins [ ] :  0.25

    In this example the algorithm to create a light curve is selected
    (algorithm = LC). The input event data file is called
    GLG_TTE_N0_BN080104514_V01.FIT (evfile =
    GLG_TTE_N0_BN080104514_V01.FIT), which is a GBM time-tagged event data
    file. The output file name is GRB_080104A_N0_lc.fit (outfile =
    GRB_080104A_N0_lc.fit). A spacecraft file is not needed. The start and
    stop time of the bins are 221142009 and 221142055 MET seconds
    respectively (tstart = 221142009, tstop =221142055). Since linear bins
    were selected (tbinalg = LIN), gtbin prompts for the width of the bins
    in seconds; here 0.25 seconds bin is selected (dtime = 0.25).  Since
    the output is not an image, but rather a table of values, you may examine
    it with fv (http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/).


    Example 5: How to create a spectrum averaged over a single time interval:

    An example of how to run gtbin to create a spectrum (PHA1):

    > gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2] PHA1
    Event data file name [ ] : events.fits
    Output file name [ ] : pha1.fits
    Spacecraft data file name [ ] : SC00.fits
    Algorithm for defining energy bins <FILE|LIN|LOG> [LOG] :
    Start value for first energy bin in MeV [30] :
    Stop value for last energy bin in MeV [200000] :
    Number of logarithmically uniform energy bins [ ] : 20

    In this example the energy spectra of the quasar 3C279 is
    generated. Previously the tool gtselect (see the gtselect
    documentation) was run in order to select a small region (of 4 degrees
    radius) of the sky around the 3C279 coordinates (193.98, -5.82) before
    running gtbin. An energy spectra between 30 MeV (emin = 30) and 200000
    MeV (emax = 200000) of 20 (enumbins = 20) logarithmic bins (ebinalg =
    LOG) is produced. You can examine the spectra using, for example, the
    fv tool
    (http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/).


    Example 6: How to create set of spectra over multiple time bins:

    An example of how to run gtbin to create set of spectra over multiple
    time bins (type-II PHA) is given below:

    > gtbin
    This is gtbin version ScienceTools-v9r33p0-fssc-20140317
    Type of output file (CCUBE|CMAP|LC|PHA1|PHA2|HEALPIX) [PHA2]
    Event data file name [ ] : events.fits
    Output file name [ ] : pha2.fits
    Spacecraft data file name [ ] : SC00.fits
    Algorithm for defining energy bins <FILE|LIN|LOG> [LOG] :
    Start value for first energy bin in MeV [30] :
    Stop value for last energy bin in MeV [200000] :
    Number of logarithmically uniform energy bins [ ] : 20
    Algorithm for defining time bins <FILE|LIN|SNR> [LIN] :
    Start value for first time bin in MET [ ] : 252390000
    Stop value for last time bin in MET [ ] : 254966400
    Width of linearly uniform time bins in MET [ ] : 20000

    In this example a PHA2 file is created with spectra of the quasar
    3C279 for every 20000 seconds.  Spectra between 30 MeV (emin = 30) and
    200000 MeV (emax = 200000) with 20 (enumbins = 20) logarithmic bins
    (ebinalg = LOG) is produced. Spectra are created for every 20000
    second interval (tbinalg = LIN and dtime = 20000), starting from
    252390000 MET seconds (tstart = 252390000) and ending at 254966400 MET
    seconds (tstop = 254966400). The user should be aware that if the last
    time time does not span the full 20000 seconds then the last time bin
    may contain much less than what is requested. You may examine the
    spectra produced using the fv tool
    (http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/).


KNOWN BUGS


    The signal-to-noise binning is not fully implemented. When using
    constant signal-to-noise binning (tbinalg = SNR) currently the
    parameters lcemin and lcemax are ignored. It is not possible to enter
    the background spectra file for the SNR option yet.

    Because gtbin has many "conditional" parameters (parameters that are
    used for some types of output and not for others) the order of
    parameter prompts does not match the order for parameters supplied
    positionally on the command line. When using positional parameters it
    is necessary to supply all parameters, even those that are not used in
    the current tool mode.

SEE ALSO

    * gtbindef
    * gtselect
