Merge pull request #34 from abatten/dev

Added NE2001 compatability (v1.1.0)
abatten · Aug 13, 2019 · 5ff2b96 · 5ff2b96
2 parents 57ba9c8 + 31d912a
commit 5ff2b96
Show file tree

Hide file tree

Showing 11 changed files with 251 additions and 69 deletions.
diff --git a/README.rst b/README.rst
@@ -29,6 +29,14 @@ If you are installing the latest development version of ``fruitbat`` then you
 will also need to install git-lfs. Instructions for installing git-lfs for
 your operating system can be found here_.
 
+Linux Users
+***********
+If you are installing ``fruitbat`` on a linux machine you may see this 'error':
+``ERROR: Failed building wheel for pyymw16``. This does not mean the installation
+failed. The C++ bindings were compiled using MacOS and needed to be recompiled
+for your machine. The installation process does this for you. You should still
+be able to run ``fruitbat`` normally.
+
 .. _PyPi: https://pypi.python.org/pypi/fruitbat 
 .. _here: https://help.github.com/en/articles/installing-git-large-file-storage
 
@@ -111,24 +119,33 @@ Referencing Fruitbat
 --------------------
 
 If you use ``fruitbat`` in your research, we would like it if you could
-reference our paper.
+reference `our paper`_.
+
+.. _our paper: https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1399B/abstract
 
 ::
 
-    @article{Batten2019,
-        author = {{Batten}, A.~J.},
-        title = {{Fruitbat}: A Python Package for Estimating Redshifts of Fast Radio Bursts},
-        doi = {10.21105/joss.01399},
-        url = {http://dx.doi.org/10.21105/joss.01399},
-        year  = {2019},
-        month = {may},
-        publisher = {The Open Journal},
-        volume = {4},
-        number = {36},
-        pages = {1399},
-        journal = {JOSS}
+    @ARTICLE{2019JOSS....4.1399B,
+           author = {{Batten}, Adam},
+            title = "{Fruitbat: A Python Package for Estimating Redshifts of Fast Radio Bursts}",
+          journal = {The Journal of Open Source Software},
+         keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - High Energy Astrophysical Phenomena},
+             year = "2019",
+            month = "May",
+           volume = {4},
+           number = {37},
+            pages = {1399},
+              doi = {10.21105/joss.01399},
+    archivePrefix = {arXiv},
+           eprint = {1905.04294},
+     primaryClass = {astro-ph.IM},
+           adsurl = {https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1399B},
+          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
     }
 
+
+
+
 .. |Logo| image:: logo/fruitbat_logo.svg
     :alt: Fruitbat Logo
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,6 +14,7 @@
 #
 import os
 import sys
+import re
 sys.path.insert(0, os.path.abspath('../../'))
 
 
@@ -23,10 +24,22 @@
 copyright = '2019, Adam Batten'
 author = 'Adam Batten'
 
+def get_version():
+    here = os.path.abspath(os.path.dirname(__file__))
+    version_file = os.path.join(here, '../../fruitbat', '__version__.py')
+
+    with open(version_file, "r") as vf:
+        lines = vf.read()
+        version = re.search(r"^_*version_* = ['\"]([^'\"]*)['\"]", lines, re.M).group(1)
+        return version
+
+
+fruitbat_version = get_version()
+
 # The short X.Y version
-version = '1.0.1'
+version = fruitbat_version
 # The full version, including alpha/beta/rc tags
-release = '1.0.1'
+release = fruitbat_version
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,23 +2,51 @@
 
 Fruitbat Documentation
 ----------------------
-**Fruitbat** is an open source Python package designed to assist the estimation of redshifts, 
+``Fruitbat`` is an open source Python package designed to assist the estimation of redshifts, 
 energies and the galactic dispersion measure contributions of fast radio bursts.
 
-**Fruitbat** generates and utilises 'look-up' tables of existing dispersion measure-redshift relations
-found in the literature (`Ioka 2003`_, `Inoue 2004`_, `Zhang 2018`_) in conjunction with parameters 
-from both the WMAP and Planck missions. **Fruitbat** also utilised the YMW16 galactic dispersion measure model
-to estimate the dispersion measure contribution due to the Milky Way.
+``Fruitbat`` generates and utilises 'look-up' tables of existing dispersion 
+measure-redshift relations found in the literature (`Ioka 2003`_, `Inoue 2004`_, 
+`Zhang 2018`_) in conjunction with parameters from both the WMAP and Planck 
+missions. ``Fruitbat`` also utilises the YMW16 galactic dispersion measure model
+to estimate the dispersion measure contribution due to the Milky Way. However it
+is also possible to use the NE2001 model if the python port has been installed
+(See the `NE2001 installation instructions`_).
 
 As a user you can independantly choose the dispersion measure-reshift relation 
 and the cosmological parameters, or define your own relation, create new cosmologies and
-generate custom look-up tables for **fruitbat**.
-
-**Fruitbat** is installable via ``pip`` (see `Getting Started`_) or the source code is made avaliable here_.
+generate custom look-up tables for ``fruitbat``.
+
+``Fruitbat`` is installable via ``pip`` (see `Getting Started`_) or the source code is made avaliable here_.
+
+If you use **Fruitbat** in your research, please add the acknowledgement statement
+"Some of the results of this paper have been derived using the ``fruitbat`` package"
+and cite the JOSS paper.
+
+.. code-block:: none
+
+    @ARTICLE{2019JOSS....4.1399B,
+           author = {{Batten}, Adam},
+            title = "{Fruitbat: A Python Package for Estimating Redshifts of Fast Radio Bursts}",
+          journal = {The Journal of Open Source Software},
+         keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - High Energy Astrophysical Phenomena},
+             year = "2019",
+            month = "May",
+           volume = {4},
+           number = {37},
+            pages = {1399},
+              doi = {10.21105/joss.01399},
+    archivePrefix = {arXiv},
+           eprint = {1905.04294},
+     primaryClass = {astro-ph.IM},
+           adsurl = {https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1399B},
+          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+    }
 
 .. _here: https://github.com/abatten/fruitbat
 .. _PyPI: https://pypi.org/project/fruitbat
 .. _Getting Started: https://fruitbat.readthedocs.io/en/latest/user_guide/getting_started.html
+.. _NE2001 installation instructions: https://fruitbat.io/en/latest/user_guide/ne2001_installation.html
 
 .. toctree::
    :maxdepth: 2
@@ -32,6 +60,7 @@ generate custom look-up tables for **fruitbat**.
    :maxdepth: 2
 
    user_guide/faq
+   user_guide/ne2001_installation
    user_guide/guidelines
 
 

diff --git a/docs/source/user_guide/faq.rst b/docs/source/user_guide/faq.rst
@@ -8,4 +8,21 @@ potential names seemed to fit. So I decided to just name it after an animal.
 After searching through lists of Australian animals I remembered the family of
 fruitbats (grey-headed flying foxes) that live in the tree in the front of my house.
 Fruitbat had the letters FRB in order and their orange necks reminded me of waterfall
-plots so I decided to so with Fruitbat as the name.
+plots so I decided to go with the name Fruitbat.
+
+I'd rather use the NE2001 model. Is this compatible with Fruitbat?
+------------------------------------------------------------------
+Yes! However you will need to install the python port of the NE2001 model.
+You can find installation and usage instructions here_.
+
+Alternatively, you can calculate the galactic DM using any version of the NE2001 model
+first and then use that value for :attr:`~fruitbat.Frb.dm_galaxy`.
+
+.. code-block:: python
+
+    >>> ne2001_dm = 34.5
+    >>> import fruitbat
+    >>> FRB = fruitbat.Frb(dm=325, dm_galaxy=ne2001_dm, gl="32.4", gb="16.2")
+
+
+.. _here: https://fruitbat.io/en/latest/user_guide/ne2001_installation.html
diff --git a/docs/source/user_guide/guidelines.rst b/docs/source/user_guide/guidelines.rst
@@ -11,20 +11,25 @@ and cite the JOSS paper.
 
 .. code-block:: none
 
