gtbin Help File

Synopsis: Bins GBM or LAT events list in time, energy, and/or space to produce light curves, spectra, count cubes, or count maps.

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

The gtbin tool performs one of three related event-binning tasks:

Examples: gtbin

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.

Parameters are passed following the FTOOLs model: 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 parameter values, simply type in the command line: gtbin

Note: 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 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):

> gtbin  
This is gtbin version ScienceTools-09-15-02  
Type of output file (CCUBE|CMAP|LC|PHA1|PHA2) [PHA2] CMAP  
Event data file name[] events_filtered.fits  
Output file name[] count_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:

count_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 arotated about the image center
(axisrot = 0).

The size of the map is:

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 count map.

The previous example can be also run from the command line as shown below:

> gtbin evfile=events_filtered.fits \    
scfile=NONE outfile=count_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 count map with different energy bins (CCUBE MAP):

> gtbin  
This is gtbin version ScienceTools-09-15-02  
Type of output file (CCUBE|CMAP|LC|PHA1|PHA2) [PHA2] CCUBE  
Event data file name[] _3C279_3C273_back_filtered.fits  
Output file name[] count_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:

3C279_3C273_back_filtered.fits

while the output FITS file name is:

count_map_3D.fits

In this case, the energy bins are logarithm (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 there is no axis rotation
(axisrot = 0).

The size of the map is 120x120 pixels (nxpix = 120, nypix = 120), with a scale of 0.25 degrees/pixel (binsz = 0.25).

The spacecraft data file is not needed

The previous example can also be run from the command line as shown below:

> gtbin evfile=events_filtered.fits \    
scfile=NONE outfile=count_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-09-15-02  
Type of output file (CCUBE|CMAP|LC|PHA1|PHA2) [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 example:

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).

Since the output is not an image, but rather a table of values, you may look at it with fv instead of ds9.

That previous example could also be run from 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:

In this example:

The algorithm to create a light curve LC is selected (algorithm = LC).

The input event data file is called:

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

A spacecraft file is not needed.

The start and stop time of the bins are:

221142009 and 221142055 MET seconds, respectively.

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).

And, since the output is not an image, but rather a table of values, you may examine it with fv.

Example 5: How to create a spectrum over a single time bin:

In this example:

The energy spectra of the quasar 3C279 is generated.

Note: Previously, the gtselect tool was run in order to select a small region (4 degrees radius) of the sky around the 3C279 coordinates (193.98, -5.82). (See the gtselect documentation.)

An energy spectra between 30 MeV (emin = 30) and 200000 MeV (emax = 200000) of 20 (enumbins = 20) logarithmic bins (ebinalg = LOG) is produced. Use the fv tool to see the spectra.

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

> gtbin  
This is gtbin version ScienceTools-v09-15-02  
Type of output file (CCUBE|CMAP|LC|PHA1|PHA2) [PHA2]   
Event data file name [ ] : events.fits  
Output file name [ ] : pha2.fits  
Spacecraft data file name [NONE] :   
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).

Use the fv tool to view the spectra.

Note: If the tstop does not span the full 20000 seconds, the last time bin may contain much less than what is requested.