Home

gtBurst has been written by Giacomo Vianello (giacomov@slac.stanford.edu), with some help from Nicola Omodei (nicola.omodei@stanford.edu).

Table of contents:

• Introduction
• Fermi data analysis: required pre-knowledge
• Installation
  • Install the HEASARC FTOOLS package
  • Install the Fermi Science Tools
  • Initial set up
    • Download the trimmed version of the Galactic template file
    • Set the environment variables
    • Test your installation
• The GUI
  • Main interface
  • Tasks
  • The log file
• Using gtBurst
  • Downloading data
    • Where are my data?
  • Loading data
  • Likelihood analysis
• Scripting gtBurst

Introduction

gtBurst is a Graphical User Interface (GUI) which allows you to study Gamma-Ray Bursts, solar flares and other sources detected by the Large Area Telescope (LAT) onboard Fermi.

It is based on the official Fermi/LAT data analysis software (Fermi Science Tools), and it is now distributed with it.

With gtBurst you can accomplish many common analysis tasks (spectral analysis, detection and so on...) with just few clicks, instead of many long and complex command lines.

Fermi data analysis: required pre-knowledge

In order to understand what you will be doing with gtBurst you need to know some general concepts related to Fermi and the framework for the Maximum Likelihood analysis. If you are not very familiar with these arguments, please read the following documentation before continuing:

IRF overview
Likelihood analysis overview

Installation

Install the HEASARC FTOOLS package

