# 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 & Graham-Smith, 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: period (float) – a pulsar period (s) pdot (float) – a period derivative the magnetic field strength in gauss. float
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: period (list, ndarray) – a list of period values Bfield (float) – the polar magnetic field strength (Defaults to $$10^{10}$$ G) an array of period derivatives numpy.ndarray
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$$) an array of period derivatives. numpy.ndarray
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}(n-1)}$

NaNs are returned for any negative period derivates, or NaN imput values.

Parameters: period (float, array_like) – the pulsar period in seconds pdot (float, array_like) – the pulsar period derivative braking_idx (float) – the pulsar braking index (defaults to $$n=3$$) the characteristic age in years float
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. bool
condition(table, expression, exactMatch=False)[source]

Apply a logical expression to a table of values.

Parameters: table (astropy.table.Table or pandas.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’. 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 or pandas.DataFrame.

Example

Some examples of this might are:

1. 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 1e-15 s/s.

>>> newtable = condition(psrtable, '(F0 > 50) & (P1 < 1e-15)')

1. finding all pulsars in binary systems
>>> newtable = condition(psrtable, 'TYPE(BINARY)')

1. parsing a boolean array equivalent to the first example
>>> newtable = condition(psrtable, psrtable['F0'] > 100)

death_line(logP, linemodel='Ip', rho6=1.0)[source]

The pulsar death line. Returns the base-10 logarithm of the period derivative for the given values of the period.

Parameters: logP (list, 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 $$\rho_6$$ parameter from [ZHM] . Defaults to 1 is, which is equivalent to $$10^6$$ cm. a vector of period derivative values numpy.ndarray

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, L135-L138 (2000), arXiv:astro-ph/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: ellipticity (list, ndarray) – a list of ellipticity values. Izz (float) – the moment of inertia of the principle axis (defaults to 1e38 kg m2). an array of $$Q_{22}$$ values. numpy.ndarray
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: fdot (list, ndarray) – a list of frequency derivative values. period (list, ndarray) – a list of periods (seconds) frequency (list, ndarray) – a list of frequencies (Hz) an array of period derivatives. numpy.ndarray
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 or pandas.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 re-downloaded 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 an Table. a table containing the entire catalogue.
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 error None 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 the ngc=True argument will return the NGC names of all clusters.
• cluster_pulsars: returns a sub-table 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. a table containing the entire glitch catalogue. 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. 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). a dictionary of references. dict
gw_h0_spindown_limit(frequency, fdot, distance, Izz=1e+38)[source]

The gravitational-wave 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: frequency (list, ndarray) – a list of frequencies (Hz). fdot (list, ndarray) – a list of frequency derivatives (Hz/s). distance (list, ndarray) – a list of distances (kpc). Izz (float) – the moment of inertia along the principle axis (defaults to 1e38 kg m2). an array of spin-down limits. numpy.ndarray
 [LVC] (1, 2, 3, 4, 5, 6) Abbott et al, ApJ, 879, 28 (2019), arXiv:1902.08507
gw_luminosity(h0, frequency, distance)[source]

The gravitational-wave luminosity as derived from a given gravitatonal-wave 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: h0 (list, ndarray) – a list of gravitational-wave amplitudes. frequency (list, ndarray) – a list of frequencies (Hz). distance (list, ndarray) – a list of distances (kpc). an array of luminosities. numpy.ndarray
h0_to_ellipticity(h0, frequency, distance, Izz=1e+38)[source]

Convert a gravitational-wave 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: h0 (list, ndarray) – a list of gravitational-wave amplitudes. frequency (list, ndarray) – a list of frequencies (Hz). distance (list, ndarray) – a list of distances (kpc). Izz (float) – the moment of inertia of the principle axis (defaults to 1e38 kg m2). an array of $$Q_{22}$$ values. numpy.ndarray
h0_to_q22(h0, frequency, distance)[source]

Convert a gravitational-wave 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: h0 (list, ndarray) – a list of gravitational-wave amplitudes. frequency (list, ndarray) – a list of frequencies (Hz). distance (list, ndarray) – a list of distances (kpc). an array of $$Q_{22}$$ values. numpy.ndarray
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 x-axis. Defaults to 0.1, i.e., 10%. an object containing the label information matplotlib.text.Text
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: pdot (list, ndarray) – a list of period derivative values. period (list, ndarray) – a list of periods (seconds) frequency (list, ndarray) – a list of frequencies (Hz) an array of frequency derivatives. numpy.ndarray
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: q22 (list, ndarray) – a list of mass quadrupole values (kg m2). Izz (float) – the moment of inertia of the principle axis (defaults to 1e38 kg m2). an array of $$\varepsilon$$ values. numpy.ndarray