mattpitkin/psrqpy repository overview

⁠PSRQpy

This module aims to provide a python interface for querying the ATNF pulsar catalogue⁠. It is an unofficial package and is not endorsed by or affiliated with the ATNF.

Full documentation of the module can be found here⁠.

Any comments or suggestions are welcome.

⁠Installation

To install the code from source, clone the git repository and run either:

python setup.py install --user

to install as a user, or

sudo python setup.py install

to install as root.

The module can also be installed using pip with:

pip install psrqpy

⁠Requirements

The requirements⁠ for installing the code are:

• six⁠
• requests⁠
• beautifulsoup4⁠
• numpy⁠
• scipy⁠
• astropy⁠ (for Python 2 astropy versions before 3.0⁠ must be used)
• pandas⁠

The ads⁠ module is an optional requirement that is needed to get ADS URLs for references, and matplotlib⁠ is required for making period-period derivative plots.

⁠Examples

A simple query of the catalogue to, e.g., just return all pulsar frequencies, would be:

import psrqpy

q = psrqpy.QueryATNF(params='F0')

# get frequencies as an astropy table
t = q.table

print(t['F0'])

You can query multiple parameters, e.g.:

import psrqpy

q = psrqpy.QueryATNF(params=['F0', 'F1', 'RAJ', 'DecJ'])

# get values as an astropy table
t = q.table

print(t['F0'])

You can query specific pulsars, e.g.:

import psrqpy

q = psrqpy.QueryATNF(params=['F0', 'F1', 'RAJ', 'DecJ'], psrs=['J0534+2200', 'J0537-6910'])

# get values as an astropy table
t = q.table

# print the table
print(t)
  JNAME          F0       F0_ERR       F1      F1_ERR     RAJ      RAJ_ERR     DECJ     DECJ_ERR
                 Hz         Hz       1 / s2    1 / s2                                           
---------- ------------- ------- ------------- ------ ------------ ------- ------------ --------
J0534+2200     29.946923   1e-06  -3.77535e-10  2e-15 05:34:31.973   0.005 +22:00:52.06     0.06
J0537-6910 62.0261895958 1.3e-09 -1.992272e-10  4e-17 05:37:47.416    0.11 -69:10:19.88      0.6

You can set conditions⁠ for the searches, e.g.:

import psrqpy
q = psrqpy.QueryATNF(params=['Jname', 'f0'], condition='f0 > 100 && f0 < 200', assoc='GC')

where assoc=GC looks for all pulsars in globular clusters.

When a query is generated the entire catalogue is downloaded and stored in the QueryATNF object as a pandas DataFrame⁠. The query can therefore be re-used to access data on different parameters, different pulsars, or using different conditions, without the need to re-download the catalogue. We may originally want to query pulsar frequencies using only frequencies greater than 10 Hz, with

import psrqpy
q = psrqpy.QueryATNF(params=['F0'], condition='F0 > 10')
freqs = q.table['F0']

Using the same QueryATNF object we could change to get frequency derivatives for pulsars with frequencies less than 10 Hz, with

q.condition = 'F0 < 10'
q.query_params = 'F1'

fdot = q.table['F1']

In these cases the whole catalogue (with no conditions applied and all available parameters) stored as a pandas DataFrame⁠ is accessible with

catalogue = q.catalogue

You can also generate⁠ a lovely period vs. period derivative plot based on the latest catalogue information, using just three lines of code, e.g.:

from psrqpy import QueryATNF
query = QueryATNF(params=['P0', 'P1', 'ASSOC', 'BINARY', 'TYPE', 'P1_I'])
query.ppdot(showSNRs=True, showtypes='all')

gives

⁠Development and Support

Code development is done via the package's GitHib repository⁠. Any contributions can be made via a fork and pull request⁠ model from that repository, and must adhere to the MIT license⁠. Any problems with the code or support requests can be submitted via the repository's Issue tracker⁠.

⁠Test suite

There are tests supplied that cover many of the functions within PSRQpy. These can be run from the base directory of the repository (after installing the pytest⁠ and pytest-socket⁠ modules, e.g., with pip) by just calling:

pytest

These tests are not included in the pip installed version of the code.

⁠Copyright and referencing for the catalogue

Regarding the use of the catalogue and software behind it, the following statements⁠ apply:

If making use of this code to access the catalogue, or produce plots, I would be grateful if (as well as citing the ATNF pulsar catalogue paper⁠ and URL⁠ given above) you consider citing the JOSS⁠ paper⁠ for this software:

@article{psrqpy,
  author = {{Pitkin}, M.},
   title = "{psrqpy: a python interface for querying the ATNF pulsar catalogue}",
  volume = 3,
  number = 22,
   pages = 538,
   month = feb,
    year = 2018,
 journal = "{Journal of Open Source Software}",
     doi = {10.21105/joss.00538},
     url = {https://doi.org/10.21105/joss.00538}
}

⁠License

This code is licensed under the MIT License⁠.

© Matt Pitkin, 2017