In order for gtBurst to work you will need a recent version of the FTOOLS ([http://heasarc.gsfc.nasa.gov/lheasoft/download.html]). Most probably, if you already work as an X-ray or Gamma-Ray astronomer, you already have this. If you are not sure, check with your system administrator.

Install the Fermi Science Tools

gtBurst comes now with the Fermi Science Tools. If you haven't yet, download and install the latest release of the ST following carefully the instructions at [http://fermi.gsfc.nasa.gov/ssc/data/analysis/software/] or ask your system administrator.

Initial set up

Download the trimmed version of the Galactic template file

Unless you have a very powerful computer with a lot of RAM memory, you will be better off by downloading a reduced version of the Galactic Template.

First of all you have to figure out where to save it. Open a terminal, and write:

user@localhost:~> echo $FERMI_DIR
/home/grb/software/ScienceTools-v9r31p1-fssc-20130410-build/i686-pc-linux-gnu-libc2.12

In this case, the path we are looking for is /home/grb/software/ScienceTools-v9r31p1-fssc-20130410-build/i686-pc-linux-gnu-libc2.12.

Now go to this page and download the file "gal_2yearp7v6_trim_v0.fits" (NOTE the "trim" part!), saving it in the directory we just found (/home/grb/software/ScienceTools-v9r31p1-fssc-20130410-build/i686-pc-linux-gnu-libc2.12 in my case).

Set the environment variables

gtBurst will need to find the Isotropic Template file and the Galactic Template file you downloaded in the previous step in order to perform a Likelihood analysis. Therefore, you have to set the environment variables ISOTROPIC_TEMPLATE and GALACTIC_DIFFUSE_TEMPLATE accordingly. If you are using a csh/tcsh shell, just write:

user@localhost:~> setenv ISOTROPIC_TEMPLATE $FERMI_DIR/refdata/fermi/galdiffuse/isotrop_2year_P76_source_v0.txt
user@localhost:~> setenv GALACTIC_DIFFUSE_TEMPLATE $FERMI_DIR/refdata/fermi/galdiffuse/gal_2yearp7v6_trim_v0.fits

while for a bash shell write:

user@localhost:~> export ISOTROPIC_TEMPLATE=$FERMI_DIR/refdata/fermi/galdiffuse/isotrop_2year_P76_source_v0.txt
user@localhost:~> export GALACTIC_DIFFUSE_TEMPLATE=$FERMI_DIR/refdata/fermi/galdiffuse/gal_2yearp7v6_trim_v0.fits

You would be probably better off by inserting this instructions at the end of your init script, after the initialization of the Fermi Science Tools, so you don't have to repeat these steps every time you want to run gtBurst.

Test your installation

You can now verify your installation by running the gtburstInstTest.py script:

user@localhost:~> gtburstInstTest.py
Testing Science Tools Python wrappers... ok
Testing environment variables... ok
Testing likelihood templates for read access...
  GALACTIC_DIFFUSE_TEMPLATE... Using /home/grb/software/ScienceTools-v9r31p1-fssc-20130410-build/i686-pc-linux-gnu-libc2.12/refdata/fermi/galdiffuse/gal_2yearp7v6_trim_v0.fits
  ISOTROPIC_TEMPLATE... Using /home/grb/software/ScienceTools-v9r31p1-fssc-20130410-build/i686-pc-linux-gnu-libc2.12/refdata/fermi/galdiffuse/isotrop_2year_P76_source_v0.txt
Testing gtBurst GUI...

Loading pyBurstAnalysisGUI v. 01-00-00p3 .....This is gtllebin (pyBurstAnalysisGUI 01-00-00p3)

..... done 

If you get any error, verify that you have followed carefully all the previous steps.

The GUI

You can run gtBurst by issuing the following command in a shell:

user@localhost:~> gtburst

After a few seconds you should see the main interface.

Main interface

The main interface of gtBurst is made by:

1. a Menu bar (top)
2. the Form panel (mid-left), which will contain information about the loaded trigger (when you will have one) in the main window, and the parameters for the current task when you are running analysis.
3. the Help panel (bottom left), which will always contain useful information on what to do. Please always read this!
4. the Figure panel (center right), which will contains plots and images. At the beginning, it just contains a picture of the Fermi spacecraft.
5. the Console panel (bottom right, with white background color): this will contain the output of all the commands run by the interface. Everything appears here will also be saved to the log file (see below). You can scroll up and down by using the scroll bar.

Tasks

The Tasks menu contains the high-level tasks which the interface is capable of doing, once you have loaded the appropriate data type (for example, if you load just GBM data, you cannot do Likelihood analysis on them and the corresponding task will be inactive).

Each task consists of a number of steps. Each step require a certain number of parameters (see below), which will be asked for in a form in the Form panel. For example, this is step 1 of 4 for the Likelihood analysis task:

Each time you are in doubt about what a given parameter means, you can click on the question mark button on the side of the form and a brief help will give you the explanation you need.

Once you have completed the form, you can click Run to complete the step. If you are satisfied with the result, you can then click Next to pass to the next step. You can also go back to previous steps by using the Back button, or cancel the task altogether by clicking Cancel.

The log file

All the messages which are output in the Console window are also saved in the file "gtburst.log" in the directory in which gtBurst has been launched. You can use this log to figure out what you run to obtain a certain input, or to ask for help.

WARNING: If a file gtburst.log is already present in the directory in which you are running gtBurst, it will be overwritten silently. Therefore, if you want to save your output, rename the gtburst.log file before starting a new session of gtBurst.

Using gtBurst

Downloading data

The first thing you want to do is to download some data to play with. From the Main interface, choose "Download datasets" from the File menu: a new window will appear.

You have now two options

1. Using the Trigger list: the easiest option is to click on the "Browse triggers" button in the new window, which will download from the HEASARC website the list of all bursts which triggered Fermi and it will display it.
   You can navigate this list by using the scroll bar. You can also filter the list by trigger type by selecting a class of triggers from the drop down menu "Trigger type filter" in the top part of the list window. Finally, you can order the various columns of the list by clicking on the relative heading: one click will place that column in increasing order, another click in decreasing order.
   From that list, you can then choose the trigger you are interested into by clicking on it and clicking "Done". At this point all the entries in the form will have been filled up automatically.

2. Manually specifying the trigger properties: another option is for you to fill the form manually, by specifying a Trigger name (whatever you want), a trigger time (in Mission Elapsed Time, see here), and the coordinates of the source (R.A. and Dec, in J2000).

Independently of the method chosen to fill the form, you have to select which type of data you want to download: GBM burst data (see here), Fermi/LAT LLE data (see here), or Fermi standard data (see here). You can select one or more data types by checking the corresponding entry.

Then click on the "Download" button.

If you have selected LAT standard data, a window will ask you how many seconds of data you want to download after the trigger time. 10 thousands seconds is the pre-defined value.

If you have selected GBM burst data, another window will ask you which kind of data you want to download: usually you will need CSPEC, TTE and RSP data which are selected by default. If you want, you can download CTIME data as well, even they are NOT handled by gtBurst. Note that you will always need CSPEC data, therefore you cannot uncheck them. For info about this data types, see again here.

You then will have to wait for the data to be downloaded. Progress bars will help you understanding how much time it will take.

At the end of the download, gtBurst will automatically start the loading process (see below the "Loading data" section, starting from point 2)

NOTE: the Download function is very convenient and works decently well if and only if your internet connection is stable. If it is not, you might need to try a couple of times. In that case, it is advised to download one data class (GBM, LLE or LAT standard) at the time.

Where are my data?

Data are downloaded by default in a FermiData subdirectory under your home (~/FermiData in Linux). Each trigger has its own subdirectory inside that. So for example, if we download the data for trigger bn080916009, data will be in ~/FermiData/bn080916009.

Loading data

To load data you have to:

1. Either download some data (see "Downloading data" above) OR, if you have downloaded already the data you want to analyze, select "Load data from a directory" from the File menu. In this second case, you will be prompted to choose the directory containing the data you want to load. For example, if you downloaded the data for trigger bn080916009 in a previous session and you want to load them, you will have to double click on the directory bn080916009. In some system double clicking will be enough, in other after double clicking you will have to click Ok as well. (see also "where are my data?" above)
2. You will see the "Select datasets" window, which contains a checklist of all available detectors (i.e., detectors for which you have downloaded data). This is one example:
   
   In parenthesis you can find the angle between each detector and the source. Select datasets to use for your analysis. Pre-selected detectors are NaIs closer than 50 deg to the source, the closest BGO of the two and the LAT (if present). Click Ok.
3. A light curve will be displayed in the Figure panel for each detector you have chosen.

You can of course repeat this procedure if you want to change the selection of detectors.

Certain specialized analysis could need to load files which have not been produced or downloaded through gtBurst. You can do so by selecting "Load a custom dataset" from the File menu. You will have then to specify one by one the needed information. This is an advanced feature. Also, no check whatsoever will be performed on the consistency of the input files, which could lead to unexpected crashes, so be careful.

Likelihood analysis

If you have loaded LAT standard data, and you want to perform a Likelihood analysis, select "Likelihood analysis" from the Tasks menu. There are 4 steps:

1. Data cuts: here you apply cuts on the data. You have to choose the radius of the circular region of interest around the position of the source (rad parameter, in deg), the time and energy selections, and the IRF. For intervals shorter than 100 s it is usually best to use TRANSIENT class, while for longer intervals it is best to use the cleaner SOURCE class. You can use the function 'Make navigation plots' in the Tools menu to decide which Zenith cut it is best to apply. Remember that all time intervals for which even a part of the ROI has a Zenith angle larger than your threshold will be excluded from the analysis.

Scripting gtBurst

Project Admins:

• Giacomo Vianello