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.
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
or in a Conda environment using:
conda install -c conda-forge psrqpy
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.
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
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.
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.
Regarding the use of the catalogue and software behind it, the following statements 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 © 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.
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", 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.
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}
}
This code is licensed under the MIT License.
© Matt Pitkin, 2017