Utility functions¶
A selection of useful functions used by the module.

B_field
(period, pdot)[source]¶ Function defining the polar magnetic field strength at the surface of the pulsar in gauss (Equation 5.12 of Lyne & GrahamSmith, Pulsar Astronmy, 2nd edition) with
\[B = 3.2\!\times\!10^{19} \sqrt{P\dot{P}}\]NaNs are returned for any negative period derivates, or NaN imput values.
Parameters: Returns: the magnetic field strength in gauss.
Return type:

B_field_pdot
(period, Bfield=10000000000.0)[source]¶ Function to get the period derivative from a given pulsar period and magnetic field strength using
\[\dot{P} = \frac{1}{P}\left( \frac{B}{3.2\!\times\!10^{19}} \right)^2\]Parameters: Returns: an array of period derivatives
Return type:

age_pdot
(period, tau=1000000.0, braking_idx=3.0)[source]¶ Function returning the period derivative for a pulsar with a given period and characteristic age, using
\[\dot{P} = \frac{P}{\tau(n  1)}\]Parameters:  period (list,
numpy.ndarray
) – the pulsar period in seconds  tau (float) – the characteristic age in years
 braking_idx (float) – the pulsar braking index (defaults to \(n=3\))
Returns: an array of period derivatives.
Return type:  period (list,

characteristic_age
(period, pdot, braking_idx=3.0)[source]¶ Function defining the characteristic age of a pulsar. Returns the characteristic age in years using
\[\tau = \frac{P}{\dot{P}(n1)}\]NaNs are returned for any negative period derivates, or NaN imput values.
Parameters: Returns: the characteristic age in years
Return type:

check_update
()[source]¶ Check if the ATNF Pulsar Catalogue has been updated compared to the version in the cache.
Returns: True if the cache can be updated. Return type: bool

condition
(table, expression, exactMatch=False)[source]¶ Apply a logical expression to a table of values.
Parameters:  table (
astropy.table.Table
orpandas.DataFrame
) – a table of pulsar data  expression (str,
ndarray
) – a string containing a set of logical conditions with respect to pulsar parameter names (also containing conditions allowed when accessing the ATNF Pulsar Catalogue), or a boolean array of the same length as the table.  exactMatch (bool) – set to true to exactly match some string comparison expressions, e.g., if asking for ‘ASSOC(SNR)’ and exactMatch is True then only pulsar with an association that is just ‘SNR’ will be returned, whereas if it is False then there could be multiple associations including ‘SNR’.
Returns: the table of values conforming to the input condition. Depending on the type of input table the returned table will either be a
astropy.table.Table
orpandas.DataFrame
.Return type: Example
Some examples of this might are:
 finding all pulsars with frequencies greater than 100 Hz
>>> newtable = condition(psrtable, 'F0 > 100')
2. finding all pulsars with frequencies greater than 50 Hz and period derivatives less than 1e15 s/s.
>>> newtable = condition(psrtable, '(F0 > 50) & (P1 < 1e15)')
 finding all pulsars in binary systems
>>> newtable = condition(psrtable, 'TYPE(BINARY)')
 parsing a boolean array equivalent to the first example
>>> newtable = condition(psrtable, psrtable['F0'] > 100)
 table (

death_line
(logP, linemodel='Ip', rho6=1.0)[source]¶ The pulsar death line. Returns the base10 logarithm of the period derivative for the given values of the period.
Parameters: Returns: a vector of period derivative values
Return type: Note
The death line models can be:
 ‘I’  Equation 3 of [ZHM]
 ‘Ip’  Equation 4 of [ZHM]
 ‘II’  Equation 5 of [ZHM]
 ‘IIp’  Equation 6 of [ZHM]
 ‘III’  Equation 8 of [ZHM]
 ‘IIIp’  Equation 9 of [ZHM]
 ‘IV’  Equation 10 of [ZHM]
 ‘IVp’  Equation 11 of [ZHM]
[ZHM] Zhang, Harding & Muslimov, ApJ, 531, L135L138 (2000), arXiv:astroph/0001341

ellipticity_to_q22
(ellipticity, Izz=1e+38)[source]¶ Convert a fiducial ellipticity \(\varepsilon\) of the pulsar to the equivalent \(l=m=2\) mass quadrupole \(Q_{22}\) using (see Equation A3 of [LVC]):
\[Q_{22} = \varepsilon I_{zz} \sqrt{\frac{15}{8\pi}}\]Parameters: Returns: an array of \(Q_{22}\) values.
Return type:

fdot_to_pdot
(fdot, period=None, frequency=None)[source]¶ Convert frequency derivatives to period derivatives. Either periods or frequencies must be supplied.
\[\dot{P} = \frac{\dot{f}}{f^2}\]Parameters: Returns: an array of period derivatives.
Return type:

get_catalogue
(path_to_db=None, cache=True, update=False, pandas=False)[source]¶ This function will attempt to download and cache the entire ATNF Pulsar Catalogue database tarball, or read in database file from a provided path. The database will be converted into an
astropy.table.Table
orpandas.DataFrame
. This was originally based on the method in the ATNF.ipynb notebook by Joshua Tan (@astrophysically).Parameters:  path_to_db (str) – if the path to a local version of the database file is given then that will be read in rather than attempting to download the file (defaults to None).
 cache (bool) – cache the downloaded ATNF Pulsar Catalogue file. Defaults to True. This is ignored if path_to_db is given.
 update (bool) – if True the ATNF Pulsar Catalogue will be redownloaded and cached if there has been a change compared to the currently cached version. This is ignored if path_to_db is given.
 pandas (bool) – if True the catalogue will be returned as a
pandas.DataFrame
rather than the default of anTable
.
Returns: a table containing the entire catalogue.
Return type:

get_gc_catalogue
()[source]¶ Download and parse Paolo Freire’s table of pulsars in globular clusters from http://www.naic.edu/~pfreire/GCpsr.txt. This will be returned as a
astropy.table.Table
, but with some additional methods to extract information for individual clusters. If the webpage returned an errorNone
is returned.The additional methods of the returned
Table
are:clusters
: by default this returns a list if the common names of the globular clusters in the table, or using thengc=True
argument will return the NGC names of all clusters.cluster_pulsars
: returns a subtable only containing pulsars within a supplied globular cluster name.

get_glitch_catalogue
(psr=None)[source]¶ Return a
Table
containing the Jodrell Bank pulsar glitch catalogue. If using data from the glitch catalogue then please cite Espinoza et al. (2011) and the URL http://www.jb.man.ac.uk/pulsar/glitches.html.The output table will contain the following columns:
 NAME: the pulsars common name
 JNAME: the pulsar name based on J2000 coordinates
 Glitch number: the number of the glitch for a particular pulsar in chronological order
 MJD: the time of the glitch in Modified Julian Days
 MJD_ERR: the uncertainty on the glitch time in days
 DeltaF/F: the fractional frequency change
 DeltaF/F_ERR: the uncertainty on the fractional frequency change
 DeltaF1/F1: the fractional frequency derivative change
 DeltaF1/F1_ERR: the uncertainty on the fractional frequency derivative change
 Reference: the glitch publication reference
Parameters: psr (str) – if a pulsar name is given then only the glitches for that pulsar are returned, otherwise all glitches are returned. Returns: a table containing the entire glitch catalogue. Return type: Table
Example
An example of using this to extract the glitches for the Crab Pulsar would be:
>>> import psrqpy >>> gtable = psrqpy.get_glitch_catalogue(psr='J0534+2200') >>> print("There have been {} glitches observed from the Crab pulsar".format(len(gtable))) 27

get_msp_catalogue
()[source]¶ Download and parse Dunc Lorimer’s catalogue of galactic millisecond pulsars. This makes use of code from the now deleted galmsps respository that scraped the database into JSON every month, contributed by @astrogewgaw before deletion via PR #88.
Returns: a table the MSPs. Return type: Table

get_references
(useads=False, cache=True, updaterefcache=False, bibtex=False, showfails=False)[source]¶ Return a dictionary of paper reference in the ATNF catalogue. The keys are the ref strings given in the ATNF catalogue.
Note: The way that the ATNF references are stored has changed, so if you downloaded the catalogue with a version of psrqpy before v1.0.8 you may need to run this function with
updaterefcache=True
to allow references to work. You may also want to update the ATNF catalogue tarball with:>>> import psrqpy >>> psrqpy.QueryATNF(checkupdate=True)
Parameters:  useads (bool) – boolean to set whether to use the python mod:ads module to get the NASA ADS URL for the references.
 cache (bool) – use cached, or cache, the reference bundled with the catalogue tarball.
 updaterefcache (bool) – update the cached references.
 bibtex (bool) – if using ADS return the bibtex for the reference along with the ADS URL.
 showfails (bool) – if outputting NASA ADS references set this flag to True to output the reference tags of references that fail to be found (mainly for debugging purposes).
Returns: a dictionary of references.
Return type:

gw_h0_spindown_limit
(frequency, fdot, distance, Izz=1e+38)[source]¶ The gravitationalwave amplutitude at Earth assuming all rotational energy loss is radiated via emission from an \(l=m=2\) mass quadrupole mode, using (see Equation A7 of [LVC])
\[h_0^{\text{sd}} = \frac{1}{d}\left(\frac{5}{2} \frac{G I_{zz}}{c^3} \frac{\dot{f}}{f}\right)^{1/2}\]Parameters: Returns: an array of spindown limits.
Return type: [LVC] (1, 2, 3, 4, 5, 6) Abbott et al, ApJ, 879, 28 (2019), arXiv:1902.08507

gw_luminosity
(h0, frequency, distance)[source]¶ The gravitationalwave luminosity as derived from a given gravitatonalwave amplitude measured at Earth, assuming all rotational energy loss is radiated via emission from an \(l=m=2\) mass quadrupole mode, using (see Equation A5 of [LVC])
\[\dot{E}_{\text{gw}} = \frac{8\pi^2c^3}{5G} f^2 h_0^2 d^2\]Parameters: Returns: an array of luminosities.
Return type:

h0_to_ellipticity
(h0, frequency, distance, Izz=1e+38)[source]¶ Convert a gravitationalwave amplitude \(h_0\) at Earth to an equivalent fiducial ellipticity \(\varepsilon\) of the pulsar using (see Equation A4 of [LVC]):
\[\varepsilon = h_0 \left(\frac{c^4 d}{16\pi^2 G f^2} \right) \sqrt{\frac{15}{8\pi}}\]Parameters: Returns: an array of \(Q_{22}\) values.
Return type:

h0_to_q22
(h0, frequency, distance)[source]¶ Convert a gravitationalwave amplitude \(h_0\) at Earth to an equivalent \(l=m=2\) mass quadrupole \(Q_{22}\) of the pulsar using (see Equations A3 and A4 of [LVC]):
\[Q_{22} = h_0 \left(\frac{c^4 d}{16\pi^2 G f^2} \right) \sqrt{\frac{15}{8\pi}}\]Parameters: Returns: an array of \(Q_{22}\) values.
Return type:

label_line
(ax, line, label, color='k', fs=14, frachoffset=0.1)[source]¶ Add an annotation to the given line with appropriate placement and rotation.
Based on code from “How to rotate matplotlib annotation to match a line?” and this answer.
Parameters:  ax (
matplotlib.axes.Axes
) – Axes on which the label should be added.  line (
matplotlib.lines.Line2D
) – Line which is being labeled.  label (str) – Text which should be drawn as the label.
 color (str) – a color string for the label text. Defaults to
'k'
 fs (int) – the font size for the label text. Defaults to 14.
 frachoffset (float) – a number between 0 and 1 giving the fractional offset of the label text along the xaxis. Defaults to 0.1, i.e., 10%.
Returns: an object containing the label information
Return type:  ax (

pdot_to_fdot
(pdot, period=None, frequency=None)[source]¶ Convert period derivatives to frequency derivatives. Either periods or frequencies must be supplied.
\[\dot{f} = \frac{\dot{P}}{P^2}\]Parameters: Returns: an array of frequency derivatives.
Return type:

q22_to_ellipticity
(q22, Izz=1e+38)[source]¶ Convert a \(l=m=2\) mass quadrupole \(Q_{22}\) to an equivalent fiducial ellipticity \(\varepsilon\) of the pulsar using (see Equation A3 of [LVC]):
\[\varepsilon = \frac{Q_{22}}{I_{zz}}\sqrt{\frac{8\pi}{15}}\]Parameters: Returns: an array of \(\varepsilon\) values.
Return type: