A variety of changes including far better docs - ref #4

README.md

@@ -5,6 +5,8 @@ It is inspired by, and has some minor similarities to, the [`ads`](https://ads.r
 [NASA ADS](https://ui.adsabs.harvard.edu/) [API](https://github.com/adsabs/adsabs-dev-api). It is an unofficial
 package and is not endorsed by or affiliated with the ATNF.
 
+Full documentation of the module can be found [here](http://psrqpy.readthedocs.io/).
+
 Any comments or suggestions are welcome.
 
 ## Installation

docs/source/conf.py

@@ -59,10 +59,12 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+from psrqpy import __version__ as vsr 
+
 # The short X.Y version.
-version = u'0.2.1'
+version = vsr
 # The full version, including alpha/beta/rc tags.
-release = u'0.2.1'
+release = vsr
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -179,7 +181,7 @@
 #html_domain_indices = True
 
 # If false, no index is generated.
-html_use_index = False
+#html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -307,5 +309,6 @@
                        'matplotlib': ('http://matplotlib.org/', None),
                        'astropy': ('http://docs.astropy.org/en/latest/', None),
                        'requests': ('http://docs.python-requests.org/en/master/', None),
-                       'ads': ('https://ads.readthedocs.io/en/latest/', None)}
+                       'ads': ('https://ads.readthedocs.io/en/latest/', None),
+                       'bs4': ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', None)}
 

docs/source/index.rst

@@ -3,6 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. include:: <isonum.txt>
+
 .. _reference:
 
 The psrqpy package
@@ -23,6 +25,20 @@ the source code can be obtained from `here <https://github.com/mattpitkin/psrqpy
 with ``sudo`` if wanted to install system wide, and with the ``--user`` flag
 if just installing for an individual user.
 
+Requirements
+------------
+
+The requirements for installing the code are:
+
+ * :mod:`six`
+ * :mod:`requests`
+ * :mod:`bs4`
+ * :mod:`numpy`
+ * :mod:`astropy`
+ * :mod:`datetime`
+
+The :mod:`ads` module and :mod:`matplotlib` are optional requirement to get the full functionality.
+
 Examples
 ========
 
@@ -34,7 +50,7 @@ A simple example of a query is to get the 'JName' (pulsar name based on the J200
    >>> from psrqpy import QueryATNF
    >>> query = QueryATNF(params=['JName', 'F0'])
 
-where the parameter names are case insensitive. The returned :class:`psrqpy.QueryATNF` query will
+where the parameter names are case insensitive. The returned :class:`~psrqpy.search.QueryATNF` query will
 contain a dictionary keyed on the parameter names (converted
 to upper case), with the
 dictionary values being :class:`numpy.ndarray` arrays containing the parameter values. This can
@@ -58,9 +74,106 @@ ATNF catalogue, the value of which is printed in the above example.
 More complex queries
 --------------------
 
+**Setting conditions**
+
+You can set `logical conditions <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#condition>`_
+on the parameters that you query. Let's say you want the names of all pulsars with rotation frequencies between
+100 and 200 Hz, then you could do the following:
+
+    >>> from psrqpy import QueryATNF
+    >>> query = QueryATNF(params=['JName'], condition='F0 > 100 && F0 < 200')
+    >>> print(len(query))
+    82
+
+If you also wanted pulsars with this condition, but also in globular clusters, you could do
+
+    >>> query = QueryATNF(params=['JName'], condition='F0 > 100 && F0 < 200', assoc='GC')
+    >>> print(len(query))
+    33
+
+This is equivalent to having ``condition='F0 > 100 && F0 < 200 && assoc(GC)'``.
+
+**Save a query**
+
+You can save a query as a `pickled object <https://docs.python.org/3/library/pickle.html>`_ for later
+use, e.g., if using a previous ``query`` we had done:
+
+    >>> query.save('atnfquery.pkl')
+
+The we could reload this with
+
+   >>> oldquery = QueryATNF(loadfromfile='atnfquery.pkl')
+
+**Query specific pulsars**
+
+We might just want to get information on certain pulsars, such as the Crab pulsar (J0534+2200) and
+J0537-6910, then we could get their sky positions with:
+
+    >>> from psrqpy import QueryATNF
+    >>> query = QueryATNF(params=['RAJ', 'DECJ'], psrs=['J0534+2200', 'J0537-6910'])
+    >>> print(query.table())
+        RAJ      RAJ_ERR     DECJ     DECJ_ERR
+    ------------ ------- ------------ --------
+    05:34:31.973   0.005 +22:00:52.06     0.06
+    05:37:47.416    0.11 -69:10:19.88      0.6
+
+You can also access these pulsars using the :class:`psrqpy.pulsar.Pulsars` class. This
+will create a dictionary of :class:`psrqpy.pulsar.Pulsar` objects keyed on the pulsar
+names. The attributes of the :class:`~psrqpy.pulsar.Pulsar` objects are the parameters
+that have been retrieved by the query. But, the  :class:`~psrqpy.pulsar.Pulsar` objects
+themselves can query the ATNF catalogue if you request a parameter that they don't already
+contain. E.g., so first lets get the :class:`psrqpy.pulsar.Pulsars`:
+
+    >>> psrs = query.get_pulsars()
+    >>> for psr in psrs:
+    ...     print(psr)
+    J0534+2200
+    J0537-6910
 
+    >>> print(psrs['J0534+2200'].keys()) # show attributes of the psr class
+    ['DECJ', 'RAJ', 'DECJ_ERR', 'RAJ_ERR', 'JNAME']
 
-Contents:
+What if we want the frequency of J0534+2200? Well we just have to do
+
+    >>> crab = psrs['J0534+2200']
+    >>> print(crab.F0)
+    29.946923
+
+We can also get the whole ephemeris for the Crab with
+
+    >>> print(crab.get_ephemeris())
+    PSRJ            J0534+2200
+    PSRB            B0531+21
+    NAME            B0531+21
+    RAJ             05:34:31.973             5.000e-03
+    DECJ            +22:00:52.06             6.000e-02
+    ELONG           84.10
+    ELAT            -1.29
+    DM              56.77118                 2.400e-04
+    PEPOCH          48442.5
+    F0              29.946923                1.000e-06
+    F1              -3.77535E-10             2.000e-15
+    P0              0.0333924123             1.200e-09
+    P1              4.20972E-13              3.000e-18
+    DIST_DM         1.31
+    ...
+
+**Make a P-Pdot diagram**
+
+You can generate a *lovely* period vs. period derivative diagram based on the latest catalogue information
+using the :func:`~psrqpy.search.ppdot` function in just three lines of code:
+
+    >>> from psrqpy import QueryATNF
+    >>> query = QueryATNF(params=['P0', 'P1', 'ASSOC', 'BINARY', 'TYPE', 'P1_I'])
+    >>> query.ppdot(showSNRs=True, showtypes='all')
+
+where this shows all pulsar types and pulsars in supernova remnants, to give
+
+.. figure::  images/ppdot.png
+   :align:   center
+
+API interface
+=============
 
 .. toctree::
    :maxdepth: 2
@@ -70,6 +183,27 @@ Contents:
    config
    utils
 
+
+Copyright and referencing for the catalogue
+-------------------------------------------
+
+Regarding the use of the catalogue and software behind it, the `following statements <http://www.atnf.csiro.au/research/pulsar/psrcat/download.html>`_ apply:
+
+    PSRCAT is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. PSRCAT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+    PSRCAT makes use of "evaluateExpression: A Simple Expression Evaluator". Copyright |copy| 1996 - 1999 Parsifal Software, All Rights Reserved.
+
+    The programs and databases remain the property of the Australia Telescope National Facility, CSIRO, and are covered by the `CSIRO Legal Notice and Disclaimer <http://www.csiro.au/en/About/Footer/Legal-notice>`_.
+
+    If you make use of information from the ATNF Pulsar Catalogue in a publication, we would appreciate acknowledgement by reference to the publication "`The ATNF Pulsar Catalogue <http://adsabs.harvard.edu/abs/2005AJ....129.1993M>`_", R. N. Manchester, G. B. Hobbs, A. Teoh & M. Hobbs, Astronomical Journal, 129, 1993-2006 (2005) and by quoting the web address http://www.atnf.csiro.au/research/pulsar/psrcat for updated versions.
+
+Copyright & license for psrqpy
+------------------------------
+
+This code is licensed under the `MIT License <http://opensource.org/licenses/MIT>`_.
+
+|copy| Matt Pitkin, 2017
+
 References
 ----------
 

psrqpy/__init__.py

@@ -2,7 +2,7 @@
 
 """ A Python tool for interacting with the ATNF pulsar catalogue """
 
-__version__ = "0.2.1"
+__version__ = "0.3.1"
 
 from .search import QueryATNF
 from .pulsar import Pulsar, Pulsars

psrqpy/config.py

@@ -116,7 +116,7 @@
 PSR_DERIVED_PARS = PSR_DERIVED.keys()
 
 # a list of all allowed parameters for querying
-
+PSR_ALL = dict(itertools.chain(PSR_GENERAL.items(), PSR_TIMING.items(), PSR_BINARY.items(), PSR_DERIVED.items()))
 """: a dict of allowed pulsars parameters (e.g., name, position, distance...)
 
 Each parameter name key gives a dictionary containing the keys:
@@ -131,10 +131,9 @@
 The allowed parameters and their units are given
 `here <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#par_list>`_.
 """
-PSR_ALL = dict(itertools.chain(PSR_GENERAL.items(), PSR_TIMING.items(), PSR_BINARY.items(), PSR_DERIVED.items()))
+
 PSR_ALL_PARS = PSR_GENERAL_PARS + PSR_TIMING_PARS + PSR_BINARY_PARS + PSR_DERIVED_PARS
 
-#: `"types" <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types>`_ of pulsar for use in ``type()`` when setting logical conditions
 PSR_TYPES = ['AXP',           # Anomalous X-ray Pulsar or Soft Gamma-ray Repeater with detected pulsations
              'BINARY',        # Pulsar has one or more stellar companion(s)
              'HE',            # Spin-powered pulsar with pulsed emission from radio to infrared or higher frequencies
@@ -143,14 +142,20 @@
              'RRAT',          # Pulsars with intermittently pulsed radio emission
              'XINS'           # Isolated neutron stars with pulsed thermal X-ray emission but no detectable radio emission
              ]
+""": `types <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types>`_ of
+pulsar for use in ``type()`` when setting logical conditions.
+"""
 
-#: binary companion `types <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#bincomp_type>`_ for use in ``bincomp()`` when setting logical conditions
 PSR_BINARY_TYPE = ['MS',      # Main-sequence star
                    'NS',      # Neutron star
                    'CO',      # CO or ONeMg White Dwarf
                    'He',      # Helium White Dwarf
                    'UL'       # Ultra-light companion or planet (mass < 0.08 solar masses)
                   ]
+""": binary companion
+`types <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#bincomp_type>`_
+for use in ``bincomp()`` when setting logical conditions.
+"""
 
 #: other objects associated with the pulsar (this is not an exhaustive list for use in ``assoc()`` when setting logical conditions)
 PSR_ASSOC_TYPE = ['GC',  # globular cluster

psrqpy/pulsar.py

@@ -1,5 +1,6 @@
 """
-classes defining pulsar objects
+The classes defined here are hold information on an individual pulsar
+or an interable list of pulsars.
 """
 
 from __future__ import print_function, division
@@ -72,12 +73,12 @@ def __getitem__(self, key):
         ukey = key.upper()
         pulsarname = self.name
 
-        param = getattr(self, key, None) # try to get value, and default to None if not present
-
-        if not param:
-            param = getattr(self, ukey, None) # try uppercase version
-
-        if not param:
+        param = None
+        if key in self.__dict__:
+            return self.__dict__[key]
+        elif ukey in self.__dict__:
+            return self.__dict__[ukey]
+        else:
             if ukey[-4:] == '_ERR': # an error parameter
                 tkey = ukey[:-4] # parameter name without error
             else:
@@ -185,8 +186,6 @@ def set_ephemeris(self, ephem=None):
         # get ephemeris values
         ephemvals = [ev.split() for ev in ephem.split('\n') if len(ev.split()) > 1]
 
-        print(ephemvals)
-
         for ev in ephemvals:
             if ev[0].upper() in PSR_ALL_PARS and not hasattr(self, ev[0].upper()):
                 if PSR_ALL[ev[0].upper()]['format'][0] == 'S': # string type

psrqpy/search.py

@@ -791,13 +791,14 @@ def ppdot(self, intrinsicpdot=False, excludeGCs=False, showtypes=[], showGCs=Fal
         if not rcparams:
             # set default parameters
             rcparams = {
-                'figure.figsize': (8, 10),
+                'figure.figsize': (10, 12),
+                'figure.dpi': 250,
                 'text.usetex': True,    # use LaTeX for all text
                 'axes.linewidth': 0.5,  # set axes linewidths to 0.5
                 'axes.grid': False,     # add a grid
                 'font.family': 'sans-serif',
                 'font.sans-serif': 'Avant Garde, Helvetica, Computer Modern Sans serif',
-                'font.size': 15,
+                'font.size': 18,
                 'legend.fontsize': 'medium',
                 'legend.frameon': False}
 
@@ -977,10 +978,10 @@ def ppdot(self, intrinsicpdot=False, excludeGCs=False, showtypes=[], showGCs=Fal
 
         # add text for characteristic age lines and magnetic field strength lines
         for l in tlines:
-            ttext = label_line(ax, tlines[l], l, color='k', fs=16, frachoffset=0.05)
+            ttext = label_line(ax, tlines[l], l, color='k', fs=18, frachoffset=0.05)
 
         for l in Blines:
-            ttext = label_line(ax, Blines[l], l, color='k', fs=16, frachoffset=0.90)
+            ttext = label_line(ax, Blines[l], l, color='k', fs=18, frachoffset=0.90)
 
         # return the figure
         return fig

psrqpy/utils.py

@@ -329,7 +329,7 @@ def death_line(logP, linemodel='Ip', rho6=1.):
     Args:
         logP (list, :class:`~numpy.ndarray`): the base-10 log values of period.
         linemodel (str): a string with one of the above model names. Defaults to ``'Ip'``.
-        rho6 (float): the value of the :math:`\rho_6` parameter from [ZHM]_ . Defaults to 1 is,
+        rho6 (float): the value of the :math:`\\rho_6` parameter from [ZHM]_ . Defaults to 1 is,
             which is equivalent to :math:`10^6` cm.
 
     Returns: