Metadata-Version: 2.1
Name: PyGRB
Version: 1.0.2
Summary: A GRB light-curve analysis package.
Home-page: https://github.com/JamesPaynter/PyGRB
Author: James Paynter
Author-email: jims.astronomy@gmail.com
License: BSD-3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6.0, <3.9
Requires-Dist: numpy (>=1.18.1)
Requires-Dist: scipy (>=1.1.0)
Requires-Dist: matplotlib (>=2.2.3)
Requires-Dist: astropy (>=3.2.3)
Requires-Dist: xlrd (>=1.1.0)
Requires-Dist: prettytable (>=0.7.2)
Requires-Dist: pandas (>=1.0.1)
Requires-Dist: beautifulsoup4 (>=4.9.0)
Requires-Dist: bilby (==0.5.9)
Requires-Dist: nestle (>=0.2.0)

|JOSS| |Travis| |Coverage| |Docs| |pypi| |version| |AstroPy|

.. image:: https://github.com/JamesPaynter/PyGRB/blob/master/docs/source/images/logo.png
    :align: center
    :alt: PyGRB logo

.. inclusion-marker-one-liner-start

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

.. inclusion-marker-one-liner-end



.. inclusion-marker-what-it-does-start

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 <https://heasarc.gsfc.nasa.gov/FTP/compton/data/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 <https://lscsoft.docs.ligo.org/bilby/index.html>`__, and `Dynesty <https://dynesty.readthedocs.io/>`__ and/or `Nestle <https://github.com/kbarbary/nestle>`__.


Installation
^^^^^^^^^^^^
The *PyGRB* repository maybe be installed manually through cloning the repository

.. code-block:: console

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

or by downloading the compiled version from `PyPI <https://pypi.org/project/PyGRB/>`__

.. code-block:: console

  $ pip install pygrb


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

Then import *PyGRB* through ``import PyGRB``.

.. inclusion-marker-what-it-does-end


.. inclusion-marker-pulse-types-start

Pulse types
------------
Description of GRB pulse phenomenology.

.. image:: https://github.com/JamesPaynter/PyGRB/blob/master/docs/source/images/equations/FRED.gif
    :align: center
    :alt: FRED eqn: $I(t) = A \exp{ - \xi \left( \frac{t - \Delta}{\tau} + \frac{\tau}{t-\Delta} \right)}$


.. inclusion-marker-pulse-types-end

`See documentation for more <https://pygrb.readthedocs.io/en/latest/user/pulses.html>`__



.. role:: python(code)
   :language: python

.. image:: https://github.com/JamesPaynter/PyGRB/blob/master/docs/source/images/BATSE_trigger_7475_rates_rates.png
    :align: center
    :alt: BATSE trigger 7475


Usage
------

.. inclusion-marker-usage-start

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.

.. code-block:: python

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


The :python:`PulseFitter` class is the main workhorse of the software.

.. code-block:: python

  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 :python:`'T90'`, :python:`'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 :python:`nSamples` parameter determines how many live points the nested sampler is initiated with.
The :python:`sampler` parameter is used to choose between samplers.
The :python:`priors_pulse_start` and :python:`priors_pulse_end` parameters are used to set the (uniform) interval over which the program will allow the pulse start times.
The :python:`datatype` parameter specifies which kind of data we would like to download and analyse.
Typically :python:`'discsc'` is the most useful.
:python:`'tte'` is better for short GRBs.
The data will be downloaded and stored in :code:`data/`.



:python:`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

.. code-block:: python

  key = 'F'
  model = create_model_from_key(key)


Finally, we run the model through the sampler

.. code-block:: python

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


The data products are stored in :code:`products/`.


.. inclusion-marker-usage-end


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

.. image:: https://github.com/JamesPaynter/PyGRB/blob/master/docs/source/images/B_7475__d_NL200__rates_F.png
    :align: center
    :alt: BATSE trigger 7475


`See documentation for more <https://pygrb.readthedocs.io/en/latest/user/usage.html>`__


Under the Hood
---------------


.. image:: https://github.com/JamesPaynter/PyGRB/blob/master/docs/source/images/pulse_fit_animation.gif
    :align: center
    :alt: 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 <https://pygrb.readthedocs.io/en/latest/user/sampling.html>`__


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.

  - `Swift BAT <https://swift.gsfc.nasa.gov/results/batgrbcat/>`__

  - `Fermi GBM <https://heasarc.gsfc.nasa.gov/FTP/fermi/data/gbm/bursts/>`__

  - `Konus Wind <https://gcn.gsfc.nasa.gov/konus_grbs.html>`__

- Include capability to download and plot GRB spectra in addition to light-curves.

- Increase coverage to 100%



.. _GitHub Issue: https://github.com/JamesPaynter/PyGRB/issues

.. |AstroPy| image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
    :target: http://www.astropy.org/
    :alt: astropy

.. |Travis| image:: https://travis-ci.com/JamesPaynter/PyGRB.svg?branch=master
    :alt: Travis Badge
    :target: https://travis-ci.com/JamesPaynter/PyGRB

.. |Coverage| image:: https://codecov.io/gh/JamesPaynter/PyGRB/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/JamesPaynter/PyGRB
    :alt: CodeCov - Coverage Status

.. |Docs| image:: https://readthedocs.org/projects/pygrb/badge/?version=latest
    :target: https://pygrb.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. |pypi| image:: https://badge.fury.io/py/PyGRB.svg
    :target: https://badge.fury.io/py/PyGRB

.. |version| image:: https://img.shields.io/pypi/pyversions/pygrb.svg
    :target: https://pypi.org/project/pygrb/

.. |JOSS| image:: https://joss.theoj.org/papers/8aff0347e6993ec23b060052a80aaaa0/status.svg
    :target: https://joss.theoj.org/papers/8aff0347e6993ec23b060052a80aaaa0