-    @article{Batten2019,
-        author = {{Batten}, A.~J.},
-        title = {{Fruitbat}: A Python Package for Estimating Redshifts of Fast Radio Bursts},
-        doi = {10.21105/joss.01399},
-        url = {http://dx.doi.org/10.21105/joss.01399},
-        year  = {2019},
-        month = {may},
-        publisher = {The Open Journal},
-        volume = {4},
-        number = {36},
-        pages = {1399},
-        journal = {JOSS}
+    @ARTICLE{2019JOSS....4.1399B,
+           author = {{Batten}, Adam},
+            title = "{Fruitbat: A Python Package for Estimating Redshifts of Fast Radio Bursts}",
+          journal = {The Journal of Open Source Software},
+         keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - High Energy Astrophysical Phenomena},
+             year = "2019",
+            month = "May",
+           volume = {4},
+           number = {37},
+            pages = {1399},
+              doi = {10.21105/joss.01399},
+    archivePrefix = {arXiv},
+           eprint = {1905.04294},
+     primaryClass = {astro-ph.IM},
+           adsurl = {https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1399B},
+          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
     }
 
+
 Issues and Contributing
 -----------------------
 If there is a feature of ``fruitbat`` that currently does not exist, but you

diff --git a/docs/source/user_guide/ne2001_installation.rst b/docs/source/user_guide/ne2001_installation.rst
@@ -0,0 +1,39 @@
+NE2001 Installation Instructions
+================================
+
+When you install ``fruitbat`` it automatically installs the YMW16 galactic 
+electron density model ``pyywm16`` from PyPi. However, if you have the python
+port of the NE2001 model by Ben Baror and JXP you can use it with ``fruitbat``
+to estimate the galactic contribution to dispersion measure.
+
+The python port that is compatible with ``fruitbat`` is found at: 
+https://github.com/FRBs/ne2001. 
+
+You will need to download and install the NE2001 model to use it.
+
+
+Installing the NE2001 model
+---------------------------
+
+.. code-block:: python
+
+    >>> git clone https://github.com/FRBs/ne2001
+    >>> cd ne2001
+    >>> pip install .
+
+Using the NE2001 model
+----------------------
+
+After installing the NE2001 model, it behaves exactly the same as the YNW16 model.
+To specify that you want to use the NE2001 model pass `"ne2001"` as a keyword in
+:meth:`~fruitbat.Frb.calc_dm_galaxy`.
+
+.. code-block:: python
+
+    >>> import fruitbat
+    >>> FRB190523 = fruitbat.Frb(760.8, gl="117.03", gb="44")
+    >>> dm_galaxy_ymw16 = FRB190523.calc_dm_galaxy(model="ymw16")
+    >>> dm_galaxy_ne2001 = FRB190523.calc_dm_galaxy(model="ne2001")
+    >>> print(dm_galaxy_ymw16, dm_galaxy_ne2001)
+    29.88017464 pc / cm3    36.87013932 pc / cm3
+
diff --git a/fruitbat/__init__.py b/fruitbat/__init__.py
@@ -4,6 +4,27 @@
 Fruitbat is a package designed to assist the estimation of redshifts, energies
 and the galactic dispersion measure of fast radio bursts.
 
+Authors: Adam J. Batten (@abatten)
+
+Short Description
+-----------------
+This is the ``fruitbat`` package, which allows for easy estimation of FRB
+quantities from observed parameters.
+
+A simple example calculate with ``fruitbat`` is to estimate the redshift of 
+a FRB from its dispersion measure.
+
+>>> import fruitbat
+>>> FRB180525 = fruitbat.FRB(388.1, gl="349", gb="50.7")
+>>> dm_milky_way = FRB180525.calc_dm_galaxy(model='ymw16')
+>>> frb_redshift = FRB180525.calc_redshift(method='Inoue2004', cosmology="Planck18")
+>>> print(frb_redshift, dm_milky_way)
+0.3646537633283661 30.56254087351872 pc / cm3
+
+There are more detailed guides for getting started with ``fruitbat`` in the 'Using Fruitbat' section of the online documentation.
+
+https://fruitbat.readthedocs.io/en/latest/user_guide/using_fruitbat.html
+
 """
 
 from __future__ import absolute_import, print_function, division
@@ -21,7 +42,7 @@
 from .__version__ import __version__
 
 __name__ = "fruitbat"
-__author__ = "Adam Batten (@abatten)"
+__author__ = ["Adam Batten (@abatten)", ]
 __all__ = ['Frb', 'methods', 'cosmologies', 'plot', 'table', 'utils',
            'catalogue', 'add_method', 'reset_methods', 
            'available_methods', 'add_cosmology', 'reset_cosmologies',

diff --git a/fruitbat/__version__.py b/fruitbat/__version__.py
@@ -1 +1 @@
-__version__ = '1.0.1'
+__version__ = '1.1.0'