Skip to content

JamesPaynter/PyGRB

Repository files navigation

JOSS DOI pypi version Travis Badge CodeCov - Coverage Status Documentation Status astropy

PyGRB logo

A gamma-ray burst (GRB) light-curve analysis package.

Introduction

PyGRB is a package to download gamma-ray burst (GRB) .FITS files from the relevant data archives (eg. NASA HEARSAC). At the moment only BATSE data can be downloaded and analysed with the software, although with only slight tweaks GRBs from other satellites can be easily analysed. The code is then able to create light-curves from either pre-binned data or time-tagged photon-event data. Light-curves may then be fitted with with pulse models, for further analysis. Model fitting is done with nested sampling, powered by Bilby, and Dynesty and/or Nestle.

Installation

PyGRB may be installed manually through cloning the repository

$ git clone https://github.com/JamesPaynter/PyGRB
$ cd PyGRB
$ pip install -r requirements.txt
$ pip install .

or by downloading the compiled version from PyPI

$ pip install pygrb

Installation of PyGRB and its dependencies should take no longer than a couple of minutes.

Then import PyGRB through import PyGRB.

Pulse types

Description of GRB pulse phenomenology.

FRED eqn: $I(t) = A \exp{ - \xi \left( \frac{t - \Delta}{\tau} + \frac{\tau}{t-\Delta} \right)}$

See documentation for more

BATSE trigger 7475

Usage

Say we would like to fit a GRB light-curve such as the above, and determine its pulse parameters. First we must load the relevant modules.

from PyGRB.main.fitpulse import PulseFitter
from PyGRB.backend.makemodels import create_model_from_key

The PulseFitter class is the main workhorse of the software.

GRB = PulseFitter(7475, times = (-2, 60),
          datatype = 'discsc', nSamples = 200, sampler = 'nestle',
          priors_pulse_start = -5, priors_pulse_end = 30)

The first argument specifies the BATSE trigger to be analysed, in this case trigger 7475. Times can either be specified as 'T90', 'full', or a tuple of start and end times. In the case of trigger 7475, most of the action happens over about (-2, 60), so we choose this interval for our times. The nSamples parameter determines how many live points the nested sampler is initiated with. The sampler parameter is used to choose between samplers. The priors_pulse_start and priors_pulse_end parameters are used to set the (uniform) interval over which the program will allow the pulse start times. The datatype parameter specifies which kind of data we would like to download and analyse. Typically 'discsc' is the most useful. 'tte' is better for short GRBs. The data will be downloaded and stored in data/.

create_model_from_key allows us to specify pulse models based on a simple key. The simple pulse type, a fast-rise exponential-decay (FRED) pulse, is utilised by

key = 'F'
model = create_model_from_key(key)

Finally, we run the model through the sampler

GRB.main_multi_channel(channels = [0, 1, 2, 3], model = model)

The data products are stored in products/.

We should be left with a light-curve that looks like this:

BATSE trigger 7475

See documentation for more

Under the Hood

a GRB light-curve fit animation

There is a typo in this animation, the two fractions should take the same sign (+ve). The -2 is an amplitude normalisation factor.

See documentation for more

Contribute

'PyGRB' is an open-source software package freely available under the BSD 3-Clause License. Users may request new features by opening a GitHub Issue, or may contribute their own additions and improvements via a pull request. Similarly, if you run into problems while using PyGRB, or require technical support, do not hesitate to request support through a GitHub Issue. If you use PyGRB in your work and would like to further collaborate on GRBs or gravitational lensing, I would be more than willing to discuss it over email or GitHub Issue.

An incomplete list of possible improvements:

  • Include support for uneven bin sizes and data gaps.
  • Include compatibility with other GRB catalogues that are publicly available.
  • Include capability to download and plot GRB spectra in addition to light-curves.
  • Increase coverage to 100%