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 [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 [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 [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